@rcpooley/concord-kit

Opinionated building blocks for a Concord config repo. Concord's modules are deliberately low-level (a docker module, a file module, a systemd module…). This kit is one way of declaring a fleet on top of them, with these conventions:

• An app is one file. Its containers, host files, packages, units, git checkouts, routes, certificates and DNS records live together, so adding an app is one file and deleting it is deleting that file.
• A machine is described once. From each Machine, assemble() derives Docker (from Docker's apt repo), host metrics (node_exporter), the host registry entry, and the machine's edge if it has one.
• The edge is generated. A machine with an edge gets an nginx container whose config, certificates and published ports are all derived from declarations: every route must be covered by exactly one certificate at plan time, and Let's Encrypt renewal is convergence rather than a timer.
• Order is decided in one place. assemble() returns the whole module array in dependency order; the config declares what, never when.

Released in lockstep with @rcpooley/concord: use the same version of both. It imports only Concord's types, from your config's own dev dependency on it.

Install

In your config repo:

npm install --save-exact @rcpooley/[email protected]
npm install --save-dev --save-exact @rcpooley/[email protected]

The kit is a runtime dependency (the daemon installs it before evaluating your config; commit package-lock.json). Concord itself stays a dev dependency, for types and the concord CLI.

A small config

// concord.ts
import type { ConcordConfig } from '@rcpooley/concord'
import { assemble, publicIpOf, registry, type App, type Machine, type ZoneMap } from '@rcpooley/concord-kit'
import { secrets } from './secrets.js'

export const fleet = {
  web: {
    ssh: { ip: '10.0.0.1', user: 'deploy', transport: 'local' }, // the machine the daemon runs on
    arch: 'amd64',
    publicIp: '203.0.113.10',
    edge: {
      listeners: {
        public: { containerPort: 443, redirectPort: 80, bind: '203.0.113.10' },
        private: { containerPort: 8444, redirectPort: 8081, bind: '10.0.0.1', allow: ['10.0.0.0/8'] },
      },
      certs: [{ domains: ['example.com', '*.example.com'] }],
    },
  },
} satisfies Record<string, Machine>
type Host = keyof typeof fleet
const publicIp = publicIpOf<Host>(fleet)

export const ZONES = {
  'example.com': {
    provider: 'porkbun',
    records: [{ type: 'A', name: '@', content: publicIp('web') }],
  },
} as const satisfies ZoneMap

const blog: App<Host, typeof ZONES> = {
  name: 'blog',
  host: 'web',
  containers: [{
    name: 'blog',
    source: { image: 'ghost', tag: '5' },
    networks: [{ name: 'apps', aliases: ['blog'] }],
  }],
  routes: [{ names: ['blog.example.com'], listen: 'public', upstream: { container: 'blog', port: 2368 } }],
  dns: [{ zone: 'example.com', records: [{ type: 'A', name: 'blog', content: publicIp('web') }] }],
}

const hosts = registry(fleet)

export default {
  schemaVersion: 8,
  hosts,
  modules: assemble({
    fleet,
    network: 'apps',
    apps: [blog],
    zones: ZONES,
    dns: { porkbun: { apiKey: secrets['porkbun-api-key'], secretKey: secrets['porkbun-secret-key'] } },
    acme: {
      email: '[email protected]',
      defaultDns: 'porkbun',
      dns: {
        porkbun: {
          PORKBUN_API_KEY: secrets['porkbun-api-key'],
          PORKBUN_SECRET_API_KEY: secrets['porkbun-secret-key'],
        },
      },
    },
  }),
} satisfies ConcordConfig<typeof hosts>

In a real config, put the machines, zones and each app in their own files, and declare type App = KitApp<HostName, typeof ZONES> once so every app file gets checked host and zone names.

What assemble() emits, in order

1. Per machine: Docker (apt repo + packages, /etc/docker/daemon.json, a restart when it changes), then node_exporter.
2. App files and directories.
3. App packages and apt repos.
4. App git checkouts.
5. App scripts.
6. One docker module per machine: the networks something there joins, then platform containers, then app containers.
7. App systemd units.
8. One nginx edge per machine that declares edge.
9. One DNS module per provider that holds a zone.

Within each layer, platform contributions come before apps, and machines appear in fleet order.

Options

| | | |---|---| | fleet | Record<name, Machine>: how Concord reaches each machine, its arch, and optionally sleeps, dev, publicIp, keepImages, edge | | network | the docker network every app joins and every edge proxies across | | apps, platform | App[]. platform is for shared infrastructure many apps need and none owns (a database); it is deployed first | | zones | every DNS zone and the provider holding it (porkbun or cloudflare). ⚠️ A Porkbun zone is the whole truth: undeclared live records are deleted. A Cloudflare zone is shared: only records Concord marked are touched | | dns | credentials per provider; cloudflare.id is the ownership marker written into each record (changing it is a migration) | | acme | Let's Encrypt for the edges: account email, default DNS provider, and per-provider lego environment variables (as secrets) | | nodeExporter | false to turn host metrics off; bind to choose the address (default: the machine's ssh.ip, assumed private); after for a service that must be up first (a VPN) | | dockerDaemonJson | the daemon.json every machine gets (default: bounded json-file logs) |

The edge

An edge machine declares listeners (planes). Each maps a host address to its own container port, so nginx knows which interface a request came in on: a private vhost can never answer on the public address. Each listener gets its own config file (public → 10-public.conf, private → 20-private.conf) with a catch-all that drops unknown hostnames.

Routes are ServerBlocks on an app. upstream: { container, port } is resolved to the container's alias on the shared network at plan time, so a typo is a plan error, not a 502. Certificates are declared (on the machine for shared wildcards, on an app for names it owns) and every route must be covered by exactly one, most specific first.

Apps can contribute shared edge material by name: features (snippet pairs a route opts into, plus an optional http part included once in nginx.conf for the maps they read), secretFiles, logFormats and rateLimits.

Also exported: nginxEdge() itself, certFor, covers, EDGE_CONF, PROXY_CONF, and the per-machine pieces (dockerAptRepo, DOCKER_PACKAGES, nodeExporterUnit) if you want to assemble differently.

Routing the Concord daemon through an edge

The daemon has two HTTP servers: the API and UI (CONCORD_LISTEN, token required) and the GitHub webhook (CONCORD_HOOK_LISTEN, signature required). The edge runs in a container, which cannot reach the host's loopback, so have the daemon also listen on an address the container can reach — a private (VPN) address of the machine — and route to that:

// /etc/concord.env on the machine:
//   CONCORD_LISTEN=127.0.0.1:7600,10.0.0.1:7600
//   CONCORD_HOOK_LISTEN=10.0.0.1:7601

export const concord: App<Host, typeof ZONES> = {
  name: 'concord',
  host: 'web',
  routes: [
    // Private plane only: the UI and API. Add the token here (a secret file
    // with `proxy_set_header Authorization "Bearer …";`, via secretInclude)
    // and the UI and CLI need no login through this route.
    { names: ['concord.internal.example.com'], listen: 'private', upstream: { address: '10.0.0.1', port: 7600 } },
    // Public: ONLY the webhook server. Nothing else is on that port.
    { names: ['concord-hook.example.com'], listen: 'public', upstream: { address: '10.0.0.1', port: 7601 } },
  ],
}

Then point the GitHub webhook at https://concord-hook.example.com/hook.