Quickstart
Metadata is in PostgreSQL. Bytes go to an S3-compatible bucket or to a directory. With S3, the FerroBox process does not keep the bytes. With the directory, the bytes are on a volume mounted into that same process.
./dev-up.sh starts PostgreSQL, Garage,
and FerroBox. ./dev-up.sh --filesystem is the smaller install: PostgreSQL
and FerroBox only. The published container image does not include
PostgreSQL or Garage. It expects a DATABASE_URL and either the S3_*
variables or STORAGE_BACKEND=filesystem with STORAGE_PATH. The Helm
chart stays a single-node PostgreSQL plus a single-node Garage unless
storage.backend=filesystem and garage.enabled=false, with
replicaCount 1.
Quickstart with Docker Compose
Section titled “Quickstart with Docker Compose”From a fresh clone, one script starts PostgreSQL, Garage, and FerroBox.
The first time it runs, it creates .env and fills the secrets.
Prerequisites
Section titled “Prerequisites”- Docker with the Compose plugin
openssl
Start the stack
Section titled “Start the stack”git clone https://github.com/ferrobox/ferrobox.gitcd ferrobox/infra./dev-up.shinfra/dev-up.sh is executable in the repository. When .env is missing
it copies .env.example, replaces the secret placeholders with values
from openssl rand, and sets the file mode to 600. An existing .env
stays as it is. The S3 access key it writes is GK plus 24 hexadecimal
characters.
The script then starts PostgreSQL and Garage, waits until both report
healthy, runs Garage’s bootstrap (layout, S3 key, and bucket), and starts
the FerroBox server. It prints Web UI: http://localhost:3000. The
published port is FERROBOX_PORT in .env (default 3000). Settings
shows S3 bucket ferrobox.
Directory instead of S3
Section titled “Directory instead of S3”Stop the Garage stack first if it is already running. The container names are shared, and switching storage backends does not copy objects.
cd ferrobox/infradocker compose down./dev-up.sh --filesystemThat starts PostgreSQL and FerroBox only. Bytes go to the ferrobox_blobs
volume, mounted at /var/lib/ferrobox/blobs. Settings shows
Directory /var/lib/ferrobox/blobs. Forge, Mirror, and Alloy stay the
same: the directory is where bytes live for the whole instance, not a new
repository kind.
Open the web UI
Section titled “Open the web UI”- URL: http://localhost:3000
- Username:
admin - Password:
admin
Those are the default ADMIN_USERNAME and ADMIN_PASSWORD. Change them
in .env before the first boot if you want different ones. Change the
password before this port is reachable by anyone else.
The vulnerability feed is empty until you load one. See Vulnerability feed.
Stopping the stack
Section titled “Stopping the stack”From ferrobox/infra:
docker compose downTo stop and delete the data volumes as well:
docker compose down -vOn the Garage install that deletes the PostgreSQL and Garage volumes. On
the directory install it deletes the PostgreSQL volume and
ferrobox_blobs.
SSO via Keycloak is an optional Compose profile
(docker compose --profile sso up -d keycloak). It stays off unless you
start it, and it is separate from the steps above.
Requires Kubernetes and Helm 3.8 or later.
helm install ferrobox oci://ghcr.io/ferrobox/charts/ferrobox --version 0.2.6 \ --namespace ferrobox --create-namespace \ --set image.tag=0.2.6The 0.2.6 chart values set image.tag to 0.2.6. The charts already
published for 0.2.4 and 0.2.5 still have image.tag set to 0.2.2. The
chart bundles a single-node PostgreSQL and a single-node Garage by
default, and generates the admin password, the database password, and the
Garage tokens on first install when you don’t set them. Point
postgresql.externalUrl or s3.external* at your own services to bring
those yourself. See infra/chart/values.yaml in the product repository
for every option.
A directory is optional. It is not the default. 0.2.4 is the release that added it:
helm install ferrobox oci://ghcr.io/ferrobox/charts/ferrobox --version 0.2.6 \ --namespace ferrobox --create-namespace \ --set image.tag=0.2.6 \ --set storage.backend=filesystem \ --set garage.enabled=false \ --set replicaCount=1replicaCount stays 1 because that volume is mounted into the FerroBox
process. Switching storage backends does not copy objects.
After install, helm status ferrobox -n ferrobox prints the admin
credentials and the access URL. The
Configuration reference lists what each setting
does.
docker pull ghcr.io/ferrobox/ferrobox:0.2.6Pin that image by digest:
ghcr.io/ferrobox/ferrobox@sha256:5b1e9998912eba21cfbd455c7d27c44eba0639d222addc64138d4412bf33142fThat digest is the manifest list Cosign signed. docker pull prints it
on the Digest: line. The list contains linux/amd64 and linux/arm64.
The 0.2.6 image shows server version 0.2.6 on Settings and
FerroBox v0.2.6 in the sidebar.
The 0.2.5 tag does not contain linux/arm64. Its digest stays
sha256:609afb8c1ec94acc72a2c6142c9f5e983d88fa5c957d3185d37da2047eb2524a.
The images tagged 0.2.4 and 0.2.5 still show server version 0.2.2 on
Settings and FerroBox v0.2.2 in the sidebar.
The release attaches ferrobox-sbom-linux-amd64.cdx.json and
ferrobox-sbom-linux-arm64.cdx.json. Those files describe the FerroBox
container. A CycloneDX bill for a package stored in a repository is a
separate assay.
Client protocols are unchanged. Inside 0.2.x, migrations add tables and columns. Installing the previous image does not rewind PostgreSQL. A release that removes or renames a column would be a major version; the way back is a database dump plus the storage volume.
Offline bundle
Section titled “Offline bundle”0.2.5 introduced this directory. 0.2.6 keeps it and adds the second architecture. Build it on a connected machine:
cd ferrobox/infra./offline-bundle.sh --version 0.2.6 \ --osv-ref ghcr.io/ferrobox/osv-db:2026-10-12 \ --expect-ferrobox-digest sha256:5b1e9998912eba21cfbd455c7d27c44eba0639d222addc64138d4412bf33142f \ --platform linux/amd64 \ --out "$HOME/ferrobox-offline"--osv-ref is a date tag that exists. 2026-10-12 is one such tag.
--expect-ferrobox-digest is the manifest-list digest above.
--platform linux/amd64 or --platform linux/arm64 chooses which image
docker save writes. Both the FerroBox archive and the PostgreSQL
archive use that architecture. --platform linux/arm64 applies to 0.2.6.
It does not apply to 0.2.5.
The directory contains the FerroBox image, postgres:18-alpine, the Helm
chart, one vulnerability index, osv-sync.pub.pem, and SHA256SUMS.
Garage is not in it. A container scanner is not in it. The index is still
npm, PyPI, crates.io, Maven, NuGet, and Go. It is not an OCI image.
Two signatures are checked while the machine is online. The FerroBox
image is keyless Cosign and needs Sigstore. The vulnerability index is a
Cosign key signature with osv-sync.pub.pem and no transparency log. The
offline machine cannot repeat those checks. It checks SHA256SUMS and
imports the index. install.sh refuses to load the directory on a machine
of the other architecture. Compose is the install that stays inside the
bundle:
cd "$HOME/ferrobox-offline"sha256sum -c SHA256SUMS./install.shinstall.sh loads the FerroBox archive and the postgres:18-alpine
archive, then starts PostgreSQL and FerroBox with the directory at
/var/lib/ferrobox/blobs. Import the gzip with
POST /api/security/osv-feed. The X-FerroBox-Sha256 header is the hex
digest without a sha256: prefix. The Vulnerability feed page then shows
mode file. Sync now pulls from the registry, so it is unused on the
offline machine. Deleting a repository does not delete the feed.
The chart inside the directory is chart/ferrobox-0.2.6.tgz. A Kubernetes
install of that chart still needs the FerroBox image, postgres:18-alpine,
and busybox:1.37 already on the node. It sets the image tag, leaves
Garage out, and stays at one replica:
helm install ferrobox chart/ferrobox-0.2.6.tgz \ --namespace ferrobox --create-namespace \ --set image.tag=0.2.6 \ --set storage.backend=filesystem \ --set garage.enabled=false \ --set replicaCount=1