Deploy
Run WebFrost in production with Docker Compose, a reverse proxy, TLS, a choice of database, backups and health checks.
A production deployment is the Docker image, one persistent volume, and a reverse proxy that terminates TLS. This page covers each piece. For a first try, use the Quickstart.
The image
The image is ghcr.io/gtkatakura/webfrost/server, built from packages/server/Dockerfile for linux/amd64 and linux/arm64:
| Stage | Base | What it does |
|---|---|---|
deps | oven/bun | Installs every workspace's dependencies once |
ui-builder | from deps | Builds the SDK and @webfrost/ui with Vite |
server-builder | from deps | Builds @webfrost/core and @webfrost/server into dist/ |
prod-deps | oven/bun | Installs only the server's production dependencies (jsdom, playwright) |
| runtime | oven/bun slim | Copies the server bundle, the UI assets and the production dependencies, installs Chromium (Playwright headless shell), yt-dlp and ffmpeg |
Base images are pinned by digest, and yt-dlp is a fixed release whose SHA-256 is checked during the build.
The runtime image:
- sets
WEBFROST_DIR=/dataand declares/dataas a volume; - exposes port 3000 and runs
bun run dist/index.js; - has a built-in
HEALTHCHECKagainst/health; - runs as the unprivileged user
webfrost(UID and GID 1000), with Chromium started without its own sandbox. The container is the sandbox: add no capabilities and mount nothing from the host except the data volume; - does not contain the
webfrostCLI. Create the admin user in the browser or withPOST /api/v1/setup.
Which tags exist
The release workflow builds the image when a v*.*.* tag is pushed or when it is dispatched manually, not on every merge to main. Tag pushes publish the semver tags (<version> and <major>.<minor>, without a leading v) and sha-<short-sha>. latest is published for each stable version tag (not for release candidates). Pin a version with IMAGE_TAG once releases exist, or build the image yourself (see below).
To build the image yourself:
docker build -f packages/server/Dockerfile -t webfrost-server .Docker Compose
The Compose file, compose.yml (docker-compose.prod.yml in the repository), is the recommended setup. Download it into an empty directory and start it:
mkdir webfrost && cd webfrost
curl -fsSLO https://webfrost.dev/compose.yml
[ -f .env ] || echo "SESSION_SECRET=$(openssl rand -hex 32)" > .env
docker compose up -dCompose substitutes ${VAR} from .env in the same directory. SESSION_SECRET is required; the rest are optional. From a clone of the repository, add -f docker-compose.prod.yml to every docker compose command.
| Compose variable | Default | Passed to the container as |
|---|---|---|
SESSION_SECRET | none, required | SESSION_SECRET |
PORT | 3000 | Host port only (the container always listens on 3000) |
IMAGE_TAG | latest | Image tag of ghcr.io/gtkatakura/webfrost/server |
WEBFROST_SETUP_TOKEN | empty | WEBFROST_SETUP_TOKEN |
WEBFROST_TRUST_PROXY | false | WEBFROST_TRUST_PROXY |
WEBFROST_CONCURRENCY | 3 | WEBFROST_CONCURRENCY |
TZ | UTC | TZ |
WEBFROST_PUBLIC_READ | false | WEBFROST_PUBLIC_READ |
WEBFROST_INSECURE_COOKIES | false | WEBFROST_INSECURE_COOKIES |
WEBFROST_ALLOW_PRIVATE_URLS | false | WEBFROST_ALLOW_PRIVATE_URLS |
WEBFROST_DOMAIN_DELAY_MS | 1000 | WEBFROST_DOMAIN_DELAY_MS |
WEBFROST_SCHEDULER | true | WEBFROST_SCHEDULER |
WEBFROST_LOG_LEVEL | info | WEBFROST_LOG_LEVEL |
DATABASE_URL | empty (SQLite) | DATABASE_URL, see Choosing a database |
WEBFROST_STORAGE_BACKEND, S3_* | filesystem | Storage |
OTEL_* | commented out | Uncomment them in compose.yml to use them: Observability |
Any other variable from Configuration needs a line of its own under the service's environment:.
The file also sets restart: unless-stopped and init: true (it reaps the Chromium and yt-dlp child processes), and defines a health check. To pin a release:
IMAGE_TAG=0.1.0 docker compose up -dA single docker run also works:
docker run -d -p 3000:3000 \
-e SESSION_SECRET=$(openssl rand -hex 32) \
-v webfrost_data:/data \
ghcr.io/gtkatakura/webfrost/server:latestUpdate
docker compose pull
docker compose up -dSnapshots that were pending when the old container stopped are re-queued automatically by the new one: a snapshot is adopted once its lease (45 seconds) has expired, at the next recovery sweep (every minute). See Pipeline.
Roll back
docker compose stop
IMAGE_TAG=<previous-version> docker compose up -d
curl http://localhost:3000/healthIf the release changed the database schema, restore a backup taken before the upgrade first.
Volumes
Always mount a volume at WEBFROST_DIR (/data in the image). Without one, every snapshot is lost when the container is removed. The directory holds archive.db and snapshots/.
The container runs as UID 1000, so /data must be writable by that user. A named volume (the compose default) is created with the right owner. A bind mount keeps the host's ownership, so change it first or the server cannot create archive.db:
mkdir -p ./data && sudo chown -R 1000:1000 ./data
docker run -d -p 3000:3000 -v "$PWD/data:/data" -e SESSION_SECRET=... ghcr.io/gtkatakura/webfrost/server:latestWith Podman in rootless mode, add --userns=keep-id:uid=1000,gid=1000 instead of chowning.
The database stores absolute paths to the files it saved, so keep the same mount point (/data) across restores and upgrades.
Choosing a database
WebFrost keeps its metadata (snapshots, results, the search index, schedules, users) in SQLite, PostgreSQL or MySQL. Archive files go to the storage backend in every case.
| Pick it when | |
|---|---|
| SQLite (default) | One host, any archive size you would keep on one disk. Nothing to set up, and a backup is a file copy or Litestream. |
| PostgreSQL 13+ | You already run PostgreSQL, want managed hosting, point-in-time recovery or replicas, or have many processes writing at once. |
| MySQL 8.0.13+ | You already run MySQL. |
SQLite needs no configuration. For the others set DATABASE_URL; WebFrost creates its tables on first start and migrates them on upgrades:
# PostgreSQL
DATABASE_URL=postgres://webfrost:[email protected]:5432/webfrost
# MySQL
DATABASE_URL=mysql://webfrost:[email protected]:3306/webfrostCREATE USER webfrost WITH PASSWORD 'secret';
CREATE DATABASE webfrost OWNER webfrost;Add ?sslmode=require to the URL for a server that expects TLS.
With Compose, put DATABASE_URL in .env; compose.yml passes it to the container. Every process that shares the archive (the server, a webfrost schedule worker, CLI commands) must use the same DATABASE_URL and storage settings. Search syntax and ranking differ slightly between engines; see full-text search.
Switching engines on a populated archive is not automatic: there is no built-in export from one database to another yet. Choose before you start archiving, or re-archive the URLs (webfrost import) into the new database.
Reverse proxy
WebFrost does not terminate TLS. Put nginx, Caddy or Traefik in front. A Caddyfile:
archive.example.com {
reverse_proxy localhost:3000
}Behind a proxy, set WEBFROST_TRUST_PROXY=true. Rate limits are keyed on the client address, which is the TCP peer by default, so without this every client shares the proxy's address and its limit. With it, the address comes from X-Forwarded-For. Proxies append the address they saw to whatever the client sent, so the server reads the header from the right: with one proxy (the default, WEBFROST_TRUSTED_PROXY_HOPS=1) it takes the last entry. With a CDN in front of the proxy, set WEBFROST_TRUSTED_PROXY_HOPS=2. Set WEBFROST_TRUST_PROXY only when the server is reachable through the proxy alone; a client that can connect directly can send any header it likes.
The proxy must pass the Host header through unchanged (Caddy and Traefik do; with nginx use proxy_set_header Host $host;). Browsers that send no Sec-Fetch-Site header are checked by comparing their Origin with Host, and a rewritten Host would make the server refuse their writes as cross-origin.
TLS and cookies
The session cookie is HttpOnly, SameSite=Strict and Secure. Browsers drop Secure cookies on plain-HTTP origins other than localhost, so signing in over http://192.168.1.10:3000 appears to work and then returns to the login page.
- Recommended: serve over HTTPS through the reverse proxy.
- HTTP-only LAN deployment: set
WEBFROST_INSECURE_COOKIES=trueto drop theSecureflag. Accept that cookies then travel in clear text.
Secrets
- Set
SESSION_SECRETfrom a secret manager or Docker secret, not a committed.env. It must be at least 32 random characters; rotating it signs everyone out. - Never set
AUTH_DISABLED=trueon a reachable server. With it the server binds to127.0.0.1unlessHOSTis set, so inside a container it is unreachable through a published port until you setHOST=0.0.0.0on purpose. - Keep
.envout of version control.
First-run setup
Until an admin exists, POST /api/v1/setup (the setup page) lets whoever reaches the server first become its admin, and the server logs a warning at every start while that is the case. Either finish setup before exposing the port, or set WEBFROST_SETUP_TOKEN:
docker run -d -p 3000:3000 \
-e SESSION_SECRET=$(openssl rand -hex 32) \
-e WEBFROST_SETUP_TOKEN=$(openssl rand -hex 16) \
-v webfrost_data:/data \
ghcr.io/gtkatakura/webfrost/server:latestThe setup page then asks for the token, and API calls must send it as X-Setup-Token or a setupToken field. With Compose, put WEBFROST_SETUP_TOKEN in .env; compose.yml passes it through. Once setup is done the token has no further use; remove it at the next restart if you like.
Shutdown
On SIGTERM or SIGINT (docker stop, a deploy) the server stops accepting requests and running schedules, then waits up to WEBFROST_SHUTDOWN_TIMEOUT_MS (default 20 seconds) for archive jobs in progress. Give the container at least that long before it is killed (docker stop -t 30, stop_grace_period: 30s in Compose). A job still running at the deadline stays pending and is re-queued by the next start.
Health check
curl http://localhost:3000/health
# {"status":"ok"}/health needs no authentication, so it suits load balancers and uptime monitors. The image and the Compose file already use it.
Backups
State lives in two places: the database (by default archive.db in WEBFROST_DIR: metadata, search index, schedules, sessions, API key hashes) and the archive files (snapshots/ in WEBFROST_DIR, or the S3 bucket). Back up both; the archive is only usable with its database. The quick recipes for SQLite are below; continuous replication with Litestream and pg_dump / mysqldump are in Backups.
Stop the container so nothing is writing, then archive the volume:
docker compose stop
docker run --rm -v webfrost_data:/data -v "$PWD":/backup alpine \
tar -czf "/backup/webfrost-$(date +%Y%m%d-%H%M%S).tar.gz" -C /data .
docker compose startCompose prefixes the volume name with the project name (the directory name by default); check with docker volume ls.
A separate schedule worker
The server runs schedules itself. You only need a worker if you want scheduled archiving in a different process, for example to keep it off the web server's resources. Disable the server's scheduler and run the CLI worker against the same data directory:
# server: .env
WEBFROST_SCHEDULER=false
# worker: the webfrost binary, same archive and storage settings
WEBFROST_DIR=/path/to/data webfrost schedule workerThe worker needs the same WEBFROST_DIR, TZ and storage variables as the server. The Docker image has no CLI, so run the worker with the webfrost binary on the same host or volume. Running both at once is safe, because a due schedule is claimed atomically and only one process runs it. See Scheduled archiving.
Hardening
Before the server is reachable by other people, work through Harden a deployment: secrets, setup token, proxy headers, egress, file permissions and backups.