Deployment

Aphex is a SvelteKit app using adapter-node, so it deploys like any Node web service: one process, one port, node build. What makes it easier to host than most CMSs is the default database — SQLite in a file — which means a complete production deploy can be one container with one mounted volume. No database to provision, nothing to wire together.

If you want it running in the next few minutes:

Which path

The real question is not which host, it's where your database and your uploaded media live. Everything else follows from that.

Choosing your database

Both adapters run the same cross-dialect conformance suite, so neither is missing features — but that is a statement about capability, and production is an operational question. The two come apart there:

Pick SQLite to try Aphex, for an internal tool, or for a site where a few seconds of downtime on deploy costs nothing. It is genuinely less to run and less to back up.

Pick Postgres for a site you would be paged about. Not because you will outgrow SQLite's capacity — most sites never would — but because zero-downtime deploys and real point-in-time recovery are the things you miss at the worst possible moment.

Switching later is one environment variable and no code change, so this is a reversible decision — but move media to a bucket before the first upload, because switching storage does not relocate files already written to disk.

The two configurations

APHEX_SQLITE_URL=file:/data/aphex.db
APHEX_UPLOADS_DIR=/data/uploads
APHEX_EMBEDDED_WORKER=true

APHEX_DATABASE=postgres
DATABASE_URL=postgres://user:pass@host:5432/dbname

S3_ENDPOINT=https://<account>.r2.cloudflarestorage.com
S3_BUCKET=my-bucket
S3_ACCESS_KEY_ID=…
S3_SECRET_ACCESS_KEY=…
S3_PUBLIC_URL=https://media.example.com

Both one-click paths ship a Postgres variant: Render has a second blueprint, Railway is two clicks and two variables. Details on either adapter: Database.

What a deploy actually needs

Four things. Every guide here is a variation on getting them right.

openssl rand -base64 48

APHEX_SQLITE_URL=file:/data/aphex.db
APHEX_UPLOADS_DIR=/data/uploads

APHEX_EMBEDDED_WORKER=true    # single container — the usual answer

Domains, origins and proxies

Three variables describe where the app lives. Most deploys only ever set the first.

ORIGIN is the one doing the real work. adapter-node does not know what hostname it is served on — it reconstructs event.url from ORIGIN, and falls back to its own localhost:3000 without one. Better Auth then compares that against AUTH_URL and declines on a mismatch, which surfaces as a bare 404 from the auth routes with nothing in the log naming the cause. The bundled entrypoint derives ORIGIN from AUTH_URL, so setting AUTH_URL correctly is normally the whole job.

Attaching a custom domain

Point DNS at the service, then set AUTH_URL to the new origin and redeploy:

AUTH_URL=https://cms.example.com

Protocol and host exactly, no trailing slash, no path. Do this even though the one-click deploy worked without it: the entrypoint's platform fallback returns the *.onrender.com / *.up.railway.app hostname, so until you change it, every password-reset and invitation email keeps linking people to the old address.

# wrong — drops the app's own origin
AUTH_TRUSTED_ORIGINS=https://www.example.com

# right
AUTH_TRUSTED_ORIGINS=https://cms.example.com,https://www.example.com

Behind a reverse proxy or tunnel

Caddy, nginx, Traefik, a Cloudflare Tunnel — the proxy terminates TLS and forwards plain HTTP to the container, so the app sees http on an internal port and would build the wrong origin for itself.

Set AUTH_URL to the public HTTPS origin and there is nothing else to do. Because ORIGIN is then explicit, adapter-node never consults the forwarded headers at all — so unlike a bare SvelteKit deploy, you do not need PROTOCOL_HEADER and HOST_HEADER, and forgetting them is not the cause of a 404 here:

AUTH_URL=https://cms.example.com     # what the browser sees, not the container port

The proxy still has to forward Host and the original protocol for logging and redirects to look right, which every default configuration already does. What it must not do is rewrite the path — the app expects to be served at the root of its origin, not under a subpath.

Before you go public

APHEX_SEED=false

APHEX_BOOTSTRAP_EMAIL=[email protected]   # only this address can claim it
# …or require a one-time code printed to the server log at first boot:
APHEX_BOOTSTRAP_CLAIM_CODE=true

Environment variables

The template's .env.example is the authoritative list and is grouped for this purpose: required, local defaults, optional. What follows is the production view of the same thing.

Required

BETTER_AUTH_SECRET / BETTER_AUTH_URL are accepted as aliases for backwards compatibility. AUTH_TRUSTED_ORIGINS (the CSRF allowlist, comma-separated) defaults to AUTH_URL; set it only when another origin calls this app's auth routes.

State

Object storage

All four of the first group must be set together — with any missing, the app silently stays on local disk.

Jobs, email, secrets

See also