Linux Administration: Building a Private APT/YUM Mirror for Docker

When you're managing production servers that aren't allowed to reach out to the public internet, apt update or yum update becomes a brick wall. I’ve spent more than a few late nights trying to manually move .deb or .rpm files via USB drives, and I can tell you: it’s a recipe for disaster.

If you’re running a robust Docker infrastructure, you need a reliable way to patch your hosts and manage dependencies without relying on external mirrors. Building a private mirror isn't just about convenience; it’s about controlling your supply chain and ensuring your CI/CD pipelines don't break because an upstream maintainer pulled a package.

The Problem with Air-Gapped Linux Administration

In most of the secure environments I’ve worked in, the network is locked down tight. You can't just apt-get install your favorite tools. We first tried to build a simple web server to host manually downloaded packages, but that quickly turned into a nightmare of dependency hell. You end up chasing individual files and manually resolving metadata, which is essentially doing the package manager’s job by hand.

Instead, you need a tool that speaks the language of the repository. For Debian/Ubuntu-based systems, apt-mirror is the classic choice. For RHEL/CentOS/Rocky environments, reposync is your best friend.

Setting Up Your Self-Hosted Repository

To get started, you’ll need a "bridge" machine—a server that has access to the internet to fetch the packages—and a local storage target. I typically use a dedicated VM or a robust container with persistent storage.

Mirroring APT Repositories

For Debian or Ubuntu, apt-mirror creates a local copy of an entire repository. Here is a basic mirror.list config:

TEXT
set base_path    /var/spool/apt-mirror
set mirror_path  $base_path/mirror
set skel_path    $base_path/skel
set var_path     $base_path/var
set cleanscript  $var_path/clean.sh

deb http://archive.ubuntu.com/ubuntu focal main restricted universe multiverse
deb http://archive.ubuntu.com/ubuntu focal-updates main restricted universe multiverse

Once you run apt-mirror, it’ll pull down the entire index. It usually takes a while—I’ve seen it take about two hours for a full Ubuntu main branch on a standard gigabit connection. Once synced, you serve these files via Nginx.

Mirroring YUM/DNF Repositories

For RHEL-based systems, reposync is cleaner. You don't need a massive config file; you can run it directly from the CLI:

Bash
reposync -p /var/www/html/repos/rocky-8 --repo=baseos --download-metadata

After downloading, you’ll need to generate the repository metadata so your clients can actually read it:

Bash
createrepo /var/www/html/repos/rocky-8/baseos

Integrating with Docker Infrastructure

Once your mirror is live, you need to point your hosts to it. This is where most people get tripped up. You have to update your /etc/apt/sources.list or your .repo files on every single host. If you’re managing more than three servers, do yourself a favor and use Ansible or SaltStack to push these configuration changes.

For your Docker-based workloads, remember that the host's package management is separate from the container's package management. If your containers need to install packages, they’ll also need to point to your internal mirror. You can do this by mounting a custom sources.list or yum.repos.d file into the container at build time.

Security Considerations

Since you’re now the source of truth for your packages, you become the primary target for supply chain attacks. You should implement Linux Security: File Integrity Monitoring with AIDE and Systemd Timers on your mirror server. This ensures that if someone (or something) modifies the binaries in your repository, you’ll know immediately.

Also, consider using eBPF-based File Access Auditing: Track Config Changes with bpftrace to keep an eye on who is accessing your repository configuration files. It’s a great way to verify that only your automation tools are touching your repo files.

FAQ: Common Pitfalls

How much disk space do I need? Expect to allocate at least 200GB to 500GB for a full mirror of a major distribution like Ubuntu or Rocky Linux. It fills up faster than you think.

Do I need to sign my packages? If you’re modifying packages, yes. If you’re just mirroring, the original GPG signatures are preserved. Keep your GPG keys secure—if they're compromised, your entire infrastructure is at risk.

What happens if the mirror sync fails? It happens. I usually set up a simple check script that verifies the checksums of a few core packages. If the sync fails, the script alerts me via my monitoring stack, which I’ve set up using Uptime Kuma Self-Hosted Monitoring: A Simple Guide for VPS Health.

Final Thoughts

Managing a local mirror is a chore, but it’s the price of admission for a truly stable, air-gapped environment. You’ll spend less time debugging "package not found" errors and more time actually building features. Just make sure your mirror server itself is backed up, because losing your repository is effectively losing your ability to deploy. Next time, I’d probably look into more automated solutions like Pulp or Artifactory if the team scales, but for a small to medium setup, a simple Nginx-backed mirror is usually plenty.