Package Cache
MISS · 20 jails pulling pkg.FreeBSD.org over WAN → HIT · Served from local LAN · 365d cached · verified
Pull every package once. Serve it to your hosts, jails, VMs, and container builds over your LAN.
Caching proxy appliance for FreeBSD pkg (including pkg audit VuXML) and Linux apt, dnf, apk, and pacman. No nginx.conf to write, a live stats page with copy-paste client commands on port 80, and package signature verification kept on every client.
Open http://<cache-host>/ in a browser for live hit rates, top clients, and pre-filled client setup commands · View first-boot UI screenshot
Platforms
Runs on FreeBSD and Linux
One multi-OS manifest tag, ghcr.io/daemonless/pkg-cache:latest, resolves to a FreeBSD jail image or a Linux container on both amd64 and arm64.
FreeBSD
amd64arm64
Built on FreeBSD nginx-base. Put /cache on a ZFS dataset and serve packages to hosts, jails, and Containerfile builds on your network.
Linux
amd64arm64
Built on Linux (Alpine) with nginx and s6, running the same startup config renderer, repository switches, log rotator, and stats landing page on amd64 and arm64.
Repositories
One cache for FreeBSD and Linux
FreeBSD pkg and pkg audit are active by default. Set one environment variable per family to cache Linux packages alongside FreeBSD.
FreeBSD
On by default
Caches quarterly and latest binary packages across FreeBSD releases and ABIs (amd64, aarch64), plus the pkg audit vulnerability database (vuxml.freebsd.org).
Debian and Ubuntu
PKG_CACHE_APT=true
Proxies apt repositories including security channels and ubuntu-ports (arm64), keeping .deb pools and by-hash indexes for a year while refreshing dists/ every minute.
Fedora and EPEL
PKG_CACHE_DNF=true
Proxies dnf RPM packages and checksummed repodata/ for 365 days while revalidating repomd.xml every minute.
Alpine Linux
PKG_CACHE_APK=true
Proxies Alpine apk repositories, caching versioned .apk packages for 365 days and refreshing APKINDEX.tar.gz every minute.
Arch Linux
PKG_CACHE_PACMAN=true
Serves as pacman's local mirror, caching .pkg.tar.* archives and .sig files for 365 days while refreshing .db and .files every minute.
Containerfiles
First RUN
In a Containerfile, put the distribution's setup command in the first RUN instruction, before anything is installed, so image builds pull cached packages over your LAN.
How it works
Cached packages, fresh indexes, verified signatures
Public mirrors often send Cache-Control: no-cache or redirect clients away, while generic proxies can serve stale package indexes. Package Cache sets separate rules for package files and metadata.
01 / Immutable packages
Cached for 365 days
*.pkg · *.deb · *.rpm · *.apk · *.zst
Package filenames include their version and are immutable once published. The first machine pulls upstream (MISS); later requests get a local HIT, with automatic LRU eviction at PKG_CACHE_SIZE.
02 / Live indexes and lock coalescing
1-minute metadata and stale fallback
proxy_cache_lock · use_stale 5xx
Catalogs (packagesite.tzst, dists/, repomd.xml, APKINDEX.tar.gz) refresh after 1 minute using If-Modified-Since. When several machines fetch the same uncached file at once, proxy_cache_lock sends one upstream download and serves cached copies during upstream 5xx errors.
03 / End-to-end verification
Client signatures stay enabled
/usr/share/keys/pkg · GPG · pacman-key
Signature checking stays on every client. FreeBSD pkg fingerprints, Debian and Ubuntu apt keys, Fedora RPM GPG keys, Alpine keys, and the Arch keyring verify packages on the client before install.
Client setup
Point hosts, jails, and builds at the cache
Open http://<cache-host>/ in a browser for commands filled in with your cache's address, or copy them below. See Client setup for full details.
Drop /usr/local/etc/pkg/repos/FreeBSD.conf on any FreeBSD host or jail. Use FreeBSD-ports on FreeBSD 15 (check pkg -vv) or FreeBSD on FreeBSD 14, and use plain http:// with mirror_type: "none":
mkdir -p /usr/local/etc/pkg/repos
cat > /usr/local/etc/pkg/repos/FreeBSD.conf <<'EOF'
FreeBSD-ports: {
url: "http://pkg-cache.home.lan/${ABI}/quarterly",
mirror_type: "none",
signature_type: "fingerprints",
fingerprints: "/usr/share/keys/pkg",
enabled: yes
}
EOF
pkg update
Fetch the pkg audit vulnerability database through the cache too:
Turn on PKG_CACHE_APT=true on the cache, then point apt at it:
# Debian 12 and later (/etc/apt/sources.list.d/debian.sources)
sed -i 's|http://deb.debian.org/|http://pkg-cache.home.lan/|' /etc/apt/sources.list.d/debian.sources
apt-get update
# Ubuntu 24.04 and later (archive, security, and ubuntu-ports)
sed -i -e 's|http://archive.ubuntu.com/ubuntu/|http://pkg-cache.home.lan/ubuntu/|' \
-e 's|http://security.ubuntu.com/ubuntu/|http://pkg-cache.home.lan/ubuntu-security/|' \
-e 's|http://ports.ubuntu.com/ubuntu-ports/|http://pkg-cache.home.lan/ubuntu-ports/|' \
/etc/apt/sources.list.d/ubuntu.sources
apt-get update
Turn on PKG_CACHE_DNF=true on the cache (with a non-redirecting PKG_FEDORA_UPSTREAM mirror), then switch dnf from metalink to baseurl:
Install
Deploy on FreeBSD or Linux
Mount persistent /config and /cache directories, publish port 80, and open http://<cache-host>/.
- Open fjord on your FreeBSD or Linux host.
- Find Daemonless pkg cache in the catalog and click Install.
- Turn on any Linux repository switches (
PKG_CACHE_APT,PKG_CACHE_DNF,PKG_CACHE_APK,PKG_CACHE_PACMAN) in Settings if you also cache Linux machines, then openhttp://<host-ip>/.
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
Start it with podman-compose up -d, then open http://<server>:80. For FreeBSD pf port forwarding, boot auto-start (restart: always), interactive path placeholders, and AppJail Director or Bastille bundles, see the Host setup guide and the Daemonless pkg cache image page.
podman run -d --name pkg-cache \
--restart always \
-p 80:80 \
-e PKG_UPSTREAM=pkg.FreeBSD.org \
-e PKG_CACHE_SIZE=50g \
-v /containers/pkg-cache:/config \
-v /containers/pkg-cache/cache:/cache \
ghcr.io/daemonless/pkg-cache:latest
See the Daemonless pkg cache image page for AppJail Director and Bastille deployment files.
Documentation
Setup and operations guides
Storage sizing, ZFS setup, client commands for FreeBSD and Linux, mirror selection, and /stats.json monitoring.
1
Size `/cache`
Default PKG_CACHE_SIZE is 50g (about 10G per FreeBSD release and architecture; give it more with Linux families on).
2
Start the appliance
Deploy on port 80 with persistent /config and /cache volumes.
3
Pick mirrors
Point PKG_UPSTREAM and optional Linux mirror variables at non-redirecting mirrors near you.
4
Point your clients
Run the client command for each machine or Containerfile, then watch hits at http://<cache-host>/.
FreeBSD and Linux setup, ZFS dataset creation, cache sizing, and all PKG_* environment variables.
Client commands for FreeBSD 14 and 15 (FreeBSD-ports, pkg audit), Debian, Ubuntu, Fedora, EPEL, Alpine, Arch, and Containerfile builds.
Mirrors, stats API, and troubleshooting →
Upstream mirror selection, why redirecting mirrors bypass caches, /stats.json and /healthz schemas, log rotation, and common fixes.
Downloadable Podman Compose, AppJail Director, and Bastille bundles with path and port placeholders.