Package cache¶

Description¶

Nexus Repository is a repository manager that proxies package registries and serves an artefact it has already fetched from local disk. nginx sits in front of it and answers for the upstream hostnames themselves, so a package manager keeps the URLs it was built with and still reads through the proxy.

Overview¶

The role deploys two containers on its inventory group’s host: the repository manager and its nginx frontend. Both run in compose mode on the manager, like the sibling svc-registry-cache.

upstreams.conf.j2 is rendered to the host and mounted into the frontend as conf.d/upstreams.conf. Its content comes from the cache: sections of the roles’ meta/networks.yml, so no hostname, repository or upstream URL is written in this role.

compose.cache-consumer.yml.j2, apt.list.j2, npmrc.j2 and pip.conf.j2 under templates/, and the shell scripts under files/, belong to the development compose stack, which drives them through render.py and compose.py. The Ansible deployment reads none of them.

Architecture¶

ARCHITECTURE.md draws Package cache from its own metadata: the containers it runs under compose, what changes under swarm, how each volume is backed, and every role it depends on or is depended upon by.

Section	Drawn from
Compose	`meta/services.yml`
Swarm	`meta/services.yml` replicas and placement
Volumes	`meta/volumes.yml` against the NFS decision chain
Dependencies	`meta/services.yml` and `meta/main.yml` of every role

Features¶

Declaration driven: Every proxied repository and every answered hostname comes from the cache: declarations, collected by the cache_upstreams and cache_repos lookups. A new upstream is added by declaring it there.
Mirror failover: A repository that declares a mirror is served through a guarded location: a 5xx from its primary remote re-runs the same path against the sibling repository, while a 404 is passed straight back.
Persistent store: Proxied artefacts live in a named volume, so a redeploy reuses what earlier runs already pulled.
Backup free: The volume is backup-disabled and its backup consumer stays off; every artefact in it is re-fetchable from its upstream.
Self-provisioning: A bootstrap sidecar runs bootstrap.sh from inside the stack whenever the cache starts, gated on the repository manager’s healthcheck. It re-creates every declared repository on a /nexus-data that came back empty. The deploy runs the same script from the host, over docker exec, so a deployment converges before its tasks finish.

Quick Setup¶

Development¶

Clone, set up the workstation, and deploy Package cache onto the local stack:

git clone https://github.com/infinito-nexus/core.git
cd core
make onboard
make compose-deploy mode=reinstall apps=svc-cache-package full_cycle=false

Production¶

Run the published image to provision the inventory and deploy Package cache to a managed server over SSH. The image logs in as root, so the server must accept root over a public key, and the two key variables are the two halves of one key pair: the private half authenticates the deploy, and the public half is what the deploy keeps authorized for root and installs for the administrator account. Naming a public half that does not belong to the private one locks the running deploy out at its next reconnect.

APP=svc-cache-package
HOST="<your-server>"
DOMAIN="<your-domain>"
TLS_MODE=self_signed
SSH_PUBLIC_KEY="<your-ssh-public-key>"
SSH_PRIVATE_KEY="<your-ssh-private-key-file>"
WORKDIR="$HOME/.infinito.nexus"

mkdir -p "$WORKDIR/inventories"
docker run --rm \
  -v "$WORKDIR/inventories:/etc/infinito.nexus/inventories" \
  -v "$SSH_PRIVATE_KEY:/run/secrets/deploy_key:ro" \
  -e APP="$APP" -e HOST="$HOST" -e DOMAIN="$DOMAIN" -e TLS_MODE="$TLS_MODE" -e SSH_PUBLIC_KEY="$SSH_PUBLIC_KEY" \
  ghcr.io/infinito-nexus/core/debian:latest bash -c '
    INVENTORY=/etc/infinito.nexus/inventories/production
    infinito administration inventory provision "$INVENTORY" \
      --inventory-file "$INVENTORY/devices.yml" \
      --host "$HOST" \
      --include "$APP" \
      --vars "{\"TLS_MODE\": \"$TLS_MODE\", \"DOMAIN_PRIMARY\": \"$DOMAIN\", \"SYS_SVC_SSHD_PERMIT_ROOT_LOGIN\": \"prohibit-password\", \"users\": {\"root\": {\"authorized_keys\": [\"$SSH_PUBLIC_KEY\"]}, \"administrator\": {\"authorized_keys\": [\"$SSH_PUBLIC_KEY\"]}}}" &&
    infinito administration deploy dedicated "$INVENTORY/devices.yml" \
      --password-file "$INVENTORY/.password" \
      -u root --private-key /run/secrets/deploy_key \
      --diff -vv'

The inventory under $WORKDIR is written by the container as root, including the vault password at inventories/production/.password. Run sudo chown -R "$USER" "$WORKDIR" afterwards to read it.

Credits¶

Kevin Veen-Birkenbach

Part of the Infinito.Nexus Project and maintained by Kevin Veen-Birkenbach. Licensed under the Infinito.Nexus Community License (Non-Commercial).

That licence covers this role. The software it deploys is a separate grant: EPL-1.0, under which commercial use is allowed. You owe its authors this much: publish the source of changes you distribute. Permission for one of the two is not permission for the other.