Deploy to Fly.io
Create the Fly app, import the generated secrets, deploy the Node image with migrations, create the production administrator, and optionally add the agent app.
On Fly.io the project is one app built from the root Dockerfile. Its database is a SQLite file on a volume, for a single machine, or a Postgres you bring. The agent service is optional and runs as a second app on Fly's private network, on Postgres only. Use this guide for the first production deployment.
Before you begin
- The
flyCLI, signed in (fly auth login). deploy.config.jsonsays"platform": "fly". Runpnpm kernlift deploy-target flyto set it, with--dialect,--agentor--regionas needed. See deploy.config.json.fly.tomland.env.productionin the project root; that command writes them.- For Postgres: a database and its connection URL; see Use Postgres and Supabase.
The examples use my-saas as the app name and iad as the region. Use the app and primary_region from your fly.toml.
Create the app and store the secrets
kernlift deploy-target fly prints these steps for your project.
Set the public URL
In .env.production, set SITE_URL to the address the site will be served from. For Postgres, add a DATABASE_URL= line with the connection URL to the same file.
Create the app
fly apps create my-saasFor SQLite, also create the volume that holds the database file:
fly volumes create data --app my-saas --region iad --size 1 --yesImport the secrets
The values are read from .env.production over standard input. For SQLite:
grep -E '^(BETTER_AUTH_SECRET|CONFIG_ENCRYPTION_KEY|SITE_URL)=' .env.production | fly secrets import --app my-saasFor Postgres, include the database URL:
grep -E '^(BETTER_AUTH_SECRET|CONFIG_ENCRYPTION_KEY|SITE_URL|DATABASE_URL)=' .env.production | fly secrets import --app my-saasDeploy
Deploy the web app
fly deploypnpm run deploy runs the same command. Fly builds the root Dockerfile and applies the migrations before the new version takes traffic. With Postgres, release_command runs node scripts/db/migrate-runtime.mjs on a temporary machine. With SQLite, the app process migrates the file on the volume and then starts the server.
Create the production administrator
fly ssh console --app my-saas --pty -C "node .output/scripts/bootstrap-super-admin.mjs"The script runs inside the app, against its own database, and prompts for the email and password.
Keep one machine running
The scheduled jobs run inside the web process, so fly.toml sets min_machines_running = 1. A stopped machine runs no fulfilment retries or AI task polling. With SQLite, do not scale the app beyond one machine, because the database file belongs to one machine.
Add the agent app
Skip this section if the project does not include the agent. With "agent": true, the project also carries fly.agent.toml for the my-saas-agent app, and fly.toml points the web app at http://my-saas-agent.internal:3001. The agent app has no public service and is not auto-stopped mid-run.
Create the agent app and import its secrets
fly apps create my-saas-agent
grep -E '^(AGENT_INTERNAL_SIGNING_SECRET|AGENT_RESOURCE_GRANT_SECRET|DATABASE_URL)=' .env.production | fly secrets import --app my-saas-agentGive the web app the signing secret
grep -E '^AGENT_INTERNAL_SIGNING_SECRET=' .env.production | fly secrets import --app my-saasDeploy the agent service
fly deploy -c fly.agent.tomlRun a single machine, because the service holds run state in memory.
Verify
fly deployprints the app's address, and the site loads there./setup, signed in as the administrator, names Fly.io and the database in its first line and shows Session secret as ready./admin/config/authshows the Base URL the site answers on. Change it there if the site uses another domain.- Scheduled jobs turns ready within a couple of minutes.
- With the agent,
/app/agentopens the workbench. - In the repository,
pnpm smoke:nodeafterpnpm build:nodechecks the build you ship, andpnpm validate:deploy-targetschecks the renderedfly.toml.
Troubleshooting
The deploy fails in the release command
The migration could not reach Postgres. Check that DATABASE_URL was imported into the app and that the database accepts connections from Fly.
The app refuses to start with a session secret error
BETTER_AUTH_SECRET was not imported. Run the import command again.
Scheduled jobs stay not ready on /setup
Check that fly.toml keeps min_machines_running = 1. If JOBS_IN_PROCESS=false is set, an external cron has to run pnpm jobs:run instead.
The workbench says the agent service is not deployed
The web app cannot reach my-saas-agent.internal:3001, or the two apps hold different values of AGENT_INTERNAL_SIGNING_SECRET. Import the secret into both apps from the same .env.production.
Next steps
Deploy to Cloudflare Workers
Deploy the Worker on D1 or on Postgres through Hyperdrive, store the session secret, create the production administrator, and optionally add the agent container.
Deploy to Railway
Create the Railway project, services and Postgres from .railway/railway.ts, set the generated secrets, deploy, and create the production administrator.