Configuration
SwiftFS Core reads its configuration from SWIFTFS_* environment variables.
Sizes accept units (5GiB, 32MiB); durations accept Go's form (30s,
168h).
Required
| Variable | Notes |
|---|---|
SWIFTFS_DATABASE_URL | PostgreSQL connection URL |
SWIFTFS_ENCRYPTION_KEY | 32 random bytes, base64 (openssl rand -base64 32). Encrypts access-key secrets. Back it up. |
Storage
| Variable | Default | Notes |
|---|---|---|
SWIFTFS_STORAGE_PATH | ./data (/data in the image) | Where object data is written |
SWIFTFS_FSYNC | true | Sync every object to disk before acknowledging it. Only disable for throwaway environments. |
SWIFTFS_MAX_OBJECT_SIZE | 5 GiB | Largest single PutObject or CopyObject; larger objects use multipart |
SWIFTFS_MULTIPART_EXPIRY | 168h | Unfinished multipart uploads are aborted after this |
S3 API
| Variable | Default | Notes |
|---|---|---|
SWIFTFS_S3_ADDR | :9000 | Listen address |
SWIFTFS_PUBLIC_ENDPOINT | http://localhost:9000 | The S3 API's URL as clients reach it (scheme and host) |
SWIFTFS_REGION | us-east-1 | The region clients sign for |
SWIFTFS_S3_DOMAIN | Enables virtual-hosted addresses (bucket.<domain>); needs wildcard DNS and TLS | |
SWIFTFS_CORS_ORIGINS | Browser origins allowed on every bucket after the bucket's own rules, for a web console (comma-separated) | |
SWIFTFS_ROOT_ACCESS_KEY, SWIFTFS_ROOT_SECRET_KEY | Optional bootstrap credentials for the default account. Prefer per-account keys. | |
SWIFTFS_BODY_IDLE_TIMEOUT | 60s | Uploads and downloads that make no progress for this long are cut |
Protection
| Variable | Default | Notes |
|---|---|---|
SWIFTFS_RATE_LIMIT_RPS, _BURST | 0 (off) | Requests per second per access key |
SWIFTFS_ANON_RATE_LIMIT_RPS, _BURST | 50, 100 | Per client IP, for anonymous requests and CORS preflights |
SWIFTFS_TRUSTED_PROXIES | CIDRs allowed to set X-Forwarded-For | |
SWIFTFS_QUOTA_REFRESH | 30s | How long account limits and usage are cached |
Operations
| Variable | Default | Notes |
|---|---|---|
SWIFTFS_OPS_ADDR | :9100 | Health checks and metrics. Keep it private (for example 127.0.0.1:9100). |
SWIFTFS_AUTO_MIGRATE | true | Apply database migrations at start-up |
SWIFTFS_SHUTDOWN_TIMEOUT | 30s | How long in-flight requests get on shutdown |
SWIFTFS_LOG_LEVEL, SWIFTFS_LOG_FORMAT | info, json | text for human-readable logs |
Background work
| Variable | Default | Notes |
|---|---|---|
SWIFTFS_SCRUB_RATE | 32MiB | How fast stored data is re-read and verified, per second; 0 disables |
SWIFTFS_SCRUB_INTERVAL | 1m | Scrubber slice length |
SWIFTFS_RECONCILE_INTERVAL, SWIFTFS_ORPHAN_GRACE | 6h, 1h | Cleanup of orphaned data, stale temporary files and empty directories |
SWIFTFS_GC_INTERVAL, SWIFTFS_GC_GRACE | 1m, 5m | Removal of data no longer referenced, after a grace period |
SWIFTFS_USAGE_FLUSH_INTERVAL | 10s | How often request counters are written |
SWIFTFS_USAGE_ROLLUP_INTERVAL | 5m | How often hourly storage figures are computed |