One-click deploys
Templates that take a fresh account on Render, Railway or Fly.io to the LumiBase setup wizard: the CMS API and the Studio, served from one container on one origin, with PostgreSQL and Redis wired in and the secrets generated for you.
| Platform | What you click or type | Manual steps left |
|---|---|---|
| Render | The Deploy to Render button (render.yaml) | None before the wizard. |
| Railway | The LumiBase template, once it is published (railway.json, docker/railway-template-variables.json) | None before the wizard. The template itself is a one-time maintainer step — see Railway. |
| Fly.io | fly launch with fly.toml | Create Postgres and Redis, set two secrets — four commands. Fly generates no secrets. |
| Cloudflare | No button | Not one-click today — see Cloudflare. |
Render, Fly.io and the Railway template run the published image
ghcr.io/khuepm/lumibase-cms (see Hardened image),
so what they deploy is the signed, scanned release, not a build from your copy
of the repository. railway.json is the exception: a Railway service created
from the repository builds docker/Dockerfile from source — see
Railway for what that build lacks.
The templates need an image from the first release after 2.0.0: they rely on
the entrypoint deriving CORS_ALLOWED_ORIGINS, which 2.0.0 (today's latest)
does not do, so until that release is published a deploy stops at production
validation with CORS_ALLOWED_ORIGINS is required in production.
What every template sets up
| Variable | How it is provided |
|---|---|
JWT_SECRET, ENCRYPTION_KEY | Generated by the platform (Render, Railway) or by you with openssl (Fly). Never stored in the repository. ENCRYPTION_KEY reaches the server exactly as generated; the entrypoint never re-encodes it. |
DATABASE_URL, REDIS_URL | Wired from the platform's PostgreSQL and Redis. |
CORS_ALLOWED_ORIGINS | Not set by any template. Derived at boot from the platform's public URL (RENDER_EXTERNAL_URL, RAILWAY_PUBLIC_DOMAIN, FLY_APP_NAME) when unset. A value with no host, such as https://, counts as unset. |
LUMIBASE_REQUIRE_SETUP_TOKEN | true: the instance is on the internet before anyone sets it up, and without the token whoever reaches /setup first becomes the admin. |
DATABASE_SSL_MODE | disable, because each template connects over the platform's own private network. Set it to require with an external database. |
NODE_ENV, LUMIBASE_ENV, LUMIBASE_RUNTIME, PORT | production, production, docker, 1989. |
Production refuses to start without DATABASE_URL, REDIS_URL, JWT_SECRET,
ENCRYPTION_KEY and CORS_ALLOWED_ORIGINS, and refuses an ENCRYPTION_KEY
that is not standard, padded base64 of a 128, 192 or 256-bit key. The image
entrypoint (docker/scripts/entrypoint.mjs) applies the same checks before it
touches the database and exits naming the variable.
Not provisioned by any template: S3-compatible media storage, Meilisearch and
imgproxy. The instance boots and setup completes without them — /health reports
degraded until they exist — but uploads, search and image transforms need their
variables (S3_ENDPOINT, MEILISEARCH_HOST, IMGPROXY_URL, …), see
Environment variables.
After the deploy: the setup wizard
-
Open the service logs. Once the server answers, the entrypoint prints the URL:
text[entrypoint] Setup is pending. Open https://<your-app>/setup to create the first admin account. -
Copy the one-time token printed earlier in the same log:
text[lumibase-cms] SETUP_TOKEN=<token> -
Open
/setup, paste the token, and create the first admin. The Studio then lives under the admin path you choose there.
The token is printed once. If the log line is gone, see First-run setup for how to issue a new one.
Render
Unattended upgrades.
render.yamldeploys:latestand the image runs migrations on every start, so any restart after a new release — including a major one — upgrades the instance and migrates its database. Pin your copy:url: ghcr.io/khuepm/lumibase-cms:<version>. See Pin a version.
The Blueprint render.yaml creates a web service from the published image, a
Render Postgres 16 database and a Render Key Value instance (noeviction, which
the job queues need), all reachable only over Render's private network.
JWT_SECRET and ENCRYPTION_KEY use generateValue, which Render documents
as a base64-encoded 256-bit value. If a deploy stops with ENCRYPTION_KEY must be a base64-encoded 128, 192, or 256-bit AES key, nothing has been encrypted yet:
replace the value in the dashboard with the output of openssl rand -base64 32.
Plans: the web service uses starter because a free instance spins down when
idle, and with it the scheduler and queue workers this process runs. Change
plans in the dashboard or in your copy of render.yaml.
Railway
Unattended upgrades. Give the template's
lumibaseservice a release tag,ghcr.io/khuepm/lumibase-cms:<version>, never:latest: the image runs migrations on every start, so a restart after a major release would upgrade the instance unattended.
railway.json configures a service built from source with
docker/Dockerfile, with a /health deploy check. That is what Railway uses
when you create a service from the repository, and that build is not the
release image: it is not signed or Trivy-scanned, has no SBOM, and is built
without LUMIBASE_GIT_SHA, so /api/v1/system/version reports the commit as
unknown. It is built from whatever branch you connect. To run the signed
image instead, create the service from the Docker image, as the template does.
A Railway template — the button that also creates
Postgres and Redis and generates the secrets — is composed in Railway's template
editor and published from a Railway account; it cannot be read from the
repository. Until it is published, a maintainer creates it once:
- In the template editor, add the official Postgres and Redis services
and a service named
lumibasefrom the Docker imageghcr.io/khuepm/lumibase-cms:<version>, with a public domain. The public domain matters:CORS_ALLOWED_ORIGINSis derived fromRAILWAY_PUBLIC_DOMAINand is not a template variable. - Copy the variables from
docker/railway-template-variables.json. They use Railway's${{secret(…)}}functions, so every deploy generates its ownJWT_SECRETandENCRYPTION_KEY(the recipe produces a standard, padded base64 AES-256 key that the server accepts as-is; the repository's tests check it). - Publish, and add the template's button here and in the README.
To deploy without the template, create the same three services in a project and
set the same variables, generating the two secrets with openssl as for Fly.
Create the lumibase service from the Docker image to get the release image; a
service created from the repository uses railway.json and builds from source.
Fly.io
Unattended upgrades.
fly.tomldeploys:latestand the image runs migrations on every start, so afly deployor machine restart after a new release — including a major one — upgrades the app and migrates its database. Pin it in[build]:image = "ghcr.io/khuepm/lumibase-cms:<version>".
Fly has no deploy button, generates no secrets, and runs Postgres and Redis as separate resources. From an empty directory:
fly launch --from https://github.com/khuepm/lumibase --no-deploy
fly postgres create --name <app>-db
fly postgres attach <app>-db # sets the DATABASE_URL secret
fly redis create # prints a redis:// URL
fly secrets set REDIS_URL=<that URL> \
JWT_SECRET="$(openssl rand -base64 48)" \
ENCRYPTION_KEY="$(openssl rand -base64 32)"
fly deploy
With Fly Managed Postgres instead, set DATABASE_URL from its connection string
with fly secrets set, and if that string carries sslmode=require, also set
DATABASE_SSL_MODE=require.
fly.toml keeps one machine running (auto_stop_machines = "off"): a stopped
machine runs no scheduler or workers. It stops the app with SIGTERM, which the
server drains on; Fly's default SIGINT would end it mid-request. A deploy
without the secrets fails at once, naming them, before the database is touched.
CORS_ALLOWED_ORIGINS defaults to https://<app>.fly.dev; set it, or
LUMIBASE_PUBLIC_URL, when you add your own domain.
Cloudflare
There is no Deploy to Cloudflare button for LumiBase yet, and adding one to this repository would not work:
- The button deploys one Worker from one directory, and treats that directory as
the root of the new repository.
apps/cmsdepends on workspace packages that would not be there. - The CMS needs PostgreSQL through Hyperdrive. A Hyperdrive configuration points at an existing database, so the database itself cannot come from the button.
- The top-level configuration in
apps/cms/wrangler.tomlis the local development profile (LUMIBASE_DEV_AUTH = "true"). Deploying it as-is would publish an instance with development authentication. - The Studio is a separate Cloudflare Pages project on this target, and the button deploys Workers only.
Use the scripted path in Cloudflare Workers instead. A self-contained Worker template that a button can deploy is tracked as backlog B211.
Pin a version
Render and Fly point at latest, which follows the newest release, and the
image runs pending migrations whenever it starts: a platform restart after a
release is an upgrade nobody scheduled, and after a major release one that may
need the manual steps in its upgrade notes. The default stays latest because
the templates only work with an image that has the current entrypoint, and no
published release tag has it yet (see the note at the top).
For production, pin the release you tested — the line to change is
url: ghcr.io/khuepm/lumibase-cms:<version> in render.yaml,
image = "ghcr.io/khuepm/lumibase-cms:<version>" in fly.toml, or the image
of the Railway service — and change it deliberately, after reading the release's
upgrade notes; see Docker → Updating.