Installation

Forge installs as a Docker Compose stack. Everything below runs on the machine that will host Forge.

The canonical, always-current instructions are the umbrella README and the forge-deploy README. This page is the orientation: what the steps are and which one you actually need.

---

The quickest path

On a Linux or macOS box that already has Docker and a docker login ghcr.io:

sudo mkdir -p /opt/forge-deploy && sudo chown "$USER:$(id -gn)" /opt/forge-deploy
npx @armoryworks/forge-deploy /opt/forge-deploy

That downloads the current deploy tree from GitHub and runs interactive setup. The npm package is a thin bootstrapper (Node.js 18+); the deploy tree is always fetched fresh, so there is no stale-package problem.

Prerequisites

Every host needs four things: Docker Engine + the Compose v2 plugin, git, curl and jq (the forge-deploy CLI hard-requires docker/curl/jq).

• RAM: ~4 GB minimum, 8 GB+ recommended. Setup applies tighter container limits automatically on low-RAM hosts.
• Network: outbound access to ghcr.io to pull prebuilt images, unless you build from source.
• Architecture: ARM is fully supported — Raspberry Pi 4/5 and Apple Silicon included. All images are multi-arch.

GHCR authentication is required. The ghcr.io/armoryworks/* packages are not anonymously pullable. Create a GitHub personal access token with only the read:packages scope and run docker login ghcr.io -u <github-username>.

Per-OS prerequisite commands (Debian/Ubuntu, Fedora/RHEL, Arch, macOS, Windows) are spelled out in README Step 0.

Windows: use WSL2. Native PowerShell (setup.ps1) is source-build only and the forge-deploy CLI is bash — version-pinned installs, upgrades and rollback need WSL2 or Linux.

The steps

1. Get the deploy tree — git clone https://github.com/armoryworks/forge-deploy.git /opt/forge-deploy. /opt/forge-deploy is conventional, not required.
2. Run setup.sh — it checks the system, writes .env (generating a random JWT_KEY), asks for a deployment target, pulls images and waits for the API to report healthy.
3. Install the CLI — scripts/install-forge-deploy.sh puts forge-deploy on the path for upgrades, pinning and rollback.

setup.sh modes

Command	What you get
./setup.sh	GHCR-pull — production / evaluation
./setup.sh --seeded	…plus demo users, jobs and customers (prompts for a demo password)
./setup.sh --source	Developer mode: builds images from sibling source repos. This is a build, not a hot-reload loop — for the development inner loop see Developer Setup

Without --seeded, the first visit opens the in-app setup wizard, which creates your first admin account.

Deployment targets

Flag	Exposure
--local	This machine only
--lan	Serves the UI to your network over HTTP at the host's LAN IP
--public	Standalone nginx + self-signed TLS, frees ports 80/443, opens UFW rules
--cohost	Keeps the UI on 127.0.0.1:4200 behind an existing reverse proxy or tunnel

Interactive runs prompt for this; the answer is saved to .env.

If you plan to expose Forge beyond your LAN, note that three capability-gated surfaces answer without a Forge login — the customer portal, the public terms page and public sales-order acceptance. They are switches, and they are off unless you turn them on. See Hardening a Production Install.

After the first run

• Configuration lives in two layers. .env holds what must exist before the process starts — image tags, port bindings, database credentials, JWT_KEY, the backup schedule. Integration credentials are not among them: they are entered in the admin settings screens and stored as encrypted rows in your database, which is why they survive image upgrades. A boot-time hydrator overwrites the environment-bound options from those rows, so the database is authoritative. See Configuration and Integrations.
• .env is never committed, and never appears in a backup. Back it up separately — see Backup and Restore.
• A host network watchdog is installed by default on Linux (--skip-host-watchdog opts out); it restarts networking on persistent failure and reboots a wedged box. It is a no-op on macOS.
• Backups run as a scheduled pg_dump sidecar (daily at 02:00 UTC by default).
• First login walks the setup wizard, then the discovery wizard that decides which features your install turns on.

What to do next

Before	Do this
It faces any user	Work through Hardening a Production Install — several defaults are meant to be changed
You trust it with data	Prove a restore, not just a backup — Backup and Restore
You believe a feature works	Check the integration readiness report; a stock install runs on canned data — Configuration and Integrations
Anyone logs in	Decide who gets what — Access and Roles
You start entering real data	Follow the loading order — First Week

Updating

Upgrades of a populated install carry the schema forward through the forge-deploy schema reconcile step — not through the API. The API's SchemaBootstrapper provisions a fresh database and is a no-op on an existing one, so the reconcile is the only thing that migrates a live install.

Two caveats decide whether it actually runs, and both default against you: ENABLE_SCHEMA_RECONCILE ships false, auto-enabled only on release deploys, and even when enabled it returns success without doing anything when the database is on another machine. Rollback has a matching sharp edge — the reconcile runs before the image swap and schema changes are forward-only.

Read Upgrades and Rollback before your first upgrade. Image tags are pinned by SERVER_IMAGE_TAG, UI_IMAGE_TAG and SCHEMA_IMAGE_TAG in .env, rewritten on every deploy.

Split topologies

Single-node is the default, but the deploy toolchain also supports splitting the UI, API and database across separate machines — without a Kubernetes commitment. See the forge-deploy README for the compose overlays and per-host setup.

One thing to know before you split: the schema reconcile skips on a box whose database lives elsewhere, and reports success anyway. On a split install the database box must run the reconcile explicitly — see Upgrades and Rollback.