Home

This repo is how Forge gets onto a machine and stays there. It holds the Compose file set, the first-run installer, the operator CLI, the doctors, the backup sidecar, and the host services that let an upgrade run from inside the app. No application code lives here — the images it pulls are built in forge-api, forge-ui and forge-db.

The product-level story — what Forge is, how to install it, how to harden it, how backups and upgrades behave — lives on the umbrella wiki. This wiki is the tool reference underneath it: what each script and flag actually does, what the CLI writes where, which combinations are wired for you, and which ones bite.

If you want	Go to
The narrative of installing Forge	Installation (hub)
Day-two operation and the common failures	Operations and Troubleshooting (hub)
What an upgrade does and what rollback can't undo	Upgrades and Rollback (hub)
The subcommands, front doors and scope rules	The CLI
Single box, split roles, and how the pieces reach each other	Topologies
What a setting in .env controls	Environment Reference
A box that is broken, half-installed, or unreachable	Recovery

What is in the tree

Path	What it is
docker-compose.yml	The base stack: UI, API, Postgres/pgvector, MinIO, the backup sidecar, plus profile-gated AI, TTS, logging, crash reporting, signing, and the demo/test SPAs
docker-compose.prod.yml, .cohost.yml, .dev.yml, .bluegreen.yml, .export.yml	Overlays. The CLI composes the right set for you; see The CLI
setup.sh	First-run setup: system detection, .env generation, deployment target, TLS, image pull, bring-up. setup.ps1 is the source-build-only Windows sibling
scripts/forge-deploy	The operator CLI and the guided console. Everything gated goes through here
scripts/forge-preflight	Read-only pre-deploy doctor
doctor.sh	Read-only network-exposure doctor: TLS, firewall, public IP, NAT, an outside-in probe
bin/install.mjs	The @armoryworks/forge-deploy npm bootstrapper — fetches a pinned tree, then hands off
agent/, panel/	Host services: the job executor behind the in-app Updates screen, and a small LAN web panel. Both are thin shells over the same CLI
backup/, maintenance/	The pg_dump sidecar image, and the nginx maintenance page shown during a cutover
scripts/host-watchdog/	The Linux network watchdog installed by default
tools/rfid-relay/	Windows-side relay that feeds badge scans to the kiosk — see Shop Floor Kiosk
scripts/forge-bundle	Air-gap update bundles. A skeleton — the control flow exists, the integration points do not, and it has never run end to end. Design notes

The two rules that matter most

Bring a box up with forge-deploy --up, never bare docker compose up. The CLI knows this box's component scope and its overlay set; bare compose knows neither, starts everything in the file set, and resurrects services you deliberately removed. When you need compose itself, go through forge-deploy compose …. The reasoning is in The CLI.

forge-db owns the schema; this repo runs the reconcile. forge-api ships no EF migrations, and its own bootstrapper is a no-op on a populated database. The forge-deploy schema reconcile is the only thing that carries a live install's schema to a new release — and on a split topology it must be run on the database box. See forge-db for what the reconcile does, and Topologies for who runs it.

Peers

forge-api supplies the image this tree pins as SERVER_IMAGE_TAG and the composite health endpoint the deploy gate polls. forge-ui supplies UI_IMAGE_TAG; its nginx proxies /api and /hubs to a baked-in upstream name, which is why a UI-only box needs the forwarder described in Topologies. forge-db supplies SCHEMA_IMAGE_TAG and the reconcile itself. forge-test and forge-demo are profile-gated SPAs this tree can also serve.

Repo docs worth reading in full: docs/DEPLOY.md, docs/TROUBLESHOOTING.md, docs/backup-restore.md, docs/postgres-18-upgrade.md, docs/email-setup.md, and the CHANGELOG — which is unusually candid about field failures and is the best record of why the tooling behaves as it does.