compose.yaml

name: pkg-cache

x-daemonless:
  title: "Daemonless pkg cache"
  type: appliance
  icon: ":material-package-variant-closed:"
  category: "Infrastructure"
  description: "Managed FreeBSD pkg caching appliance — proxies pkg.FreeBSD.org to speed up package fetches across image builds and insulate them from upstream rate limits/outages."
  upstream_url: "https://github.com/daemonless/pkg-cache"
  web_url: "https://daemonless.io/images/pkg-cache/"
  freshports_url: ""
  user: "bsd"
  mlock: false
  upstream_binary: false
  community: "Discord:https://discord.gg/Kb9tkhecZT"
  appjail: true
  notes: |
    ### How it works

    Package files (`*.pkg`) are cached for 365 days — their filenames are
    versioned and immutable, so a HIT is always safe. Catalog metadata
    (`meta.conf`, `packagesite.*`, `data.*`) is cached for 1 minute instead,
    so `pkg` keeps resolving the latest updates without serving stale
    catalogs.

    ### Linux package managers

    apt (Debian, Ubuntu), dnf (Fedora, EPEL), apk (Alpine) and pacman (Arch
    Linux) can come through the cache too. Each is off until its switch is
    on: `PKG_CACHE_APT`, `PKG_CACHE_DNF`, `PKG_CACHE_APK`, `PKG_CACHE_PACMAN`.
    They live under their own paths (`/debian/`, `/ubuntu/`, `/fedora/`,
    `/epel/`, `/alpine/`, `/archlinux/`), with the same rules: packages are
    kept, indexes are refreshed every minute, and signatures still verify on
    the client. The landing page has the command for each distribution, with
    this cache's address filled in. Every family shares `PKG_CACHE_SIZE`:
    with Debian, Ubuntu or Fedora on, give it more than FreeBSD alone needs.

    ### Pointing clients at the cache

    On a build host (or any FreeBSD box), drop in
    `/usr/local/etc/pkg/repos/FreeBSD.conf`:

    ```ini
    FreeBSD: {
      url: "http://<cache-host>/${ABI}/quarterly",
      mirror_type: "none",
      signature_type: "fingerprints",
      fingerprints: "/usr/share/keys/pkg",
      enabled: yes
    }
    ```

    Use plain `http://`, not `pkg+http://` — pkg on FreeBSD 15 rejects the
    `pkg+` scheme unless `mirror_type` is `srv`.

    Then `pkg update` fetches through the cache — first pull is a MISS,
    everything after is a HIT, and package signatures still verify end-to-end.

    `pkg audit` can use the cache too — the appliance proxies the FreeBSD
    vulnerability database at `/vuxml/`:

    ```sh
    echo 'VULNXML_SITE = "http://<cache-host>/vuxml/vuln.xml.xz";' >> /usr/local/etc/pkg.conf
    ```

    No nginx config is required; the appliance renders its managed config at startup from environment variables. Size the `/cache` volume to at least `PKG_CACHE_SIZE` (default 50G — a full set of packages for one FreeBSD release and arch is around 10G).

    ### Stats

    Open `http://<cache-host>/` in a browser. The landing page shows the hit
    rate, bytes served from cache versus fetched upstream, cache disk usage,
    top clients and the most recent requests, refreshed every few seconds.
    Nothing to enable; the same numbers are at `/stats.json`.

  docs:
    env:
      TZ: "Timezone for the container"
      PKG_UPSTREAM:
        desc: "FreeBSD pkg mirror to proxy, e.g. pkg1.us.freebsd.org or pkg0.eu.freebsd.org. Defaults to the primary pkg.FreeBSD.org."
        default: "pkg.FreeBSD.org"
      PKG_CACHE_SIZE:
        desc: "Max on-disk cache size (nginx max_size), e.g. 10g, 100g, 500g. Keep the /cache volume at least this big."
        default: "50g"
      SKIP_CHOWN:
        desc: "Skip the startup recursive chown of /config and /cache once ownership is recorded in /config/.chown_done (default true). Set false to force a chown on every start. The marker lives in /config, so /config must be a persistent volume for the skip to take effect across restarts."
        default: "true"
      PKG_CACHE_APT:
        desc: "Cache apt repositories (Debian and Ubuntu) under /debian/, /debian-security/, /ubuntu/, /ubuntu-security/ and /ubuntu-ports/: true or false."
        default: "false"
      PKG_CACHE_DNF:
        desc: "Cache dnf repositories (Fedora and EPEL) under /fedora/ and /epel/: true or false."
        default: "false"
      PKG_CACHE_APK:
        desc: "Cache Alpine's apk repositories under /alpine/: true or false."
        default: "false"
      PKG_CACHE_PACMAN:
        desc: "Cache Arch Linux's pacman repositories under /archlinux/: true or false."
        default: "false"
      PKG_DEBIAN_UPSTREAM:
        desc: "Debian mirror for /debian/, as a URL base."
        default: "https://deb.debian.org/debian"
      PKG_DEBIAN_SECURITY_UPSTREAM:
        desc: "Debian security mirror for /debian-security/, as a URL base."
        default: "https://deb.debian.org/debian-security"
      PKG_UBUNTU_UPSTREAM:
        desc: "Ubuntu mirror for /ubuntu/ (amd64), as a URL base, e.g. https://us.archive.ubuntu.com/ubuntu."
        default: "https://archive.ubuntu.com/ubuntu"
      PKG_UBUNTU_SECURITY_UPSTREAM:
        desc: "Ubuntu security mirror for /ubuntu-security/, as a URL base."
        default: "https://security.ubuntu.com/ubuntu"
      PKG_UBUNTU_PORTS_UPSTREAM:
        desc: "Ubuntu mirror for /ubuntu-ports/ (arm64 and other architectures), as a URL base."
        default: "https://ports.ubuntu.com/ubuntu-ports"
      PKG_FEDORA_UPSTREAM:
        desc: "Fedora mirror for /fedora/, as a URL base ending at the directory that holds releases/ and updates/. The default is Fedora's master; a mirror near you is kinder, e.g. https://mirror.example.org/fedora/linux. It must answer itself: a mirror that redirects bypasses the cache."
        default: "https://dl.fedoraproject.org/pub/fedora/linux"
      PKG_EPEL_UPSTREAM:
        desc: "EPEL mirror for /epel/, as a URL base."
        default: "https://dl.fedoraproject.org/pub/epel"
      PKG_ALPINE_UPSTREAM:
        desc: "Alpine mirror for /alpine/, as a URL base."
        default: "https://dl-cdn.alpinelinux.org/alpine"
      PKG_ARCH_UPSTREAM:
        desc: "Arch Linux mirror for /archlinux/, as a URL base (the directory that holds core/ and extra/)."
        default: "https://geo.mirror.pkgbuild.com"
      PKG_LOG_MAX_SIZE:
        desc: "Size cap for each on-disk log in /config/log (access.log, error.log), e.g. 10m, 50m, 1g. A log past this is rotated away so /config can't fill; the stats totals are kept separately and survive rotation."
        default: "50m"
    volumes:
      /config: "Logs (log/), stats totals (stats/) and the startup ownership marker (.chown_done). Mount as a persistent volume so the chown is skipped on later starts."
      /cache: "Package cache storage (proxy_cache). Size to match max_size in nginx.conf (default 50G)."
    ports:
      80: "HTTP — pkg clients point their FreeBSD.conf url here; browsers get the stats page"

services:
  pkg-cache:
    image: ghcr.io/daemonless/pkg-cache:latest
    container_name: pkg-cache
    restart: unless-stopped

    environment:
      - TZ=UTC
      - PKG_UPSTREAM=pkg.FreeBSD.org
      - PKG_CACHE_SIZE=50g
      - SKIP_CHOWN=true
      - PKG_LOG_MAX_SIZE=50m
      - PKG_CACHE_APT=${PKG_CACHE_APT:-false}
      - PKG_CACHE_DNF=${PKG_CACHE_DNF:-false}
      - PKG_CACHE_APK=${PKG_CACHE_APK:-false}
      - PKG_CACHE_PACMAN=${PKG_CACHE_PACMAN:-false}

    volumes:
      - /containers/pkg-cache:/config
      - /containers/pkg-cache/cache:/cache

    ports:
      - 80:80