Deploy to a server
sixb deploy runs your project on a Linux server you reach over SSH. You describe the deployment in sixb.deploy.ts. The CLI prepares the server once, then on each deploy sends the commit, builds it on the server, runs every service under an account without root access, and serves each one on its own domain over HTTPS.
Before you start
You need:
- A server running Ubuntu or Debian with systemd, such as a new virtual machine from a cloud provider, with an account that can use
sudo, orroot. You use that account once, to set the server up. - A domain whose DNS you control. Each service gets its own name under it, so one wildcard record such as
*.example.compointing at the server covers them all. Ports 80 and 443 must be open; the server gets an HTTPS certificate for each name automatically. - Production providers. The services run as separate processes, so they need storage, a broker, and queues they can share, such as PostgreSQL and Redis, and authentication configured for production. See Prepare your configuration. The databases can run on the server or anywhere it can reach.
Add the SSH target to the project:
bun add @sixb/deploy-ssh
The server runs the Bun version that packageManager pins in package.json, such as "packageManager": "bun@1.4.4". A project created with bun create sixb pins it already.
Describe the deployment
Create sixb.deploy.ts in the project root:
// sixb.deploy.ts
import { defineDeploy } from "@sixb/core/deploy"
import { SshTarget } from "@sixb/deploy-ssh"
export default defineDeploy({
name: "shop",
domain: "example.com",
target: new SshTarget({ host: "203.0.113.10" }),
})
This serves the API at shop-api.example.com and your app at shop-app.example.com. It runs the orchestrator, rules, and workers alongside them.
Preview what will run, without connecting to the server:
bun sixb deploy --dry-run
It lists every process with its command, address, and environment.
| Option | Purpose |
|---|---|
name | Names the deployment on the server and in default domains. Lowercase letters, numbers, and hyphens. |
domain | Parent domain for services without their own: <name>-<service>.<domain>. |
target | Where the deployment runs. |
env | Environment variables for every service. This file is committed, so keep secrets in the server's .env. |
services | Turn services off or adjust them. |
processes | Long-running scripts of your own, supervised alongside the services. |
Every service gets NODE_ENV=production and the public origins of the API and the app, so you do not set those yourself.
The SSH target
| Option | Default | Purpose |
|---|---|---|
host | The server's hostname or IP address, or a Host alias from your SSH config. Use an alias to reach SSH on a port other than 22. | |
user | "sixb" | The account the services run as. Never root. See Several projects on one server. |
ports | app 3001, API 3002 | The primary local ports each domain is forwarded to. A project also uses its standbyPorts, so give the next project on a server ports 20 higher. |
standbyPorts | ports + 10 (app 3011, API 3012) | Second local port pair used to boot and verify a new release before Caddy switches traffic. |
Services
Set a service to false to turn it off, or pass an object to adjust it:
export default defineDeploy({
name: "shop",
domain: "example.com",
target: new SshTarget({ host: "203.0.113.10" }),
services: {
app: { domain: "shop.example.com" },
rules: false,
workers: {
concurrency: { sync: 4 },
process: { instances: 2, maxMemory: "1G" },
},
},
})
The rules process waits idly when the project has no rules; turn it off to save memory. Keep the orchestrator on: it runs cron schedules, delivers events whose first delivery failed, brings back runs that lost their worker, and requests storage maintenance, which runs in the lake worker. Without it a lost sync run stays running, and later runs of that sync wait behind it. sixb deploy warns when a deployment leaves either out. The lake worker also writes the changes ingest stores, with or without the orchestrator; without that worker they wait, and Console › Lake health shows them.
| Service | Settings |
|---|---|
api, app | domain, env, process |
orchestrator, rules | env, process. Each always runs as one process. |
workers | types (default: every type the project registers work for), concurrency per type, env, process |
process sets maxMemory (restart a process that grows past a size such as "512M"), killTimeoutMs (how long a stopping process may take; default 10000, and 70000 for api and workers, which first wait up to 65 seconds for the Actions they are running and their effects), and restartDelayMs (the wait before restarting a process that exited, growing with each restart; default 1000). For workers and your own processes, instances runs several copies.
Your own processes
Run a script of your own next to the services, restarted like them if it exits:
processes: {
"price-feed": { entrypoint: "scripts/price-feed.ts", args: ["--live"] },
},
It runs with Bun from the project directory and gets the same environment as the services.
Set up the server
Run this once per server, naming an account with sudo (default: root):
bun sixb deploy setup --admin ademattos
Setup logs in as that account only when the server needs something, and:
- installs Caddy, the web server that routes each domain to its service and handles HTTPS;
- creates the deploy account,
sixbby default, which accepts your SSH key and no password, and lets its services start at boot; - lets the deploy account reload Caddy, and nothing else that needs root;
- adds your admin account to the deploy account's group, so it can read the projects without
sudo.
--key <file> authorizes a different public key than the one SSH uses for the server. A Caddy already on the server must be 2.7 or later, and sixb deploy check stops on an older one. On a server where Caddy already serves other sites, setup keeps its configuration, adds one import line, and saves the previous file as /etc/caddy/Caddyfile.before-sixb-deploy. Setup reports an SSH server that accepts passwords, or a firewall that blocks ports 80 and 443, but changes neither.
Setup is safe to run again. More projects under the same deploy account need no admin login.
Check the server at any time without changing anything:
bun sixb deploy check
It checks the server's tools, the deploy account, the routes, the project's .env, its ports, the free disk space, and where each domain points, and says what to do about each problem. sixb deploy runs the same checks first, and stops before uploading anything when one would make the deploy fail.
Add the project's settings
To keep them in one place across your team and servers, use environment variables from Doppler. A deploy then writes the server's .env for you, and you can skip the rest of this section.
Otherwise, secrets and connection strings, such as DATABASE_URL, API keys, and anything else you keep out of the repository, go in a .env file in the project's directory on the server. Create it readable only by the deploy account, then edit it:
ssh sixb@203.0.113.10 'install -m 600 /dev/null ~/shop/code/.env'
ssh -t sixb@203.0.113.10 'nano ~/shop/code/.env'
For a project inside a monorepo, the directory is ~/<name>/code/<path>; sixb deploy check prints the exact path. Every release reads this one file, so sixb deploy restart applies an edit. Without a source, a deploy never replaces the server's .env, even when the repository has one.
Deploy
Commit your changes, then deploy:
bun sixb deploy
Only committed files are sent, with submodules at their recorded commits. Uncommitted changes and ignored files stay on your machine. --ref <branch|tag|commit> deploys something other than the checked-out commit.
A deploy:
- Checks the server.
- Unpacks the commit into its own
releases/<id>directory and links it to the server's.env. - Installs the pinned Bun and the dependencies, writes
.envif the project has a source, and runssixb build(carrying one generation of hashed browser chunks forward so open tabs never404). - Runs
sixb db migrate,sixb check, andsixb lake checkfrom the new release while the previous release keeps serving. When the new release brings storage migrations, the services stop first, since the previous release cannot run against the new schema: that deploy has a short downtime. - Starts the new
app,api, andworkerson the standby ports, waits for the API's/ready, and fails if a process exits in its first seconds. - Validates and reloads the Caddy routes onto the new slot, swaps
orchestratorandrules, and drains the retiringapiandworkersin the background so in-flight requests and agent turns finish cleanly.
A deploy that fails before the new release takes over discards it, and the live release keeps serving, unless a migration stopped it in step 4. A check that fails after that leaves the new release serving: the deploy says so, and sixb deploy status names its commit. Two deploys of the same project never overlap; the second waits for the first.
Operate the deployment
| Command | Purpose |
|---|---|
sixb deploy status | Show each process with its memory, CPU, and restarts, and the deployed commit. |
sixb deploy logs [service] | Print recent log lines. --follow keeps printing; --tail <lines> sets how many (default 100). |
sixb deploy restart [service] | Restart one service, or all of them. stop and start work the same way. |
sixb run --deployed <script> | Run a one-off script on the deployment, with its environment. |
A process that exits is restarted automatically, and the services start when the server boots, without anyone logging in.
To return to an earlier release, deploy its commit with --ref. Storage migrations are not reversed.
Next steps
- Deploy from GitHub Actions on every push.
- Server accounts and access: give teammates access, and run several projects on one server.
- The Northline example deploys this way, with PostgreSQL and Redis.