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, or root. 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.com pointing 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:

BASH
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:

TS
// 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:

BASH
bun sixb deploy --dry-run

It lists every process with its command, address, and environment.

OptionPurpose
nameNames the deployment on the server and in default domains. Lowercase letters, numbers, and hyphens.
domainParent domain for services without their own: <name>-<service>.<domain>.
targetWhere the deployment runs.
envEnvironment variables for every service. This file is committed, so keep secrets in the server's .env.
servicesTurn services off or adjust them.
processesLong-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

OptionDefaultPurpose
hostThe 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.
portsapp 3001, API 3002The 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.
standbyPortsports + 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:

TS
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.

ServiceSettings
api, appdomain, env, process
orchestrator, rulesenv, process. Each always runs as one process.
workerstypes (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:

TS
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):

BASH
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, sixb by 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:

BASH
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:

BASH
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:

BASH
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:

  1. Checks the server.
  2. Unpacks the commit into its own releases/<id> directory and links it to the server's .env.
  3. Installs the pinned Bun and the dependencies, writes .env if the project has a source, and runs sixb build (carrying one generation of hashed browser chunks forward so open tabs never 404).
  4. Runs sixb db migrate, sixb check, and sixb lake check from 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.
  5. Starts the new app, api, and workers on the standby ports, waits for the API's /ready, and fails if a process exits in its first seconds.
  6. Validates and reloads the Caddy routes onto the new slot, swaps orchestrator and rules, and drains the retiring api and workers in 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

CommandPurpose
sixb deploy statusShow 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

Search docs

Search the documentation