Skip to content

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.

From a fresh clone, one script starts PostgreSQL, Garage, and FerroBox. The first time it runs, it creates .env and fills the secrets.

  • Docker with the Compose plugin
  • openssl
Terminal window
git clone https://github.com/ferrobox/ferrobox.git
cd ferrobox/infra
./dev-up.sh

infra/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.

Stop the Garage stack first if it is already running. The container names are shared, and switching storage backends does not copy objects.

Terminal window
cd ferrobox/infra
docker compose down
./dev-up.sh --filesystem

That 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.

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.

From ferrobox/infra:

Terminal window
docker compose down

To stop and delete the data volumes as well:

Terminal window
docker compose down -v

On 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.

Terminal window
helm install ferrobox oci://ghcr.io/ferrobox/charts/ferrobox --version 0.2.6 \
--namespace ferrobox --create-namespace \
--set image.tag=0.2.6

The 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:

Terminal window
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=1

replicaCount 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.

Terminal window
docker pull ghcr.io/ferrobox/ferrobox:0.2.6

Pin that image by digest:

ghcr.io/ferrobox/ferrobox@sha256:5b1e9998912eba21cfbd455c7d27c44eba0639d222addc64138d4412bf33142f

That 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.

0.2.5 introduced this directory. 0.2.6 keeps it and adds the second architecture. Build it on a connected machine:

Terminal window
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:

Terminal window
cd "$HOME/ferrobox-offline"
sha256sum -c SHA256SUMS
./install.sh

install.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:

Terminal window
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