Skip to content

Deploying Holo Apps ​

A Holo app deploys like any Next.js, Nuxt, or SvelteKit app, with two additions: you run database migrations as a deploy step, and you may need long-running worker processes for queues and broadcasting. This page walks through a typical deploy.

The short version ​

bash
npm ci
npx holo migrate
npm run build
npm run start

Plus, if you use them:

bash
npx holo queue:work --connection redis
npx holo broadcast:work
npx holo schedule:work

The scaffolded build and start scripts run holo build and holo start.

Pick a host by what your app runs ​

What you need depends on whether anything has to keep running after a request ends.

Your app usesYou needHosts that fit
Pages, API routes, database, auth, forms, storage, sync queueA web server onlyAny host your framework supports, including Vercel and Cloudflare when the framework supports them
redis or database queues, queued mail or notifications, queued listeners, media conversions on a queueWeb server + queue workerWeb app anywhere, plus a VPS, container service, or PaaS that runs long-lived processes
Self-hosted broadcasting (holo driver) or realtime queriesWeb server + broadcast workerSame as above
Scheduled tasks (server/schedule.ts)Web server + a cron entry for holo schedule:run, or holo schedule:workSame as above

A common setup is to put the web app on a serverless platform and run workers on a small server or container, all with the same environment variables. Serverless platforms can't run workers on their own.

Build ​

bash
npm run build

holo build refreshes Holo's generated files (model and job registries, generated schema types) and then runs your framework's build. Extra arguments are passed to the framework.

WARNING

holo build reads the tables and columns of your default connection's database and writes the generated schema types from them. It doesn't load or run migrations. The build environment needs the same database settings as production, and the database must be reachable: if it isn't, holo build fails with an error that names the connection. On SQLite, the database file must already exist where the build runs: holo build never creates it, so a fresh checkout or a Docker build stage without the file fails instead of building against an empty database. Run your migrations before building. holo build doesn't load your migration files either, so a migration that imports a development-only package doesn't break the build.

Start the server ​

bash
npm run start

holo start loads your .env files and starts the framework's production server with Holo ready before your code runs:

FrameworkWhat holo start runs
Next.jsnext start
Nuxtnode .output/server/index.mjs
SvelteKitnode build/index.js (adapter-node)

Use holo start in your process manager (systemd, PM2, Docker, and so on) instead of calling the framework's server directly. Pass server options after it:

bash
npx holo start --hostname 0.0.0.0 --port 3000

WARNING

Production Next.js apps must set trustedProxies to '*' in config/security.ts. Scaffolded apps read it from TRUSTED_PROXIES. Without it, the first request that checks an IP-keyed rate limit fails with a configuration error. On Vercel, set TRUSTED_PROXIES=* (or trustedProxies: '*') in the project's environment variables. When you run your own reverse proxy, use '*' too, but only if the proxy overwrites X-Forwarded-For and the Next.js server listens only on 127.0.0.1 or a private network behind it. Next.js can't match a proxy address, so a list doesn't work there. See Trusted proxies in Next.js.

If you don't pass --port, Holo uses the PORT environment variable.

Stop the server ​

Send the Next.js or Nuxt server SIGTERM (or press Ctrl+C) to stop it. Holo closes its database, Redis, queue, and other connections, then the process exits.

Next.js starts closing as soon as the signal arrives, while requests may still be running. A request that uses a database or Redis connection after that point can fail, so remove the server from your load balancer before you send the signal. The process exits once the close finishes, or 30 seconds after the signal, so set your process manager's stop timeout to at least 30 seconds. Nuxt's server finishes its in-flight requests before Holo closes, and also waits up to 30 seconds by default.

Holo reports a failed close through exceptions.report, with capability next or nuxt and operation shutdown. Holo doesn't wait for your reporter to finish, so flush your error tracker before exit if you need every report. See Reporting errors.

Run migrations ​

Run migrations as an explicit deploy step, before you build and before new code serves traffic:

bash
npx holo migrate

Holo never migrates on startup. A typical deploy:

  1. Install dependencies.
  2. Run tests.
  3. Run npx holo migrate against the production database.
  4. Build with npm run build.
  5. Cache config with npx holo config:cache (optional).
  6. Start or restart the web server and workers.

If several replicas run step 3 at once, use npx holo migrate --isolated. One replica applies the migrations and the others skip them without failing the deploy. The lock comes from the default cache store, so every replica must share a redis or database store. A database store needs its tables first: run npx holo cache:table and npx holo migrate once. See Isolating migration runs.

To undo the last deploy's migrations, run npx holo migrate:rollback. In production it asks you to confirm, so pass --force in a script. See Migrations.

Run workers ​

Run each worker as its own supervised process, next to the web server. Don't start workers from inside a web request.

Queue workers ​

bash
npx holo queue:work --connection redis --queue default,emails

Run one process per queue group you need, and add more processes to handle more jobs. After each deploy, tell running workers to finish their current job and exit, so your process manager starts them on the new code:

bash
npx holo queue:restart

See Running Workers and the CLI reference for every flag.

Broadcast worker ​

bash
npx holo broadcast:work

It listens on worker.host and worker.port from config/broadcast.ts (default 0.0.0.0:8080). Put it behind your reverse proxy with WebSocket support. To run more than one, turn on Redis scaling. See Scaling in Production.

Cache config ​

bash
APP_ENV=production npx holo config:cache

This evaluates config/*.ts with your env values and writes the results, secrets included, to .holo-js/generated/config-cache.json. Holo still reads .env at startup to choose the environment. APP_ENV picks which cache is used, and in production Holo reads that file instead of loading each config file. Config modules that contain functions, such as app with an exception reporter or security with rate-limit callbacks, still load at startup, and the env() values they read while loading are frozen too. Code that calls env() after startup, such as a reporter's body, reads the runtime environment. Run it on every deploy, after your environment variables are in place. Remove it with npx holo config:clear. Don't commit the cache file.

Environment variables ​

Set production values through your host's environment settings or a .env.production file on the server. At minimum:

ini
APP_ENV=production
APP_DEBUG=false
APP_KEY=your-generated-key
APP_URL=https://blog.example.com

Generate APP_KEY once with npx holo key:generate and keep it the same across deploys. When APP_ENV isn't set, Holo runs as production. Don't copy your development .env to the server: its APP_ENV=development would win over that default. See Environment Variables.

Next steps ​

Released under the MIT License.