LumiBaseDocs

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.

PlatformWhat you click or typeManual steps left
RenderThe Deploy to Render button (render.yaml)None before the wizard.
RailwayThe 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.iofly launch with fly.tomlCreate Postgres and Redis, set two secrets — four commands. Fly generates no secrets.
CloudflareNo buttonNot 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

VariableHow it is provided
JWT_SECRET, ENCRYPTION_KEYGenerated 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_URLWired from the platform's PostgreSQL and Redis.
CORS_ALLOWED_ORIGINSNot 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_TOKENtrue: the instance is on the internet before anyone sets it up, and without the token whoever reaches /setup first becomes the admin.
DATABASE_SSL_MODEdisable, 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, PORTproduction, 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

  1. 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.
    
  2. Copy the one-time token printed earlier in the same log:

    text
    [lumibase-cms] SETUP_TOKEN=<token>
    
  3. 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.yaml deploys :latest and 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.

Deploy to Render

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 lumibase service 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:

  1. In the template editor, add the official Postgres and Redis services and a service named lumibase from the Docker image ghcr.io/khuepm/lumibase-cms:<version>, with a public domain. The public domain matters: CORS_ALLOWED_ORIGINS is derived from RAILWAY_PUBLIC_DOMAIN and is not a template variable.
  2. Copy the variables from docker/railway-template-variables.json. They use Railway's ${{secret(…)}} functions, so every deploy generates its own JWT_SECRET and ENCRYPTION_KEY (the recipe produces a standard, padded base64 AES-256 key that the server accepts as-is; the repository's tests check it).
  3. 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.toml deploys :latest and the image runs migrations on every start, so a fly deploy or 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:

bash
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/cms depends 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.toml is 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.

Last modified: 15/11/2026