Configuration

S5W is configured with environment variables only — there are no configuration files. No variable is required to run the storage; signing in to the panel needs two — a login and a password.

Recommended start

docker compose

services:
  s5w:
    image: flytachi/s5w:latest
    ports:
      - "9090:9090"   # API and delivery
      - "9091:9091"   # admin panel
    environment:
      ADMIN_LOGIN: admin
      ADMIN_PASSWORD: ${S5W_ADMIN_PASSWORD}   # from .env next to the compose file
      PUBLIC_BASE_URL: https://files.example.com
      TIME_ZONE: Asia/Tashkent
      LOG_LEVEL: warning
    volumes:
      - s5w_data:/var/lib/s5w
    # The application stops first (up to 35 s), then PostgreSQL. Docker's default
    # 10 s is not enough: after a SIGKILL the database recovers on the next start.
    stop_grace_period: 45s
    restart: unless-stopped

volumes:
  s5w_data:

docker run

docker run -d --name s5w -p 9090:9090 -p 9091:9091 \
  -e ADMIN_LOGIN=admin -e ADMIN_PASSWORD="$S5W_ADMIN_PASSWORD" \
  -e PUBLIC_BASE_URL=https://files.example.com \
  -e TIME_ZONE=Asia/Tashkent \
  -e LOG_LEVEL=warning \
  -v s5w_data:/var/lib/s5w \
  --stop-timeout 45 \
  --restart unless-stopped \
  flytachi/s5w:latest

All variables

The panel variables (ADMIN_*, TRUSTED_PROXIES) are covered in detail on the Admin panel page, the resource variables (SERVER_*) on Resources and performance. The rest are below.

PUBLIC_BASE_URL

What it does. Sets the start of every address the service hands out itself: publicUrl and privateUrl of files, url of temporary links, addresses in the panel. Written with the scheme and without a trailing /: https://files.example.com.

If not set. The address is built from the incoming request: scheme, host and port. As long as clients reach the service directly, this works. Behind a proxy the result depends on which headers the proxy passes, and in the panel addresses are built from the panel’s domain — that is, they point to the wrong place. In that case the panel shows a warning.

When to set it. Always, if the service sits behind a proxy or the API has its own domain. Give the address where files are reachable from outside — the API domain, not the panel’s.

TIME_ZONE

What it does. The time zone in which the panel splits traffic statistics into days when the browser did not report its own. Usually the browser does, and the variable is a fallback.

What it does not change. The maintenance schedule (always in UTC), the time in logs and the time in API responses — there it carries an explicit offset (+00:00).

Value. A name from the time zone database: Europe/Moscow, Asia/Tashkent. An unknown name is silently replaced with UTC.

CACHE_DEFAULT_MAX_AGE and CACHE_PRIVATE_MAX_AGE

What they do. The max-age values in the Cache-Control header used when neither the folder nor the bucket has its own max-age. CACHE_DEFAULT_MAX_AGE — for the shared cache (public: browser and CDN), a day by default. CACHE_PRIVATE_MAX_AGE — for the private one (private: browser only), 0 by default: the browser asks again every time, and ETag makes such a request cheap.

When to change them. To change the default behaviour for all buckets at once. For a single bucket or folder it is easier to set the policy in the panel — it takes precedence over these variables. How exactly the header is built is on the Caching page.

LOG_LEVEL and LOG_OUTPUT

LOG_LEVEL — debug · info · warning · error. The default is info: start and stop of the parts, bucket creation, errors. For a production server warning is usually enough. An empty value turns the application logs off.

LOG_OUTPUT — auto · stdout · stderr · file. auto means stdout, which is exactly what docker logs and any container log collector pick up. file writes to files inside the container; under Docker this is usually not needed.

PostgreSQL and s6 supervisor logs go to the same container output regardless of these variables.

WINTER_KEY

What it does. The secret key that signs panel sessions and /t/… temporary links.

If not set. On the first start the key is generated and saved in the volume, in /var/lib/s5w/.runtime_secrets, and read from there on later starts. Same volume, same key. The first start’s log shows this as WINTER_KEY auto-generated.

If set. The value from the environment takes precedence over the one saved in the volume. Set it if you want to keep the key in a secrets store rather than in the volume, or if you bring the service up on a new volume and want old temporary links to keep working.

If changed. Every panel session and every temporary link issued in every bucket stops working. Files, access tokens and public links are not affected.

The /var/lib/s5w volume

/var/lib/s5w/
  postgresql/        PostgreSQL cluster — metadata
  buckets/           files, one directory per bucket
  staging/           unfinished chunked uploads
  .runtime_secrets   the generated WINTER_KEY

Mount one volume as a whole. It has no parts that can be moved out separately: buckets/ and staging/ must be on the same filesystem (a chunked upload finishes with a rename, which is atomic only within one filesystem), and the database without the files or the files without the database are useless.

Without a volume the container is disposable. The data ends up in the container layer and disappears when the container is recreated — and it is recreated on every image update and every change of variables.

A host directory instead of a named volume is fine: -v /srv/s5w:/var/lib/s5w. The directory must be on a local filesystem: PostgreSQL on network filesystems such as NFS is unreliable.

The PostgreSQL version is tied to the volume. Currently it is 18. If the image ever moves to a new major version, the cluster will need pg_upgrade — this will be described separately in the release notes.

Ports

The ports inside the container are fixed: 9090 — API and delivery, 9091 — the panel. For a different port outside, change only the publishing: -p 8080:9090. Behind a proxy on a shared docker network the ports need not be published at all — see Behind a reverse proxy.