Skip to content

APT Integration Guide

OrbitRepos provides a full-featured APT (Advanced Package Tool) repository manager, allowing you to host private Debian/Ubuntu packages, proxy upstream mirrors, and aggregate multiple repositories into a single source.

Overview

By using OrbitRepos for your APT packages, you can simplify Linux package management across your infrastructure. Key features include:

  • Hosted Repositories: Securely store and version your internal .deb packages.
  • Proxy Repositories: Cache packages from official Debian, Ubuntu, or third-party mirrors to reduce bandwidth and ensure availability.
  • Automatic Indexing: OrbitRepos automatically generates and signs Release and Packages metadata when artifacts are uploaded.
  • Transparent Pooling: Packages are stored in a standard pool/ structure for compatibility with all APT clients.

The APT handler is served at the /apt/{repoName}/ route.

Prerequisites

Before you begin, ensure you have the following:

  • A Debian-based Linux distribution (Debian, Ubuntu, Mint, etc.).
  • Standard tools installed: apt-transport-https, curl, and gnupg.
  • An active OrbitRepos instance. See the Quick Start for setup instructions.
  • Network access to http://localhost:8080.

Create a Repository

You can create an APT repository via the Web UI or the Management API.

  1. Log in to OrbitRepos (default: admin/admin).
  2. Navigate to Repositories > Create Repository.
  3. Select APT as the format.
  4. Choose a type: hosted, proxy, or group.
  5. Name it my-debian-repo (for this guide).
  6. Click Create.
curl -u admin:admin -X POST http://localhost:8080/api/v1/repositories \
  -H "Content-Type: application/json" \
  -d '{
    "name": "my-debian-repo",
    "format": "apt",
    "type": "hosted"
  }'

Push / Publish Artifacts

To publish artifacts to a hosted repository, use a standard curl command to upload your .deb files.

1. Upload a Package

curl -u admin:admin --upload-file my-package_1.0.0_amd64.deb \
  http://localhost:8080/apt/my-debian-repo/

2. Verify Index Generation

Upon upload, OrbitRepos triggers a background task to update the repository metadata. You can verify this by checking the Packages index: 

curl http://localhost:8080/apt/my-debian-repo/dists/stable/main/binary-amd64/Packages

Release Metadata

OrbitRepos manages the dists/ and pool/ directory structure automatically. By default, packages are assigned to the stable distribution and main component unless specified otherwise via API metadata.

Pull / Install Artifacts

To install packages, add the repository to your system's sources.list.

1. Add the Repository GPG Key

If your repository is signed (recommended), download and add the public key: 

curl -fsSL http://localhost:8080/apt/my-debian-repo/public.gpg | sudo gpg --dearmor -o /usr/share/keyrings/orbitrepos-archive-keyring.gpg

2. Configure sources.list

Create a new list file in /etc/apt/sources.list.d/: 

echo "deb [signed-by=/usr/share/keyrings/orbitrepos-archive-keyring.gpg] http://localhost:8080/apt/my-debian-repo/ stable main" | sudo tee /etc/apt/sources.list.d/orbitrepos.list

3. Update and Install

sudo apt update
sudo apt install my-package

Proxy Setup

A proxy repository allows you to cache packages from an upstream mirror locally. This is useful for mirroring official Ubuntu or Debian repositories for air-gapped or bandwidth-constrained environments.

  1. Create a new repository with type proxy.
  2. Set the Remote URL to an upstream mirror (e.g., http://archive.ubuntu.com/ubuntu/).
  3. OrbitRepos will automatically handle the mapping of requests to the upstream mirror and cache the .deb files and metadata.

Virtual Repositories

Use a group repository to combine your internal my-debian-repo (hosted) and an ubuntu-proxy (proxy). This allows your clients to use a single URL in their sources.list for both internal and external packages.

Troubleshooting

Issue Cause Resolution
401 Unauthorized Missing or incorrect credentials. Verify your username and password or API token.
GPG error: ... InRelease: The following signatures were invalid GPG key mismatch. Re-import the repository GPG key using gpg --dearmor.
Package not found Index not yet updated or wrong architecture. Check the Packages file for your specific architecture (e.g., binary-amd64).
Hash Sum mismatch Metadata out of sync during a download. Run sudo apt clean && sudo apt update on the client.
Connection Refused OrbitRepos is not reachable. Ensure the service is running and localhost:8080 is accessible.

Architecture Support

Ensure your .deb packages include the correct Architecture field in their control file. OrbitRepos uses this field to organize the Packages index under the correct binary-{arch} directory.