Installation

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

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.

After the first run

• .env holds every tunable — image tags, port bindings, database credentials, integration keys. It is never committed. Back it up.
• 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.

Updating

Upgrades of a populated install go 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. See README § Updating and Architecture on schema ownership.

Versions are pinnable and rollback is supported through the forge-deploy CLI; docker-compose.pin.yml records the pinned tags.

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.