Overview

A Better Compute deployment is one configuration file, one PostgreSQL database and some number of Node.js processes started from that configuration. Each process runs a subset of the same roles: the HTTP API, the daemon gateway, and the worker roles that run reconcilers, deliver events and run Better IAM's jobs. PostgreSQL is the only source of truth. Every process can be stopped, restarted or duplicated, and the leases in the database keep each job single-writer.

This section covers running that system: how to lay the processes out, what to configure, what the database needs, how the machine PKI works, and how to harden, observe and scale it.

Process roles

better-compute serve runs the roles you name with --roles (or BETTER_COMPUTE_ROLES). The default, all, runs the API, every worker role, and the gateway when the configuration exports host.gateway.

--roles takes all or a comma list: api, gateway, and any of controllers, scheduler, sinks, iam. The worker roles are the server's workerRoles export; compute.start() with no argument runs all four.

better-compute serve                                          # all: api, workers, and the gateway if configured
better-compute serve --roles api --port 3000 --no-migrate
better-compute serve --roles controllers,scheduler,sinks,iam --no-migrate
better-compute serve --roles gateway --no-migrate

What talks to what

• Callers to the API. JSON over HTTPS with X-Better-Compute: 1. Better IAM authenticates every caller and decides every call. See security.
• Daemons to gateways. Nodes only dial out, to gw.<region>:443 through an L4 balancer that passes TLS through, so the gateway sees the client certificate. See the gateway.
• Everything to PostgreSQL. Processes never call each other for correctness. The API writes commands, desired state and outbox rows in its transactions; gateways and workers read them from the database.
• API to gateways, as an accelerator. After a commit the API can poke the owning gateway (notifier), relay a tunnel, or push a revocation through the gateway's internal control API, over mutual TLS from the internal CA. Without it, gateways still converge from their 1-second dispatch loop.

One configuration

Every process loads the same better-compute.config.ts. Its default export describes the control plane (defineConfig, the options of betterCompute()); its named host export describes what serve runs around it (defineHost: extra routes, metrics, tunnels, the gateway listener). Environment variables supply what differs between environments. See configuration.

import { defineHost } from 'better-compute/cli';
import { postgres } from 'better-compute/postgres';
import { defineConfig } from 'better-compute/server';

export default defineConfig(({ env = process.env } = {}) => ({
  database: postgres({ url: env.BETTER_COMPUTE_DATABASE_URL! }),
  secret: env.BETTER_COMPUTE_SECRET!,
  baseURL: 'https://compute.example.com',
  iam, // bridge.embedded(iam, { rootTenantId })
  modules: [/* provisionModule(), metal(), vps(), eventsModule(), … */],
}));

export const host = defineHost(async ({ compute, env }) => ({
  gateway: { region: 'eu-1', tls: { key, cert, ca: nodeCaPem } },
}));

Before the first node joins

better-compute migrate
better-compute serve --no-migrate
better-compute doctor --strict

In this section