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| Variable | Production value |
|---|---|
APP_ORIGIN | The exact public origin, for example https://app.example.com. HTTPS is required outside localhost, and there must be no trailing slash. |
AUTH_ENCRYPTION_KEY_HEX | 64 hex characters. Encrypts authenticator (MFA) secrets; existing MFA enrolments stop working if it changes. |
AUTH_RATE_LIMIT_SECRET | At least 32 random characters. |
TRUSTED_CLIENT_IP_HEADER | A 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_HEX | D1 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:downloadFor 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:
.envcontains a randomly generated administrator password and a separate application user and password, both 64 hex characters.docker composereads 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-configvolume. docker/mongodb/create-app-user.jscreates the application user on first start with thereadWriterole onMONGODB_DATABASEonly. The application never uses the administrator account.- The
db:setuppackage 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.1only, 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:
- Copy
docker-compose.ymland thedocker/mongodb/directory to the server. - Create a
.envnext to them with new values forMONGODB_ROOT_PASSWORDandMONGODB_APP_PASSWORD, and update the password inMONGODB_URIto match. - Restrict the file:
chmod 600 .env. - 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-
Copy the returned
database_idintowrangler.jsonc, replacing the preview ID. -
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 -
Deploy with
npm run deploy. This builds the application and runswrangler deploy(oropennextjs-cloudflare deployfor 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 startnext 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 startnpm 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 startnpm 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 buildUpload 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
.envor source control. APP_ORIGINset to the exact HTTPS origin.TRUSTED_CLIENT_IP_HEADERset to a header your host overwrites.- Database reachable only from the application, with a least-privileged user.
public/fontscommitted and up to date withpuzzle-fonts.json.- Backups configured for self-hosted databases.
See Production readiness and the Authentication setup guide for a complete Auth review.