pkg-cache/compose.yaml at main · daemonless/pkg-cache · GitHub

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
name: pkg-cache

x-daemonless:
  title: "Daemonless pkg cache"
  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.

    ### 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 — 10G is plenty for a handful of hosts/images, bump it up if you're caching a large fleet).

  readme:
    version_tags: |
      | Tag | Description | Best For |
      | :--- | :--- | :--- |
      | `latest` | **daemonless Appliance**. Managed FreeBSD pkg cache proxy built on nginx-base. | Shared package cache for daemonless builds and FreeBSD hosts. |

  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. 10g is plenty for light use; keep the /cache volume at least this big."
        default: "50g"
      ENABLE_STATS:
        desc: "Set to true to enable the GoAccess real-time stats dashboard on port 7890."
        default: "false"
      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"
    volumes:
      /config: "Logs, generated stats storage (log/, 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; 10G is fine for light use)."
      /etc/resolv.conf: "Host DNS resolver config. Optional but recommended so upstream pkg resolution matches the host."
    ports:
      80: "HTTP — pkg clients point their FreeBSD.conf url here"
      7890: "GoAccess stats dashboard (HTML) — enabled via ENABLE_STATS=true"

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
      - ENABLE_STATS=false
      - SKIP_CHOWN=true

    volumes:
      - /containers/pkg-cache:/config
      - /containers/pkg-cache/cache:/cache
      - /etc/resolv.conf:/etc/resolv.conf:ro

    ports:
      - 80:80
      - 7890:7890