Kernlift

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 fly CLI, signed in (fly auth login).
  • deploy.config.json says "platform": "fly". Run pnpm kernlift deploy-target fly to set it, with --dialect, --agent or --region as needed. See deploy.config.json.
  • fly.toml and .env.production in 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-saas

For SQLite, also create the volume that holds the database file:

fly volumes create data --app my-saas --region iad --size 1 --yes

Import 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-saas

For Postgres, include the database URL:

grep -E '^(BETTER_AUTH_SECRET|CONFIG_ENCRYPTION_KEY|SITE_URL|DATABASE_URL)=' .env.production | fly secrets import --app my-saas

Deploy

Deploy the web app

fly deploy

pnpm 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-agent

Give the web app the signing secret

grep -E '^AGENT_INTERNAL_SIGNING_SECRET=' .env.production | fly secrets import --app my-saas

Deploy the agent service

fly deploy -c fly.agent.toml

Run a single machine, because the service holds run state in memory.

Verify

  • fly deploy prints 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/auth shows 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/agent opens the workbench.
  • In the repository, pnpm smoke:node after pnpm build:node checks the build you ship, and pnpm validate:deploy-targets checks the rendered fly.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