Skip to content

environment.md

Latest commit

 

History

History
113 lines (91 loc) · 6.29 KB

environment.md

File metadata and controls

113 lines (91 loc) · 6.29 KB
Raw
title Environment Variables
description Configure SynapS3 with SYNAPS3 environment overrides and understand when to use them.

Environment Variables

Configuration environment variables use the SYNAPS3_ prefix and map underscores to config paths. They override file values and are a good place for deployment secrets and host-specific settings.

Common Overrides

Environment variable Config path
SYNAPS3_SERVER_PORT server.port
SYNAPS3_SERVER_MAX_CONNECTIONS server.max_connections
SYNAPS3_SERVER_MAX_REQUESTS server.max_requests
SYNAPS3_SERVER_TLS_ENABLED server.tls.enabled
SYNAPS3_SERVER_TLS_CERT_FILE server.tls.cert_file
SYNAPS3_SERVER_TLS_KEY_FILE server.tls.key_file
SYNAPS3_S3_REGION s3.region
SYNAPS3_FILECOIN_NETWORK filecoin.network
SYNAPS3_FILECOIN_RPC_URL filecoin.rpc_url
SYNAPS3_FILECOIN_PRIVATE_KEY filecoin.private_key
SYNAPS3_FILECOIN_WITH_CDN filecoin.with_cdn
SYNAPS3_FILECOIN_ALLOW_PRIVATE_NETWORKS filecoin.allow_private_networks
SYNAPS3_FILECOIN_DEFAULT_COPIES filecoin.default_copies
SYNAPS3_FILECOIN_OBSERVABILITY_INTERVAL filecoin.observability.interval
SYNAPS3_FILECOIN_OBSERVABILITY_TIMEOUT filecoin.observability.timeout
SYNAPS3_FILECOIN_OBSERVABILITY_CONCURRENCY filecoin.observability.concurrency
SYNAPS3_DATABASE_DRIVER database.driver
SYNAPS3_DATABASE_DSN database.dsn
SYNAPS3_DATABASE_MAX_OPEN_CONNS database.max_open_conns
SYNAPS3_DATABASE_MAX_IDLE_CONNS database.max_idle_conns
SYNAPS3_CACHE_DIR cache.dir
SYNAPS3_CACHE_MAX_SIZE_GB cache.max_size_gb
SYNAPS3_CACHE_EVICTION_POLICY cache.eviction_policy
SYNAPS3_CACHE_LRU_HIGH_WATERMARK_PERCENT cache.lru_high_watermark_percent
SYNAPS3_CACHE_LRU_LOW_WATERMARK_PERCENT cache.lru_low_watermark_percent
SYNAPS3_WORKER_UPLOAD_CONCURRENCY worker.upload.concurrency
SYNAPS3_WORKER_UPLOAD_POLL_INTERVAL worker.upload.poll_interval
SYNAPS3_WORKER_UPLOAD_MAX_RETRIES worker.upload.max_retries
SYNAPS3_WORKER_EVICTOR_CONCURRENCY worker.evictor.concurrency
SYNAPS3_WORKER_EVICTOR_POLL_INTERVAL worker.evictor.poll_interval
SYNAPS3_WORKER_EVICTOR_MAX_RETRIES worker.evictor.max_retries
SYNAPS3_WORKER_STORAGE_CLEANUP_CONCURRENCY worker.storage_cleanup.concurrency
SYNAPS3_WORKER_STORAGE_CLEANUP_POLL_INTERVAL worker.storage_cleanup.poll_interval
SYNAPS3_WORKER_STORAGE_CLEANUP_MAX_RETRIES worker.storage_cleanup.max_retries
SYNAPS3_LOGGING_LEVEL logging.level
SYNAPS3_LOGGING_FORMAT logging.format
SYNAPS3_LOGGING_S3_ACCESS_ENABLED logging.s3_access.enabled
SYNAPS3_LOGGING_S3_ACCESS_LEVEL logging.s3_access.level
SYNAPS3_ADMIN_ADDR admin.addr
SYNAPS3_ADMIN_TRUSTED_PROXIES admin.trusted_proxies
SYNAPS3_ADMIN_AUTH_ENABLED admin.auth.enabled
SYNAPS3_ADMIN_AUTH_USERNAME admin.auth.username
SYNAPS3_ADMIN_AUTH_SESSION_SECRET admin.auth.session_secret
SYNAPS3_ADMIN_AUTH_SESSION_TTL admin.auth.session_ttl

SYNAPS3_ADMIN_TRUSTED_PROXIES is a comma-separated list of IP or CIDR entries.

Advanced Generated Fields

Environment variable Config path
SYNAPS3_ADMIN_AUTH_PASSWORD_HASH admin.auth.password_hash

admin.auth.password_hash is normally generated by synaps3 init or synaps3 admin-auth reset-password. Do not hand-write it unless an external password-hash process owns Admin auth.

CLI and Container Path Variables

These variables do not map to TOML config fields.

Environment variable Purpose
SYNAPS3_DATA_DIR Runtime data directory used for automatic synaps3 init; defaults to /var/lib/synaps3.
SYNAPS3_CONFIG Config file used by CLI commands when --config is not set; the Compose example defaults it to /var/lib/synaps3/config.toml and allows override, and the entrypoint uses $SYNAPS3_DATA_DIR/config.toml when starting serve.
SYNAPS3_ADMIN_PASSWORD Admin password used only by CLI authentication. Prefer the no-echo terminal prompt or a protected secret source instead of placing it in shell history.

When to Use Environment Variables

Use environment variables for:

  • wallet private keys and database DSNs,
  • externally managed Admin session secrets,
  • container-only paths,
  • network-specific RPC URLs,
  • deployment-specific logging format,
  • temporary overrides during troubleshooting.

Use the TOML config file for stable settings that should survive process restarts and be visible in synaps3 admin settings get. Use SYNAPS3_DATA_DIR only for Docker entrypoint path control; use SYNAPS3_CONFIG when container-local commands should share the same config file.

Security Guidance

Warning

Keep wallet private keys, database credentials, Admin passwords, and Admin session secrets out of git, container images, and shell history.

  • Keep SYNAPS3_FILECOIN_PRIVATE_KEY in a secret manager, .env, or host environment. synaps3 init and synaps3 admin-auth reset-password generate admin.auth.session_secret; use SYNAPS3_ADMIN_AUTH_SESSION_SECRET only when deployment policy manages it outside TOML.
  • Treat SYNAPS3_DATABASE_DSN, SYNAPS3_ADMIN_PASSWORD, and SYNAPS3_ADMIN_AUTH_SESSION_SECRET as sensitive values. Use the CLI no-echo prompt for the Admin password whenever practical.
  • Keep .env, config.toml, and credential files at permission mode 0600.
  • Keep SYNAPS3_ADMIN_TRUSTED_PROXIES empty unless trusted proxies strip untrusted forwarded headers before requests reach SynapS3.
  • Do not commit .env, config.toml, local databases, cache data, or wallet material.
  • Keep filecoin.allow_private_networks = false unless private provider URLs are explicitly trusted.
  • Remember that environment-managed fields override file values; changing the file will not affect them until the environment changes.

Verify Effective Settings

synaps3 admin settings get

The output shows current values and whether settings writes are available.

After changing settings, restart SynapS3, check /healthz, and run this command again to confirm the effective values. Environment variables continue to override file values.