Innovative Software Technology

Building an Offline Linux Repository: Your Ultimate Guide to Local APT Mirrors

In today’s interconnected world, the ability to manage software packages offline or in isolated environments is becoming increasingly vital. This comprehensive guide will walk you through the process of creating a local mirror for Ubuntu/Debian repositories and establishing your own custom “flat” repositories, ensuring you always have access to the packages you need, regardless of internet connectivity. Whether you’re a system administrator preparing for a disconnected setup or a developer looking to localize your environment, mastering local package management is a powerful skill.

Understanding the Need for Local Repositories

Imagine a scenario where your production Linux server loses internet access, or you need to deploy systems in a completely air-gapped environment. Relying on remote official repositories becomes impossible. This is where local repository mirroring comes into play. By creating a replica of an official repository on your own server, you gain:

  • Offline Access: Install packages without an internet connection.
  • Speed: Faster package downloads within your local network.
  • Control: Pin specific package versions and ensure consistency across deployments.
  • Localization: Meet security or compliance requirements for sensitive environments.

We’ll cover both mirroring official Ubuntu repositories and setting up simple “flat” repositories for custom or third-party .deb packages.

Essential Prerequisites

Before diving into the mirroring process, ensure your mirroring server has the necessary tools installed. These utilities are crucial for managing, exposing, and signing your local repositories.

sudo apt-get update
sudo apt-get install -y apt-utils nginx debmirror gnupg

Here’s a breakdown of what each tool provides:

  • apt-utils: Contains various utilities for APT, including apt-ftparchive, which is essential for generating repository metadata.
  • nginx: A high-performance web server that will serve your local repository files over HTTP.
  • debmirror: A specialized tool designed for creating and updating local mirrors of Debian and Ubuntu repositories.
  • gnupg: The GNU Privacy Guard, used for creating and managing GPG keys to sign your repository, enhancing security and trust.

Mirroring the Official Ubuntu Repository with Debmirror

The debmirror utility simplifies the process of replicating remote Debian/Ubuntu repositories. This method is highly flexible and can be adapted for various vendor repositories, provided you have their repository URL and GPG key.

First, create a dedicated directory on your server to store the mirrored repository data. This example uses /storage/ubuntu:

sudo mkdir -p /storage/ubuntu

The official Ubuntu repository URL we’ll be mirroring is `http://archive.ubuntu.com/ubuntu/`.

Debian-based repositories are structured into Suites and Components:

  • Suites: Represent different releases or distributions (e.g., noble for Ubuntu 24.04, noble-updates for subsequent stable updates).
  • Components: Categorize packages by license or support level (e.g., main for official open-source, restricted for proprietary drivers, universe for community-maintained, multiverse for non-free software).

For this guide, we’ll mirror the noble and noble-updates suites, focusing only on the main component to save space. A full mirror can consume terabytes of storage.

debmirror /storage/ubuntu \
  --nosource \
  --progress \
  --host=archive.ubuntu.com \
  --root=ubuntu \
  --method=http \
  --dist=noble,noble-updates \
  --section=main \
  --arch=amd64 \
  --ignore-release-gpg

Important Note: For production environments, it’s strongly recommended to fetch and include the vendor’s GPG key in /usr/share/keyrings instead of using --ignore-release-gpg. This verifies the authenticity of the packages.

The mirroring process can take a significant amount of time, depending on the scope of your mirror and your network speed.

Deciphering the Debian Repository File Structure

Understanding the layout of a Debian repository is key to managing it effectively. Once debmirror completes, you’ll find a specific structure within your /storage/ubuntu directory:

  • pool: This directory holds all the actual .deb package files. They can be organized alphabetically or stored together, as APT primarily uses metadata to locate them.
  • dists: This is the heart of the repository’s metadata. It contains directories for each mirrored suite (e.g., noble/, noble-updates/), and within each suite, component directories (e.g., main/). More importantly, it houses the critical repository metadata files: Packages, Release, InRelease, and Release.gpg.

The APT Repository Metadata Files

These files are what APT clients read to understand the contents of your repository:

  • Packages file: An index listing all available .deb packages within a component. It includes crucial information like package names, file paths, checksums, and dependencies. If you add or remove packages, this file must be regenerated.
  • Release file: Provides a summary of the entire repository. It contains checksums of the Packages files, defines the distributions and components present, and includes general repository metadata. Any change to the repository’s contents or structure necessitates regenerating this file.
  • InRelease and Release.gpg: These are cryptographic signatures of the Release file.
    • Release.gpg: An older, detached signature.
    • InRelease: A newer, inline signature, preferred for modern APT clients.
      These files ensure the integrity and authenticity of the repository’s metadata. When you run apt-get update, APT downloads the signed InRelease (or Release.gpg) and Packages files to determine what packages are available and where to find them.

Making Your Local Repository Accessible with Nginx

To allow client machines to pull packages from your mirror, you need to expose it via a web server. Nginx is an excellent choice for this task.

Create an Nginx configuration file for your Ubuntu mirror:

sudo vim /etc/nginx/sites-available/ubuntu-mirror

Add the following Nginx server block configuration. This sets up two locations: /ubuntu for your mirrored repository and /my-local-repo for a custom flat repository we’ll discuss later.

server {
    listen 80;
    listen [::]:80;
    server_name _;

    location /ubuntu {
        alias /storage/ubuntu;
        autoindex on;
        try_files $uri $uri/ @notfound;
    }

    location /my-local-repo {
        alias /storage/my-local-repo;
        autoindex on;
        try_files $uri $uri/ @notfound;
    }

    location @notfound {
        return 404;
    }
}

Enable the Nginx site by creating a symlink and restart the Nginx service to apply the changes:

sudo ln -s /etc/nginx/sites-available/ubuntu-mirror /etc/nginx/sites-enabled/
sudo systemctl restart nginx

Your local repository is now accessible over HTTP.

Enhancing Security: Generating and Using a GPG Key

While not strictly mandatory for a private, trusted mirror, signing your repository with your own GPG key is a best practice. It provides an additional layer of trust and allows APT clients to verify the authenticity of the packages from your mirror.

Generating a GPG Key

Use gnupg to generate a new keypair:

gpg --gen-key

Follow the prompts to create your key. Once generated, list your keys to identify the Public Key ID (PUB KEY ID), which you’ll need for signing:

gpg --list-keys

Signing Your Repository

Remember that each suite within your dists directory contains its own metadata files that need to be signed. Navigate to your repository’s root directory (/storage/ubuntu).

# Navigate to your repository root
cd /storage/ubuntu

# Sign the Release file to create InRelease (inline signature)
gpg --local-user "<PUB_KEY_ID>" --yes --clearsign -o dists/<dist_name>/InRelease dists/<dist_name>/Release

# Sign the Release file to create Release.gpg (detached signature)
gpg --local-user "<PUB_KEY_ID>" --yes --detach-sign -o dists/<dist_name>/Release.gpg dists/<dist_name>/Release

Replace <PUB_KEY_ID> with your actual GPG Public Key ID and <dist_name> with the suite names you mirrored (e.g., noble, noble-updates).

Finally, export your public key into a file and prepare it for client use:

gpg --armor --export <PUB_KEY_ID> > my_local_repo_key.asc
sudo gpg --dearmor -o /usr/share/keyrings/my_local_repo_key.gpg my_local_repo_key.asc
sudo chmod 644 /usr/share/keyrings/my_local_repo_key.gpg

Replace <PUB_KEY_ID> with your key ID and my_local_repo_key with a descriptive name. This makes your public key available for APT to trust your repository.

Client Configuration: Accessing the Local Mirror

On each client machine that needs to access your local mirror, you must configure APT to point to your new repository.

Create or edit an APT sources file (e.g., /etc/apt/sources.list.d/ubuntu.sources) on the client:

sudo vim /etc/apt/sources.list.d/ubuntu.sources

Add the following configuration, replacing <IP_or_DNS_of_mirror_server> with your server’s address and <key_name> with the name you chose for your GPG key (e.g., my_local_repo_key).

Types: deb
URIs: http://<IP_or_DNS_of_mirror_server>/ubuntu/
Suites: noble noble-updates
Components: main
Architectures: amd64
Signed-By: /usr/share/keyrings/<key_name>.gpg

Ensure the GPG public key from your mirror server is also present on the client:

# Transfer my_local_repo_key.gpg from your mirror server to the client
# For example, using scp: scp user@mirror_server:/usr/share/keyrings/my_local_repo_key.gpg /tmp/
sudo mv /tmp/my_local_repo_key.gpg /usr/share/keyrings/

Now, update APT on the client:

sudo apt-get update

APT stores the downloaded metadata in /var/lib/apt/lists. You can verify package availability using:

apt-cache search <package_name>
apt-cache show <package_name>

For newer Ubuntu/Debian versions, apt search and apt show are preferred:

apt search <package_name>
apt show <package_name>

Ensure network connectivity between the client and your mirror server.

Crafting a Custom “Flat” Repository

Sometimes, mirroring a large official repository is overkill. If you only need to store a handful of custom .deb packages (e.g., internal tools, specific vendor binaries), a “flat” repository is the perfect solution. It’s simpler, less structured, and ideal for smaller collections.

A flat repository is essentially a single directory containing .deb packages and the essential Packages and Release metadata files, all within the same directory.

Creating the Packages File for Your Flat Repository

First, create a directory for your flat repository, for example, /storage/my-local-repo. Place all your .deb packages directly into this directory.

Then, navigate into your flat repository directory and use apt-ftparchive to generate the Packages file:

sudo mkdir -p /storage/my-local-repo
# Place your .deb files in /storage/my-local-repo
cd /storage/my-local-repo
apt-ftparchive packages . | sudo tee Packages

If desired, you can also compress the Packages file:

gzip -9c Packages | sudo tee Packages.gz

For a pool-based Debian repo, the command would be slightly different:

cd <debian_repo_dir>
apt-ftparchive packages ./pool | sudo tee dists/<suite>/<component>/binary-<Arch>/Packages

Generating the Release File for Your Flat Repository

To create the Release file, it’s helpful to first define a configuration template:

cat > release.conf <<'EOF'
APT::FTPArchive::Release {
  Origin "MyCustomRepo";
  Label  "My Local Packages";
  Suite  "stable";
  Version "1.0";
  Codename "generic";
  Architectures "amd64";
  Components "main";
  Description "A collection of local .deb packages.";
}
EOF

Now, generate the Release file using apt-ftparchive and your configuration:

cd /storage/my-local-repo
apt-ftparchive -c ./release.conf release . | sudo tee Release

Signing Your Flat Repository

Just like the mirrored repository, you can sign your flat repository for added security. Ensure you’re in the flat repository’s root (/storage/my-local-repo).

gpg --local-user "<PUB_KEY_ID>" --yes --clearsign -o InRelease Release
gpg --local-user "<PUB_KEY_ID>" --yes --detach-sign -o Release.gpg Release

Remember to replace <PUB_KEY_ID> with your GPG Public Key ID.

Exposing and Configuring Clients for Your Flat Repository

You’ve already set up Nginx to expose /storage/my-local-repo at the /my-local-repo path.

On client machines, the sources.list.d entry for a flat repository differs slightly: the Components field is omitted, and Suites is set to ./ to indicate the root of the repository.

sudo vim /etc/apt/sources.list.d/flatrepo.sources

Add the following, adjusting <IP_or_DNS_of_repo> and <Key_name> as necessary:

Types: deb
URIs: http://<IP_or_DNS_of_repo>/my-local-repo
Suites: ./
Architectures: amd64
Signed-By: /usr/share/keyrings/<Key_name>.gpg

Ensure your GPG public key for this repository is placed in /usr/share/keyrings/ on the client, then update APT:

sudo apt-get update

You can now apt search and apt install packages from your custom flat repository.

Conclusion

You now possess the knowledge to establish robust local package management solutions for your Linux environments. From mirroring vast official repositories for comprehensive offline access to creating nimble flat repositories for custom package distribution, these techniques provide unparalleled control and reliability. Embracing local APT mirrors empowers you to maintain secure, consistent, and highly available systems, even when external network dependencies are not an option.

Leave a Reply

Your email address will not be published. Required fields are marked *

Fill out this field
Fill out this field
Please enter a valid email address.
You need to agree with the terms to proceed