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
- Operating pkgproxy for CI, step 5 of 12 · previous: Settings · next: On Kubernetes
01 What this topic covers
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
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 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"
-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
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
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
| Name | registry.gitlab.com/zygoon/pkgproxy |
| Tags | edge follows the main branch; each release has its own tag, such as v0.13.0 |
| Architecture | amd64 (the published image) |
| Base | bare: the static binary, CA certificates and Pebble, no shell |
| Entrypoint | Pebble, which starts the pkgproxy service |
| User | UID and GID 584792, for Pebble and pkgproxy |
| Version | git describe with - for +: v0.12.1, or v0.12.1-git5.abc1234 after a tag |
Files
| Path | What it holds |
|---|---|
/usr/bin/pkgproxy | the daemon |
/usr/bin/pkgproxyctl | a symlink to the same binary |
/var/cache/pkgproxy | the cache; mount a volume here. Owned by 584792 |
/run/pkgproxy | the 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
| Port | For |
|---|---|
3142 | every client but LXD, the setup page and the health route |
3143 | LXD'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 check | health, level ready: GET http://localhost:3142/pkgproxy/v1/health. It fails when -addr names another port |
| When pkgproxy exits | Pebble shuts down and the container ends; the runtime's restart policy decides what comes next |
| Kill delay | 15s, above pkgproxy's 10s shutdown grace |
| Stopping | docker 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
- Running pkgproxy in a container: the image, volumes, options and commands
Roads from here
CORE · the path every side shares
- The store — what the cache volume holds
- One listener — the health route the image's check asks
SETUP AND THE COMMAND LINE
- Setting up clients — pointing your tools at the container
RUNNING PKGPROXY
- On Kubernetes — the same image on Kubernetes with Juju
- Juju machines — the snap on Juju machines
OPERATIONS
- Settings — every setting the image takes