Guide to setting up apt package repository on Debian and Ubuntu servers

Why should I set up an enterprise APT repository?

In this practical and expert guide, we explain step by step how to set up and manage an APT repository on a Debian/Ubuntu server. It is suitable for developers, system administrators, DevOps teams, and companies that need to distribute internal packages (.deb) or publish custom packages.

Advantages: Internal distribution of packages without manual uploads, version control and dependencies, integration with CI/CD (e.g. GitLab CI), and the ability to use CDN and edge locations for rapid distribution.

Why is it important to build an APT repository?

An APT repository allows you to centrally publish packages, control dependencies, and automate release releases. For organizations with global users, using a CDN or content delivery network reduces latency and load on the origin.

For public repositories, use Anti-DDoS and CDN services to stay resilient against attacks and high traffic.

Quick comparison of methods

dpkg-scanpackages: Suitable for simple, fast, and small environments. Simple configuration but limited management.

reprepro: Suitable for organizations; multi-distribution management, mirror and import/export support.

aptly: Modern and powerful; snapshot, publish to S3, version management and flexible publishing.

Prerequisites

Requirements for setup:

• Debian/Ubuntu server with access root Or sudo
• Web server to serve (Nginx/Apache) or use S3/CDN
• GPG for Release signing
• Install the required tools (e.g. reprepro or aptly)

Example of installing basic packages:

sudo apt update && sudo apt install nginx gnupg2 apt-utils dpkg-dev
# برای reprepro یا aptly:
sudo apt install reprepro
# یا برای aptly (ممکن است پکیج در مخازن رسمی نباشد و نیاز به نصب از بسته‌های پروژه باشد)

Basic structure of the APT tank

The general structure of an APT repository should include the following branches:

• dists/ / /binary- /Packages(.gz)
• pool/ /package.deb
• dists/ /Release and Release.gpg (signature)

Example file structure:

/var/www/html/apt-repo/
├── dists/
│   └── focal/
│       └── main/
│           └── binary-amd64/
│               └── Packages.gz
└── pool/
    └── main/
        └── your-package_1.0.0_amd64.deb

Simple method: dpkg-scanpackages

Suitable for small and private tanks. General steps:

1. Creating a directory and setting the owner:

sudo mkdir -p /var/www/html/apt-repo/{dists/focal/main/binary-amd64,pool/main}
sudo chown -R $USER:$USER /var/www/html/apt-repo

Copy package to pool:

cp mypackage_1.0.0_amd64.deb /var/www/html/apt-repo/pool/main/

Creating Packages file and compressing it:

cd /var/www/html/apt-repo
dpkg-scanpackages pool /dev/null | gzip -9c > dists/focal/main/binary-amd64/Packages.gz

Manually creating the Release file:

cat > dists/focal/Release <<EOF
Origin: MyRepo
Label: MyRepo
Suite: stable
Codename: focal
Architectures: amd64
Components: main
Description: Internal APT repository
EOF

Signing Release with GPG (recommended):

gpg --default-key "[email protected]" --output dists/focal/Release.gpg --detach-sign --armor dists/focal/Release

Example of adding a repository in the client using signed-by:

echo "deb [signed-by=/usr/share/keyrings/myrepo.gpg] https://repo.example.com/apt-repo focal main" | sudo tee /etc/apt/sources.list.d/myrepo.list
sudo apt update

Standard and professional method: reprepro

Reprepro is suitable for managing multiple distributions and components and integrates well with organizational processes.

Installation:

sudo apt install reprepro

Creating structure and folders:

sudo mkdir -p /var/www/html/repo
cd /var/www/html/repo
sudo mkdir conf db dists pool

Example conf/distributions file:

Origin: MyCompany
Label: MyCompany
Suite: stable
Codename: focal
Architectures: amd64 source
Components: main
Description: MyCompany internal repository
SignWith: <KEYID>

Add the package to the repo:

sudo reprepro -b /var/www/html/repo includedeb focal /path/to/mypackage_1.0.0_amd64.deb

reprepro automatically generates Packages and Release files and signs them if SignWith is set.

Example of a simple Nginx configuration with SSL to serve a repository:

server {
    listen 443 ssl;
    server_name repo.example.com;

    ssl_certificate /etc/ssl/certs/fullchain.pem;
    ssl_certificate_key /etc/ssl/private/privkey.pem;

    root /var/www/html/repo;
    location / {
        autoindex on;
    }
}

Modern method: aptly (suggested for production)

aptly has snapshot, publish to S3, mirror, and advanced management features and is recommended for production and enterprise environments.

Simple installation and use:

sudo apt install aptly

aptly repo create -distribution=focal -component=main myrepo
aptly repo add myrepo /path/to/*.deb
aptly publish repo -architectures=amd64 myrepo

To publish to S3/CDN, you can use various aptly backends and put the output in an S3 bucket and use CDN/edge locations for distribution.

Security tips and best practices

HTTPS: Always publish the repository with TLS to prevent MiTM attacks.

Extracting the public key and distributing it:

gpg --export --armor "[email protected]" | sudo tee /usr/share/keyrings/myrepo-archive-keyring.gpg

On the client:

deb [signed-by=/usr/share/keyrings/myrepo-archive-keyring.gpg] https://repo.example.com/ubuntu focal main

Limited access: For private repositories, use Basic Auth, client-cert, or IP whitelisting (e.g. in Nginx).

Logging and monitoring: Record and monitor download volume, errors, and failed attempts.

Client configuration (practical example)

Place the key file and add the repository on the client machine:

sudo mkdir -p /usr/share/keyrings
curl -fsSL https://repo.example.com/keys/myrepo.gpg | sudo tee /usr/share/keyrings/myrepo-archive-keyring.gpg

echo "deb [signed-by=/usr/share/keyrings/myrepo-archive-keyring.gpg] https://repo.example.com/apt-repo focal main" | sudo tee /etc/apt/sources.list.d/myrepo.list
sudo apt update
sudo apt install mypackage

Automation and CI/CD

You can have a job in GitLab CI to build the .deb and push it to the repo, and then publish the package with reprepro or aptly.

build-package:
  script:
    - dpkg-buildpackage -us -uc
    - scp ../mypackage_*.deb deploy@repo-server:/tmp
    - ssh deploy@repo-server "reprepro -b /var/www/html/repo includedeb focal /tmp/mypackage_*.deb"

For aptly, you can use the API or CLI for automatic publishing.

Performance and scalability optimization

Key tips for better performance:

• CDN and edge locations: Distributing content to the closest edge reduces latency and pressure on the origin. Our company enables this with over 85 global locations and BGP and CDN options.
• Compression and caching: Gzip the Packages.gz files and set the appropriate Cache-Control headers.
• Load balancing and HA: Use load balancers and multi-region replicas for higher stability.

Example of Cache-Control header in Nginx:

location /apt-repo/ {
    add_header Cache-Control "public, max-age=3600";
}

Specific tips for specific cases

For organizations that need to distribute to trading servers (trading VPS) or gaming servers, it is recommended to use locations close to the destination data centers to minimize latency.

If you have large packages like AI models or render files, use GPU Cloud and compute servers with high-speed network and CDN.

For scalable global publishing, using S3 and a CDN at the edge provides the best performance.

Summary and Startup Checklist

• Tool selection: dpkg-scanpackages (simple) / reprepro (enterprise) / aptly (advanced)
• Preparing the directory structure (dists, pool)
• Package and Release Generation
• Signing with GPG and distributing the public key (with the signed-by method)
• Serving over HTTPS with Nginx/Apache or S3+CDN
• Applying access restrictions and monitoring
• Automation with CI/CD for automated releases

Recommended hosting services

Our company can provide the complete infrastructure for running an APT repository, including hosting on a high-performance cloud server and BGP network, global distribution with CDN and 85+ locations, private and secure options (dedicated server, Anti-DDoS, TLS and authentication), and support for S3-compatible storage and integration with aptly.

The technical team can help with location selection, CDN setup, Nginx configuration, and CI/CD implementation.

Frequently Asked Questions