Deployment

Aphex is a SvelteKit app, so it deploys like any SvelteKit app. The two paths covered here are the ones actually shipping today: Docker on a VPS (with Cloudflare Tunnel for ingress) and Render.com (managed). The base template includes a Dockerfile and prod.docker-compose.yml already.

Other platforms (Vercel, Cloudflare Pages, Fly, Railway) should work — adapter-node makes Aphex portable — but they're untested in production by the maintainers. If you ship on one, please open a PR with notes.

Production checklist

Before your first deploy:

openssl rand -base64 48

Environment variables

# --- Database ----------------------------------------------
DATABASE_URL=postgres://user:pass@host:5432/dbname?sslmode=require
# Or split: PG_HOST, PG_PORT, PG_USER, PG_PASSWORD, PG_DATABASE

# --- Auth --------------------------------------------------
BETTER_AUTH_SECRET=<48+ bytes of randomness — never commit>
BETTER_AUTH_URL=https://cms.your-app.com           # public origin of the SvelteKit app
AUTH_TRUSTED_ORIGINS=https://cms.your-app.com,https://your-app.com

# AUTH_SECRET / AUTH_URL also work for backwards compat (and the
# bundled Dockerfile uses those names).

# --- Email (Resend in prod, Mailpit in dev) ----------------
RESEND_API_KEY=re_xxxxxxxxxxxxxxxxxxxxxxxx
RESEND_FROM=[email protected]                  # must be a verified sender

# --- Storage (any S3-compatible — optional, falls back to local) ---
R2_BUCKET=my-bucket
R2_ENDPOINT=https://<account>.r2.cloudflarestorage.com
R2_ACCESS_KEY_ID=...
R2_SECRET_ACCESS_KEY=...
R2_PUBLIC_URL=https://cdn.your-app.com             # what end-users see in <img src=…>

Optional but recommended

# Asset signing — short-lived signed URLs for cross-org sharing
ASSET_SIGNING_SECRET=<32+ random chars>

# Public org id — pinned in your frontend integration (see /docs/frontend)
PUBLIC_ORG_ID=<uuid of the org your public site reads from>

Docker (battle-tested)

The base template ships with a multi-stage Dockerfile and a prod.docker-compose.yml that runs the studio + Postgres together (with optional Cloudflare Tunnel for ingress so you don't need to expose ports or run a reverse proxy).

The Dockerfile builds with the workspace context and outputs the standard adapter-node bundle:

FROM node:20-alpine AS builder
RUN npm install -g pnpm
WORKDIR /app
# ... copy workspace, install, build ...

FROM node:20-alpine AS runner
WORKDIR /app/apps/studio
# ... copy build output + drizzle ...
EXPOSE 3000
CMD ["node", "build"]

The prod.docker-compose.yml adds Postgres with a healthcheck and a Cloudflare Tunnel sidecar:

services:
  postgres:
    image: postgres:16-alpine
    env_file: [.env.production]
    healthcheck:
      test: ['CMD-SHELL', 'pg_isready']
    volumes: [postgres_data:/var/lib/postgresql/data]

  studio:
    build:
      context: .
      dockerfile: Dockerfile
    env_file: [.env.production]
    depends_on:
      postgres:
        condition: service_healthy
    volumes:
      - ./storage:/app/apps/studio/storage   # local-storage persistence

  cloudflared:
    image: cloudflare/cloudflared:latest
    command: tunnel run
    environment:
      TUNNEL_TOKEN: ${CLOUDFLARE_TUNNEL_TOKEN}
    profiles: [cloudflare]

Bring it up

# First deploy
docker compose -f prod.docker-compose.yml --profile cloudflare up -d --build

# Run migrations against the running app
docker compose -f prod.docker-compose.yml exec studio pnpm db:migrate

# Tail logs
docker compose -f prod.docker-compose.yml logs -f studio

If you don't want Cloudflare Tunnel, drop the --profile cloudflare flag, expose port 3000 (or map it through), and front it with Caddy / Nginx / Traefik for TLS.

Local storage in Docker

The volumes mount in the compose file (./storage:/app/apps/studio/storage) keeps uploaded assets durable across container rebuilds. If you switch to R2 / S3, you can remove the volume — cms_assets rows still reference the old storageAdapter, so historical local files keep working through the mount.

Updating

git pull
docker compose -f prod.docker-compose.yml up -d --build studio
docker compose -f prod.docker-compose.yml exec studio pnpm db:migrate

The Postgres container won't rebuild — only the studio service is affected.

Render.com (battle-tested)

Render runs the same Docker image, with managed Postgres alongside.

Free vs Starter plan caveats

Render's free plan spins down after 15 minutes of inactivity. The first request after spin-down hits a cold start that can take 30–60 seconds — fine for occasional editing, painful for production. Use the Starter plan for anything customer-facing.

Migrations on deploy

Never run db:push against production — it can drop columns silently. Always commit a generated migration file:

Signed asset URLs

If you serve assets to multiple downstream apps that don't share the CMS's session, generate short-lived signed URLs instead of exposing API keys:

createCMSConfig({
	security: {
		assetSigningSecret: env.ASSET_SIGNING_SECRET // 32+ chars
	}
});

The /media/{id}/{filename}?sig=...&exp=... URL is HMAC-validated on every request. After expiry, it's a 403.

Health checks

The CMS exposes adapter health via databaseAdapter.isHealthy() and storageAdapter.isHealthy(). Wire them into a /healthz route:

import { json } from '@sveltejs/kit';

export const GET = async ({ locals }) => {
	const { databaseAdapter, storageAdapter } = locals.aphexCMS;
	const [db, storage] = await Promise.all([
		databaseAdapter.isHealthy(),
		storageAdapter.isHealthy()
	]);

	const ok = db && storage;
	return json({ ok, db, storage }, { status: ok ? 200 : 503 });
};

Point your platform's health probe at /healthz. Render watches HTTP 200 by default.

Backups

Three things to back up:

Documents are content + a hash; restoring Postgres restores everything including version history.

CDN / cache headers

The CMS's asset CDN sets Cache-Control: public, max-age=31536000, immutable because URLs are content-addressed (the id is unique per upload). For your public site's HTML, set sensible cache headers yourself — the CMS doesn't touch SvelteKit page responses.

For the published-data cache layer, see Configuration → cache. Pair with a CDN like Cloudflare in front of your origin and you've got two-tier caching for free.

Other platforms

These should work — the studio is a standard adapter-node SvelteKit app — but aren't tested in production by the maintainers:

• Vercel / Netlify — adapter-vercel exists; cold starts will hit Sharp's native binaries. Test asset uploads carefully.
• Cloudflare Pages / Workers — partial fit. The admin uses Sharp + Better Auth crypto + Postgres driver, all of which want Node. The pragmatic split: studio on a Node platform, public site on Pages, both reading the same DB.
• Fly.io / Railway — Docker-friendly platforms; the bundled Dockerfile should drop in. Probably fine.

If you ship on one of these, file an issue (or a docs PR) so we can fold real-world notes into this page.

See also