Docker

The templates ship a Dockerfile, a docker-entrypoint.sh and a docker-compose.prod.yml. Every other guide here is a wrapper around them, so this is the page that explains what is actually happening — useful whether you're on a VPS, on Fly, on Kubernetes, or debugging a one-click deploy that came up wrong.

Run it

docker build -t my-aphex .

docker run -d --name aphex -p 3000:3000 \
  -v aphex_data:/data \
  -e AUTH_SECRET="$(openssl rand -base64 48)" \
  -e AUTH_URL=https://cms.example.com \
  -e APHEX_SQLITE_URL=file:/data/aphex.db \
  -e APHEX_UPLOADS_DIR=/data/uploads \
  -e APHEX_EMBEDDED_WORKER=true \
  my-aphex

That is a complete production deploy: one container, one volume, no database service. The volume holds both the SQLite file and the uploaded media, which is why -v is not optional — without it, a docker run of the next image starts with an empty CMS.

Or with compose, which is the same thing with the variables written down:

docker compose -f docker-compose.prod.yml up -d --build

The build

Multi-stage, single-package, pnpm via corepack:

FROM node:22-alpine AS builder
RUN corepack enable
WORKDIR /app
COPY package.json pnpm-lock.yaml* svelte.config.js vite.config.ts tsconfig.json ./
RUN pnpm install --frozen-lockfile
COPY . .
RUN ADAPTER=node pnpm build
RUN pnpm prune --prod

FROM node:22-alpine AS runner
WORKDIR /app
ENV NODE_ENV=production PORT=3000
COPY --from=builder /app/build ./build
COPY --from=builder /app/node_modules ./node_modules
COPY --from=builder /app/package.json ./package.json
COPY --from=builder /app/drizzle ./drizzle
EXPOSE 3000
COPY docker-entrypoint.sh /app/docker-entrypoint.sh
RUN chmod +x /app/docker-entrypoint.sh
ENTRYPOINT ["/app/docker-entrypoint.sh"]

The runtime stage also removes the build toolchain and declares a HEALTHCHECK (both elided above). pnpm prune --prod does not remove the toolchain on its own, because it is reachable from production dependencies as peers: bits-ui and better-auth peer-depend on @sveltejs/kit, which peer-depends on Vite and TypeScript. So the runtime stage deletes them explicitly, along with Sharp's glibc libvips (the image is Alpine; only the musl build is ever loaded).

Two things worth knowing:

• ADAPTER=node selects @sveltejs/adapter-node so the build emits build/index.js. The template's svelte.config.js defaults to adapter-auto otherwise. If your platform runs pnpm build itself rather than building this Dockerfile, either set that variable in the platform's build config or make adapterNode() unconditional in svelte.config.js.
• The build needs no environment. Every server module guards its initialisation with building from $app/environment, so SvelteKit's analyse pass doesn't need a database or an auth secret. Real values are required at runtime only. (This was not always true — older template versions crashed the build without a .env.)

The entrypoint

docker-entrypoint.sh exists for one reason: the app has to know its own public URL, and on a managed platform nobody knows it until provisioning finishes.

adapter-node builds event.url from its own internal host:port unless ORIGIN says otherwise. Better Auth compares that origin against AUTH_URL and, on a mismatch, declines the request — and the decline lands on the API catch-all as a bare 404. The result is a deploy where the site renders, the admin loads, and sign-up returns a 404 with nothing in the log explaining why. It is the single most common way a first deploy fails.

So on boot the entrypoint:

1. Derives AUTH_URL from RENDER_EXTERNAL_URL, RAILWAY_PUBLIC_DOMAIN, APP_URL, COOLIFY_URL or FLY_APP_NAME, if you haven't set one. An explicit AUTH_URL always wins, and you should set one as soon as a custom domain exists — outgoing email links are built from it.
2. Sets ORIGIN to match, which is what adapter-node actually reads.
3. Refuses to start without AUTH_SECRET, rather than coming up publicly reachable with unsigned sessions.
4. Applies migrations, on Postgres only, then execs the server.

That last point is deliberate and easy to get wrong if you write your own entrypoint:

exec node build matters too: without it the shell stays PID 1, swallows SIGTERM, and every deploy waits out the platform's kill timeout before the container dies.

Escape hatches

Running as a non-root user

The server runs as node (uid 1000), not root. Getting there needs slightly more than a USER line, because the two requirements pull against each other:

• Kubernetes' restricted Pod Security Standard requires runAsNonRoot — a root image is rejected outright.
• Every platform in these guides mounts its volume owned by root, so a non-root process fails on first boot with EACCES: permission denied, mkdir '/data/uploads'. That's the failure Railway papers over with RAILWAY_RUN_UID=0, which hands root back and loses the point.

So the entrypoint starts as root, chowns only the paths it is about to write, then hands the server to node via su-exec. The chown is not recursive except on a directory it just created — a recursive pass over a media library is a slow, pointless cost on every restart.

If the container is started as non-root (runAsNonRoot, or docker run --user), the entrypoint detects it, skips the chown and execs directly. Volume ownership is then the orchestrator's job via fsGroup or an init container, which is the right division of responsibility.

What has to be on a volume

Two paths, and they default to inside the image:

APHEX_SQLITE_URL=file:/data/aphex.db   # the database
APHEX_UPLOADS_DIR=/data/uploads        # local media storage

Assets are stored with /media/:id/:filename URLs and resolved through the storage adapter, so moving APHEX_UPLOADS_DIR rewrites nothing in the database — but it doesn't move existing files either. Set it before the first upload, or copy the old directory across yourself while preserving its contents' relative layout. The template rebases persisted paths from its former ./static/uploads and ./uploads defaults to the current root. Remove the old static/uploads directory after copying so those files are not publicly served outside the access-controlled /media route.

If you're using S3-compatible storage (S3_*), only the database needs the volume, and on Postgres you need no volume at all.

Background jobs

APHEX_EMBEDDED_WORKER=true appears in the docker run line and in docker-compose.prod.yml above, and it is not decoration. It runs the job queue in-process — scheduled publishes, event consumers, anything a plugin enqueues.

Without it the queue fills and never drains. A scheduled publish is accepted, reports success, and then simply never happens. There is no error to find; the symptom is a post that didn't go live, noticed later.

APHEX_EMBEDDED_WORKER=true    # one container — the usual answer

Setup for both shapes, and how to verify the queue is actually draining: Operations → Background jobs.

Postgres instead

One variable and a connection string; no code change:

APHEX_DATABASE=postgres
DATABASE_URL=postgres://user:pass@host:5432/aphex?sslmode=require

Uncomment the db service in docker-compose.prod.yml to run it alongside, or point at a managed instance. The default pool is 10 — fine for a VPS, drop it for serverless.

With more than one container against the same database, migrate as a deploy step rather than on boot:

docker compose -f docker-compose.prod.yml run --rm app \
  node node_modules/@aphexcms/cms-core/dist/cli/index.js migrate

then set APHEX_SKIP_MIGRATE=true and APHEX_DB_AUTO_MIGRATE=false on the running containers.

Updating

git pull
docker compose -f docker-compose.prod.yml up -d --build app

Only the app rebuilds; the volume and any database service persist. Read CHANGELOG.md in the template repo before upgrading — the template is meant to be customized, so upstream changes aren't applied to your copy automatically, and the changelog is the list of what you may want to port.

Fly.io

Docker-friendly, so the bundled image drops straight in:

fly launch --dockerfile Dockerfile --no-deploy
fly volumes create aphex_data --size 5

Then in fly.toml:

[http_service]
  internal_port = 3000
  auto_stop_machines = false     # a volume pins this to one machine anyway

[[mounts]]
  source = "aphex_data"
  destination = "/data"

[env]
  APHEX_SQLITE_URL = "file:/data/aphex.db"
  APHEX_UPLOADS_DIR = "/data/uploads"
  APHEX_EMBEDDED_WORKER = "true"

[checks.health]
  type = "http"
  path = "/healthz"

fly secrets set AUTH_SECRET="$(openssl rand -base64 48)"
fly deploy

The entrypoint derives AUTH_URL from FLY_APP_NAME, so the .fly.dev hostname works without configuration. Set AUTH_URL explicitly once you attach your own domain.