Configuration and deploy

Running locally#

Requires Node.js 22.18 or later (.nvmrc). There are no runtime dependencies.

npm install                    # dev tools only: typescript, @types/node
npm start                      # API, marketing page (/) and app (/app) on http://127.0.0.1:8080
npm run dev                    # same, restarting on TypeScript changes
npm run check                  # typecheck + tests + e2e (what CI's check job runs, plus the harness)
npm run keygen                 # print a new Ed25519 signing key (PEM) for SIGNING_KEY_PEM
DEMO_PUBLISHERS=on npm start   # also serve and route to the five demo publishers
WIKIMEDIA_SOURCES=all npm start   # also route to live Wikinews and Wikipedia

Local runs use an ephemeral signing key, leave /v1/admin/* open (unless ADMIN_TOKEN is set) and append ledger and telemetry records to var/*.jsonl.

Environment variables#

All configuration is environment variables, read by src/config.ts. Out-of-range values stop startup with an error naming the variable.

Credentials for http-offer publishers are also environment variables, named by each source's auth_token_env in the sources file.

The deployed demo (Fly.io)#

The public demo runs at https://clearexchange.ai (landing page), https://app.clearexchange.ai (app and API) and https://docs.clearexchange.ai (docs), all also served at https://clear-exchange.fly.dev: Fly app clear-exchange, region lhr, built from Dockerfile with fly.toml. It deploys only from GitHub Actions: every push to main that passes CI is deployed. Nobody runs flyctl or logs in to Fly by hand.

What fly.toml and the image set:

• NODE_ENV=production, HOST=0.0.0.0, PORT=8080, PUBLIC_URL=https://app.clearexchange.ai (the canonical issuer; see Hostnames), VAR_DIR="" (ledger and telemetry in memory).
• WIKIMEDIA_SOURCES=wikinews,wikipedia and DEMO_PUBLISHERS=on, so the demo shows live supply and routing across several sources.
• SITE_HOSTS=clearexchange.ai,www.clearexchange.ai, APP_HOSTS=app.clearexchange.ai and DOCS_HOSTS=docs.clearexchange.ai, so each hostname serves its own part and old paths redirect (Hostnames). https://docs.clearexchange.ai serves the docs at its root. The image includes docs/ and renders it at startup, so each deploy publishes the docs as committed. See Docs site.
• Fly terminates TLS and force_https redirects plain HTTP. The health check is GET /healthz.
• One machine, always on (auto_stop_machines = "off", min_machines_running = 1, deployed with --ha=false), because offers and sessions live in process memory and an offer made on one machine cannot be accepted on another.
• Ledger and telemetry reset on every restart or deploy. This is deliberate for a demo where no money moves and the publishers are fictional; the JSONL trail is not replayed at startup anyway, and a volume would pin the app to one host. When the ledger matters, the right step is a database behind AppendLog, not a volume. One consequence: an entitlement issued before a restart and retrieved after it is recorded again in the fresh ledger.
• Stable signing key from the SIGNING_KEY_PEM secret, so entitlements and the JWKS survive restarts. Replacing the secret rotates the key and invalidates outstanding entitlements.
• If you rename the app or move the API to another hostname, change PUBLIC_URL to match.

CI and continuous deployment#

.github/workflows/ci.yml runs on every push and pull request:

The deploy job runs in the GitHub environment production, which holds the secrets and accepts only main. It:

1. checks the three secrets are present and well formed (ADMIN_TOKEN ≥ 32 characters, SIGNING_KEY_PEM an Ed25519 key), failing with an error naming any that are missing;
2. creates the Fly app if it does not exist (in vars.FLY_ORG, default personal) and checks primary_region is lhr;
3. stages ADMIN_TOKEN and SIGNING_KEY_PEM on Fly with flyctl secrets set --stage;
4. runs flyctl deploy --remote-only --ha=false (built on Fly's builders);
5. makes sure the app has a public IPv6 and IPv4 address (allocating a dedicated IPv6 and a shared IPv4, both free, only if missing) and prints them with the DNS records for every custom hostname in the log and job summary;
6. makes sure a TLS certificate exists for each hostname in CERT_HOSTNAMES (default clearexchange.ai www.clearexchange.ai app.clearexchange.ai docs.clearexchange.ai) with flyctl certs add, treating "already exists" as success. The job summary shows each certificate's status (see Hostnames and DNS);
7. smoke-checks /healthz, / and /docs/ return 200 and /v1/admin/ledger returns 401 on the fly.dev URL, then checks each custom hostname answers and probes the live sources (both advisory).

Deploys never overlap and CI runs on main are queued rather than cancelled, so an older commit never deploys after a newer one. Secrets reach flyctl only through environment variables on the steps that need them; the third-party setup-flyctl action is pinned to a commit SHA. A deploy whose secrets are wrong fails its health check and Fly keeps the previous release running.

The three GitHub secrets#

Created once, by a repository admin, as environment secrets of production (Settings → Environments → production; restrict deployment branches to main). The workflow never generates them.

If the app must live in an organisation other than the personal one, add an environment or repository variable FLY_ORG with the org slug. If the app name is taken, change app and PUBLIC_URL in fly.toml and FLY_APP in the workflow.

Checking the deployment#

curl -s https://clear-exchange.fly.dev/healthz
curl -s -o /dev/null -w '%{http_code}\n' https://clear-exchange.fly.dev/v1/admin/ledger   # 401
ADMIN_TOKEN="<the saved token>" npm run e2e -- https://clear-exchange.fly.dev

The e2e walkthrough runs query, accept, verify, retrieve and report against the live service and needs ADMIN_TOKEN for its final ledger and telemetry checks. Each run adds a small entry to the demo ledger. Logs are in the Fly dashboard under the clear-exchange app.