Skip to Content

Deployment

Deploy applications generated by @puzzle-ui/create to production with Next.js, TanStack Start, React Router, or Basic React, using MongoDB, Cloudflare D1, or a custom database.

This guide takes a project generated by @puzzle-ui/create from local development to production. Work through Before you deploy first, then follow the section for your database and framework. Examples use npm; substitute your package manager's run command.

Before you deploy

Production secrets

The generated .env contains secrets for local development. Never commit it and never reuse its values in production. Generate new values for each environment and set them in your host's secret or environment-variable settings:

# AUTH_ENCRYPTION_KEY_HEX, AUTH_PASSWORD_PEPPER_HEX, and database passwords
openssl rand -hex 32

# AUTH_RATE_LIMIT_SECRET
openssl rand -base64 48
VariableProduction value
APP_ORIGINThe exact public origin, for example https://app.example.com. HTTPS is required outside localhost, and there must be no trailing slash.
AUTH_ENCRYPTION_KEY_HEX64 hex characters. Encrypts authenticator (MFA) secrets; existing MFA enrolments stop working if it changes.
AUTH_RATE_LIMIT_SECRETAt least 32 random characters.
TRUSTED_CLIENT_IP_HEADERA client IP header your host or proxy always overwrites, such as cf-connecting-ip on Cloudflare or x-real-ip behind an Nginx proxy you control. Required outside localhost.
AUTH_PASSWORD_PEPPER_HEXD1 only. 64 hex characters. Keep it stable: changing it makes every existing password stop verifying.

Next.js, TanStack Start, and React Router read .env when it exists, but variables set by your host take precedence. Prefer host-managed variables and do not ship .env in images or build artefacts.

Fonts

Generated projects serve fonts locally. The CLI writes a default puzzle-fonts.json and downloads the fonts into public/fonts during setup. Commit public/fonts so builds do not depend on Google Fonts, and run the download script again whenever you change puzzle-fonts.json:

npm run fonts:download

For the best caching, serve versioned font-<hash>.woff2 files with Cache-Control: public, max-age=31536000, immutable, and puzzle-fonts.css plus the puzzle-font-<family>.woff2 preload files with a short cache, such as public, max-age=86400, stale-while-revalidate=604800. TanStack Start projects apply these headers automatically through Nitro route rules. On other hosts, configure the same rules in your CDN or web server.

Databases

The first application account created by the CLI exists only in the local database. It is not automatically provisioned in a separate production database or remote D1. Its password is stored as an Auth password hash, not in generated configuration files. Puzzle Auth has no built-in administrator roles; this account is separate from MongoDB's database administrator.

MongoDB

Puzzle Auth uses MongoDB transactions, so production MongoDB must be a replica set or sharded cluster.

The generated setup is locked down by default:

  • .env contains a randomly generated administrator password and a separate application user and password, both 64 hex characters.
  • docker compose reads the credentials from .env; it refuses to start when one is missing.
  • Access control is enabled. The replica set authenticates its members with a keyfile generated on first start and stored in the mongodb-config volume.
  • docker/mongodb/create-app-user.js creates the application user on first start with the readWrite role on MONGODB_DATABASE only. The application never uses the administrator account.
  • The db:setup package script starts the database and verifies both accounts and replica-set primary readiness. It can initialize the first administrator on an older local volume without users and create a missing application user with matching administrator credentials. Existing passwords and data are never reset.
  • The port is published on 127.0.0.1 only, so MongoDB is not reachable from other machines.

Managed MongoDB

A managed service such as MongoDB Atlas is the simplest production option. Create a database user with readWrite on your application's database only, restrict network access to your application hosts, and set:

MONGODB_URI="mongodb+srv://<user>:<password>@<cluster-host>/<database>?retryWrites=true&w=majority"
MONGODB_DATABASE="<database>"

The MONGODB_ROOT_* and MONGODB_APP_* variables are only used by the generated Docker Compose file and are not needed with a managed service.

Self-hosted with Docker Compose

To run the generated docker-compose.yml on your server:

  1. Copy docker-compose.yml and the docker/mongodb/ directory to the server.
  2. Create a .env next to them with new values for MONGODB_ROOT_PASSWORD and MONGODB_APP_PASSWORD, and update the password in MONGODB_URI to match.
  3. Restrict the file: chmod 600 .env.
  4. Start MongoDB with docker compose up -d --wait.

Docker's entrypoint creates users only when the data volume is first initialised. Changing a password in .env afterwards does not change it in MongoDB; update it in both places, for example with db.getSiblingDB("<database>").changeUserPassword("<user>", "<new password>") as the administrator.

For an older local volume without users, run the generated db:setup package script from the application directory instead of deleting the volume. If existing users have different credentials, setup refuses to reset them: restore their original .env values or update the passwords as an administrator. Exported shell variables override Compose's .env values, so check those too.

Run the application on the same server so it can reach 127.0.0.1:27017. If the application runs as another service in the same Compose project, connect to the mongodb service name instead of localhost. Never publish port 27017 to the internet. Back up the mongodb-data volume, for example with mongodump, and keep the mongodb-config volume with it.

Cloudflare D1

D1 projects deploy to Cloudflare Workers. Before the first deploy:

npx wrangler login
npx wrangler d1 create <project>-db
  1. Copy the returned database_id into wrangler.jsonc, replacing the preview ID.

  2. Store each secret in the Worker. Do not put secrets in wrangler.jsonc:

    npx wrangler secret put AUTH_ENCRYPTION_KEY_HEX
    npx wrangler secret put AUTH_RATE_LIMIT_SECRET
    npx wrangler secret put AUTH_PASSWORD_PEPPER_HEX
    npx wrangler secret put APP_ORIGIN
    npx wrangler secret put TRUSTED_CLIENT_IP_HEADER   # cf-connecting-ip
  3. Deploy with npm run deploy. This builds the application and runs wrangler deploy (or opennextjs-cloudflare deploy for Next.js).

D1 access is limited to the DB binding of your Worker; there is no database password to manage. Use npm run preview to test the Worker build locally before deploying.

Custom database

Implement the storage adapter in the generated database module. Use a dedicated database user with the minimum privileges Puzzle Auth needs, require TLS for connections that leave the host, keep the database off the public internet, and supply credentials through host-managed environment variables. Until the module returns an adapter, the auth API responds with HTTP 503.

Frameworks

Next.js

Build and start the production server on any Node.js host:

npm run build
npm run start

next start listens on port 3000; set PORT to change it. Run it behind a reverse proxy or load balancer that terminates HTTPS and sets the header named in TRUSTED_CLIENT_IP_HEADER.

On a managed platform such as Vercel, add the production variables in the project settings and set TRUSTED_CLIENT_IP_HEADER to a header the platform overwrites, such as x-real-ip on Vercel.

With D1, the project uses OpenNext for Cloudflare. Follow Cloudflare D1, then run npm run deploy.

TanStack Start

Node.js projects include Nitro, which builds a standalone server into .output:

npm run build
npm run start

npm run start runs node .output/server/index.mjs. Nitro listens on port 3000 by default; set PORT and HOST to change it. Copy the whole .output directory to deploy; it does not need node_modules. Nitro can also build for platforms such as Vercel and Netlify; see its deployment presets.

The Vite configuration passes createFontRouteRules() from @puzzle-ui/theme/nitro to Nitro, so local fonts are served with the cache headers described in Fonts. The route rules are created from the files in public/fonts when the build starts, so download fonts before building.

With D1, the project uses @cloudflare/vite-plugin instead of Nitro. Follow Cloudflare D1, then run npm run deploy.

React Router

Build and start the production server on any Node.js host:

npm run build
npm run start

npm run start serves build/server/index.js with react-router-serve, which listens on port 3000 by default; set PORT to change it. Deploy the build directory together with package.json and production dependencies. The React Router template also includes a Dockerfile for container hosts.

With D1, the project runs on Cloudflare Workers and has no start script. Follow Cloudflare D1, then run npm run deploy.

Basic React

Basic React builds a static single-page application:

npm run build

Upload dist to any static host or CDN, and rewrite unknown paths to index.html if you add client-side routing. Serve dist/assets/* with a long immutable cache and fonts as described in Fonts.

Basic React has no server runtime. With Auth, host the authentication API separately, ideally on the same site so session cookies stay first-party, and point the AuthProvider base path at it.

Production checklist

  • New secrets generated for production and stored in the host, not in .env or source control.
  • APP_ORIGIN set to the exact HTTPS origin.
  • TRUSTED_CLIENT_IP_HEADER set to a header your host overwrites.
  • Database reachable only from the application, with a least-privileged user.
  • public/fonts committed and up to date with puzzle-fonts.json.
  • Backups configured for self-hosted databases.

See Production readiness and the Authentication setup guide for a complete Auth review.