In a container

running pkgproxy for users for administrators for CI operators

pkgproxy as an OCI image for docker, podman and Kubernetes, run by Pebble as a user of its own, its cache on a volume, its settings as environment variables or flags, with a health check and a stop that lets requests finish.

On the map: running pkgproxy

▶ Watch this deck — 6 scenes, ~4 min

Part of journeys

01 What this topic covers

ABOUT THIS TOPIC In a container pkgproxy as an OCI image, for docker, podman and Kubernetes 1 One binary and Pebble 2 A volume for the cache 3 Settings: variables and flags 4 Ready, and a stop that waits
The topic title, In a container, and its 4 scenes in order: One binary and Pebble, A volume for the cache, Settings: variables and flags, Ready, and a stop that waits

The pkgproxy image: what is in it, running it with a cache volume, its settings, and its health check and stop.

pkgproxy is also an OCI image, for docker, podman and Kubernetes, for when you would rather not install the snap. You will see what the image holds and how it starts. Then you run it with a volume for the cache, and give it settings as environment variables or flags. Last come its health check, and how to stop it without cutting requests short.

02 One binary and Pebble

THE IMAGE registry.gitlab.com/zygoon/pkgproxy · base: bare /usr/bin/pkgproxy /usr/bin/pkgproxyctl → pkgproxy CA certificates Pebble: the entrypoint no shell service pkgproxy runs as UID and GID 584792, not root /var/cache/pkgproxy owned by 584792, ready for a volume
The image as a box: the pkgproxy binary with pkgproxyctl as a second name, CA certificates and Pebble, with no shell; Pebble starts pkgproxy as user 584792, which owns /var/cache/pkgproxy

A base: bare rock for amd64: /usr/bin/pkgproxy, pkgproxyctl as a symlink, CA certificates and Pebble, no shell. It runs as UID and GID 584792; /var/cache/pkgproxy is owned by it.

The image is built with rockcraft on a bare base. It holds the pkgproxy binary, with pkgproxyctl as a second name for it, the CA certificates for upstreams reached over HTTPS, and Pebble, which is its entrypoint. There is no shell. Pebble starts pkgproxy as a service, as a user of its own with the ID 584792, not as root. The cache directory, /var/cache/pkgproxy, is ready in the image and owned by that user.

03 A volume for the cache

DOCKER RUN $ docker volume create pkgproxy-cache $ docker run -d --name pkgproxy --restart unless-stopped \ -v pkgproxy-cache:/var/cache/pkgproxy \ -p 3142:3142 -p 3143:3143 \ registry.gitlab.com/zygoon/pkgproxy:edge a new named volume takes its owner from the image: ready as it is $ sudo chown 584792:584792 /srv/pkgproxy a host directory first; or mount it with podman's :U no volume: the cache is lost with the container
A terminal creates a named volume and runs the image with it mounted at /var/cache/pkgproxy and ports 3142 and 3143 published; below, a host directory must be chowned to 584792 first, and without a volume the cache goes with the container

docker volume create pkgproxy-cache, then docker run -v pkgproxy-cache:/var/cache/pkgproxy -p 3142:3142 -p 3143:3143. A bind mount needs chown 584792:584792, or podman's :U.

The image declares no volume and no port; you choose them when you run it. Create a named volume, mount it at /var/cache/pkgproxy, and publish ports 3142, and 3143 for LXD. A new named volume takes the directory's owner from the image, so it is ready as it is. A host directory is not: give it to user 584792 first, or let podman do it. Without a volume, the cache is lost with the container.

04 "Settings: variables and flags"

SETTINGS no PKGPROXY_ setting in the image: the daemon's defaults $ docker run ... -e PKGPROXY_PUBLIC_URL=http://cache.example:3142 ... $ docker run ... registry.gitlab.com/zygoon/pkgproxy:edge --args pkgproxy -addr=:8080 a flag wins over a variable $ docker logs pkgproxy the log, and why a value was refused $ docker exec pkgproxy pkgproxyctl stats finds the daemon with no flags
Two ways to set an option: -e PKGPROXY_PUBLIC_URL, or flags after --args pkgproxy; the flag wins; docker logs shows the log and docker exec runs pkgproxyctl stats

-e PKGPROXY_PUBLIC_URL=…, or --args pkgproxy -addr=:8080; a flag wins. docker logs pkgproxy shows the log; docker exec pkgproxy pkgproxyctl stats needs no flags.

The image sets no pkgproxy setting of its own; the defaults suit a container. To change one, pass its environment variable with docker run -e, such as the public URL. Or pass flags after --args pkgproxy, which replace the service's empty arguments. A flag wins over a variable. The log goes to docker logs, and an invalid value is explained there. pkgproxyctl runs inside the container with docker exec, and finds the daemon without any flags.

05 Ready, and a stop that waits

HEALTH AND STOPPING Pebble check GET localhost:3142/pkgproxy/v1/health another -addr port: the check fails pkgproxy exits → the container exits → your restart policy decides an invalid setting: a stopped container with its message in the log, not a restart loop requests finish: up to 10 s docker stop waits 10 s in all $ docker stop -t 20 pkgproxy
Pebble's health check asks /pkgproxy/v1/health on port 3142; when pkgproxy exits the container ends and its restart policy decides; on stop pkgproxy needs up to 10 seconds, docker waits 10 in all, so use docker stop -t 20

The health check asks http://localhost:3142/pkgproxy/v1/health. pkgproxy exiting ends the container. Pebble's kill-delay is 15s; use docker stop -t 20 pkgproxy.

Pebble checks that pkgproxy is ready by asking its health route on port 3142. If you move pkgproxy to another port, that check fails. When pkgproxy exits, the container exits with it, and your restart policy decides what comes next, so an invalid setting shows as a stopped container, not a restart loop. On a stop, pkgproxy takes up to ten seconds to finish requests in progress, and docker waits only ten in all, so stop it with docker stop -t 20.

06 Where to go next

WHERE NEXT pkgproxy as a container, its cache on a volume you are here In a container pkgproxyctl setup point your tools at the container's address Settings every setting the image takes On Kubernetes the same image under Juju
Where next from In a container: pkgproxyctl setup, pointing your tools at it; Settings, every option the image takes; On Kubernetes, the same image under Juju

Next: pkgproxyctl setup, to point your tools at it; Settings, for every option; On Kubernetes, for the image under Juju.

Instead of installing the snap, you can now run pkgproxy as a container, with its cache on a volume that outlives it. To point your tools at the container, watch pkgproxyctl setup, and give it the address your machines reach it on. For every setting the image takes, watch Settings. To run the same image on Kubernetes with Juju, watch On Kubernetes.

Read more

The image

Nameregistry.gitlab.com/zygoon/pkgproxy
Tagsedge follows the main branch; each release has its own tag, such as v0.13.0
Architectureamd64 (the published image)
Basebare: the static binary, CA certificates and Pebble, no shell
EntrypointPebble, which starts the pkgproxy service
UserUID and GID 584792, for Pebble and pkgproxy
Versiongit describe with - for +: v0.12.1, or v0.12.1-git5.abc1234 after a tag

Files

PathWhat it holds
/usr/bin/pkgproxythe daemon
/usr/bin/pkgproxyctla symlink to the same binary
/var/cache/pkgproxythe cache; mount a volume here. Owned by 584792
/run/pkgproxythe stats and admin sockets, made again at every start; needs no volume

The image declares no volume and no port. A new named docker or podman volume is seeded from the image, owner included. A host directory must be owned by 584792 (chown 584792:584792), or mounted with podman's :U. The cache needs extended attributes; named volumes and most host directories have them.

Ports

PortFor
3142every client but LXD, the setup page and the health route
3143LXD's image server, over TLS

Settings

An option comes from, strongest first:

1. A flag after --args pkgproxy: docker run IMAGE --args pkgproxy -addr=:8080. 2. The container's environment: docker run -e PKGPROXY_NAME=value, or a pod's env. 3. The daemon's default.

The image sets no PKGPROXY_* variable; its only variable is PEBBLE_VERBOSE=1, so that docker logs shows pkgproxy's log. See Settings for every option.

Service and health

Health checkhealth, level ready: GET http://localhost:3142/pkgproxy/v1/health. It fails when -addr names another port
When pkgproxy exitsPebble shuts down and the container ends; the runtime's restart policy decides what comes next
Kill delay15s, above pkgproxy's 10s shutdown grace
Stoppingdocker stop -t 20 pkgproxy; docker waits only 10s by default. Kubernetes gives a pod 30s

Commands

docker volume create pkgproxy-cache docker run -d --name pkgproxy --restart unless-stopped \ -v pkgproxy-cache:/var/cache/pkgproxy \ -p 3142:3142 -p 3143:3143 \ registry.gitlab.com/zygoon/pkgproxy:edge docker logs pkgproxy docker exec pkgproxy pkgproxyctl stats docker exec pkgproxy pkgproxyctl setup apt -addr cache.example:3142 docker stop -t 20 pkgproxy

The setup scripts name the address given with -addr: the one your machines reach the container on.

In the documentation

Roads from here

CORE · the path every side shares

SETUP AND THE COMMAND LINE

RUNNING PKGPROXY

OPERATIONS

  • Settings — every setting the image takes