Skip to main content

Private Registry (Core Layer) — The core layer runs a private Docker registry on the same server as the stack. ⬆ índice

Private Registry (Core Layer)

The core layer runs a private Docker registry on the same server as the stack.

Security model (important)​

  • The registry listens on the server loopback only (127.0.0.1:5000 by default).
  • It is intentionally not exposed publicly (no direct access from your laptop).
  • Operator-side pushes/pulls happen via an SSH tunnel.

Open a tunnel:

./infra remote tunnel <host|number> registry
curl -fsS http://127.0.0.1:5000/v2/
docker login 127.0.0.1:5000

Publish images (build locally, push to remote registry)​

This is a publish-only workflow (no deploy). It runs on your machine and requires your local Docker daemon.

./infra registry publish <host|number> <project>

Important distinction:

  • ./infra build <project> only builds locally.
  • ./infra registry publish <host> <project> pushes the built image to the remote private registry.
  • ./infra remote deploy <host> <project> updates the remote server to use the published image.

Normal full flow for one app:

./infra build <project>
./infra registry publish <host|number> <project>
./infra remote deploy <host|number> <project>

Single-line example for Portal:

./infra build portal && ./infra registry publish <host|number> portal && ./infra remote deploy <host|number> portal

Equivalent built-in shortcut:

./infra release <host|number> portal

If the operator machine does not have Docker available, use the remote fallback:

./infra registry publish-remote <host|number> <project>
./infra remote deploy <host|number> <project>

Equivalent built-in shortcut:

./infra release <host|number> <project> --remote-build

This fallback is useful when remote deploy alone keeps reusing an old image even though the remote .env changed.

Common failures:

  • controller Docker daemon is not running: start Docker on your machine (this command builds locally).
  • skopeo is required: run ./infra setup prereqs --yes.

Tags and versioning​

Publishing always creates:

  • an immutable deploy-id tag (unique per publish run; used for deterministic deploys)
  • an optional stable VERSION tag (human tag), when a version is detected for the project

Version detection sources:

  • VERSION= in <project>/project.conf, or
  • package.json (for Node projects) when supported by the helper

The publish command may offer to write/update VERSION in project.conf to keep a single source of truth.

Inspect and cleanup​

List repositories (via tunnel):

./infra registry catalog

List tags for a repo (via tunnel):

./infra registry tags <repo>

Delete one tag (manifest) (via tunnel):

./infra registry delete <host|number> <repo> <tag>

Prune old manual tags (optional cleanup helper):

./infra registry prune-manual <host|number> <repo> --keep 3 --yes

Verify a deploy is using registry images​

On the server, check container images:

./infra remote ssh <host|number> -- docker ps --format 'table {{.Names}}\t{{.Image}}'

For a given project, you should see images pointing at the internal registry host (127.0.0.1:5000/...:<deploy-id>).