Creating and Managing Custom Arch Linux Repositories

Custom Arch Linux repositories enable you to distribute your own packages, create offline installation media, and maintain private package collections. This guide covers everything from creating your first repository to serving it over HTTP for network installations.

Overview

A custom Arch Linux repository allows you to:

Package and distribute your own software
Create offline installation media with custom packages
Maintain private package collections for your organization
Control package versions and dependencies
Serve packages over HTTP for network installations

This process combines package management with GPG signing for security and can be integrated with custom ISO creation workflows.

Prerequisites

Before creating a custom repository, ensure you have:

A working Arch Linux system
GPG keys configured for package signing
Basic understanding of package management
Web server software (nginx) if serving over HTTP

This process combines package management with GPG signing for security and can be integrated with custom ISO creation workflows.

Creating Your First Custom Repository

Step 1: Prepare Your Package

First, you’ll need a built package file. Arch Linux packages use the .pkg.tar.zst format and contain all necessary files and metadata.

# Example package file
pkg=some-package-0.0.2-1-any.pkg.tar.zst

Step 2: Sign the Package

Package signing ensures authenticity and integrity. Use GPG to create a detached signature:

# Create a detached signature for the package
gpg --use-agent --output ~/build/"${pkg}".sig --detach-sig ~/build/"${pkg}"

Important Notes:

The --use-agent flag uses the GPG agent for password caching
The signature file will have the same name as the package with .sig extension
Ensure your GPG key is properly configured and trusted

Step 3: Create Repository Structure

Set up a directory structure for your repository:

# Create repository directory
mkdir -p ~/repo
 
# Copy package and signature to repository
cp ~/build/"${pkg}"{,.sig} ~/repo/

Step 4: Add Package to Repository Database

Create or update the repository database:

# Add package to repository and sign the database
repo-add --verify --sign ~/repo/test_repo.db.tar.gz ~/repo/"${pkg}"

Command Breakdown:

--verify: Verifies existing signatures before adding
--sign: Signs the repository database
test_repo.db.tar.gz: Repository database file
The database file will be created if it doesn’t exist

Managing Multiple Packages

Adding Multiple Packages at Once

For repositories with multiple packages, you can add them all simultaneously:

# Add all packages in the repository directory
repo-add <repo-db>.db.tar.zst <packages-location>/*.pkg.tar.zst

Batch Package Processing

For larger repositories, create a script to process multiple packages:

#!/bin/bash
REPO_DIR="$HOME/repo"
BUILD_DIR="$HOME/build"
REPO_DB="custom_repo.db.tar.gz"
 
# Sign all packages
for pkg in "$BUILD_DIR"/*.pkg.tar.zst; do
    if [ -f "$pkg" ]; then
        echo "Signing $(basename "$pkg")"
        gpg --use-agent --output "${pkg}.sig" --detach-sig "$pkg"
        
        # Copy to repository
        cp "$pkg"{,.sig} "$REPO_DIR/"
    fi
done
 
# Update repository database
repo-add --verify --sign "$REPO_DIR/$REPO_DB" "$REPO_DIR"/*.pkg.tar.zst

Configuring Pacman for Custom Repository

Adding Repository to Pacman Configuration

Edit /etc/pacman.conf to include your custom repository:

[custom-repo]
# For development/testing - skip signature verification
#SigLevel = Never
 
# For production - require signatures
SigLevel = Required TrustedOnly
Server = file:///path/to/your/repo

Configuration Options:

SigLevel = Never: Disables signature verification (development only)
SigLevel = Required TrustedOnly: Requires valid signatures from trusted keys
Server = file://: Uses local filesystem path
Server = http://: Uses HTTP server (covered in next section)

Repository Priority

Repository order in pacman.conf determines priority. Place custom repositories:

Above official repositories: For package overrides
Below official repositories: For additional packages only

Testing Your Repository

After configuration, test the repository:

# Update package database
sudo pacman -Sy
 
# List packages from your repository
pacman -Sl custom-repo
 
# Install a package from your repository
sudo pacman -S custom-package-name

For comprehensive package management operations, see the pacman commands cheatsheet.

Serving Repository Over HTTP

Setting Up Nginx

For network installations or shared repositories, serve your repository over HTTP using nginx configuration:

worker_processes  1;
 
events {
    worker_connections  1024;
}
 
http {
    include       mime.types;
    default_type  application/octet-stream;
    sendfile        on;
    keepalive_timeout  65;
 
    server {
        listen       80;
        server_name  archrepo.lab.net;
 
        location / {
            alias /srv/http/archrepo/;
            autoindex on;
            autoindex_exact_size off;
            autoindex_localtime on;
        }
    }
}

Repository Directory Structure

Organize your served repository:

/srv/http/archrepo/
├── custom_repo.db.tar.gz
├── custom_repo.db.tar.gz.sig
├── custom_repo.files.tar.gz
├── custom_repo.files.tar.gz.sig
├── package-1.0.0-1-x86_64.pkg.tar.zst
├── package-1.0.0-1-x86_64.pkg.tar.zst.sig
└── other-package-2.0.0-1-any.pkg.tar.zst
    └── other-package-2.0.0-1-any.pkg.tar.zst.sig

Pacman Configuration for HTTP Repository

Update /etc/pacman.conf to use the HTTP server:

[custom-repo]
SigLevel = Required TrustedOnly
Server = http://archrepo.lab.net/

Security Considerations

GPG Key Management

Use dedicated keys: Create separate GPG keys for package signing
Key distribution: Ensure client systems have your public key
Key revocation: Plan for key rotation and revocation procedures

Repository Security

HTTPS recommended: Use HTTPS for production repositories
Access control: Implement authentication for private repositories
Regular updates: Keep repository software updated

Package Verification

Always verify packages before adding to your repository:

# Verify package integrity
pacman -Qkk package-name
 
# Check package signatures
gpg --verify package-name.pkg.tar.zst.sig package-name.pkg.tar.zst

For comprehensive package verification procedures, see the pacman verification commands.

Automation and Maintenance

Repository Update Script

Create a maintenance script for regular updates:

#!/bin/bash
set -e
 
REPO_DIR="/srv/http/archrepo"
BUILD_DIR="/home/builder/packages"
REPO_DB="custom_repo.db.tar.gz"
 
# Function to log messages
log() {
    echo "[$(date '+%Y-%m-%d %H:%M:%S')] $1"
}
 
# Check for new packages
log "Checking for new packages..."
if [ -z "$(find "$BUILD_DIR" -name "*.pkg.tar.zst" -newer "$REPO_DIR/$REPO_DB" 2>/dev/null)" ]; then
    log "No new packages found"
    exit 0
fi
 
# Process new packages
log "Processing new packages..."
for pkg in "$BUILD_DIR"/*.pkg.tar.zst; do
    if [ -f "$pkg" ] && [ "$pkg" -nt "$REPO_DIR/$REPO_DB" ]; then
        log "Processing $(basename "$pkg")"
        
        # Sign package if signature doesn't exist
        if [ ! -f "${pkg}.sig" ]; then
            gpg --use-agent --output "${pkg}.sig" --detach-sig "$pkg"
        fi
        
        # Copy to repository
        cp "$pkg"{,.sig} "$REPO_DIR/"
    fi
done
 
# Update repository database
log "Updating repository database..."
cd "$REPO_DIR"
repo-add --verify --sign "$REPO_DB" *.pkg.tar.zst
 
# Set permissions
chown -R http:http "$REPO_DIR"
chmod -R 644 "$REPO_DIR"/*
 
log "Repository update completed"

Automated Deployment

For continuous integration, consider:

Git hooks: Trigger repository updates on code pushes
Build servers: Automated package building and signing
Mirror synchronization: Distribute repository across multiple servers

Integration with Custom ISO Creation

Custom repositories integrate well with ISO creation workflows:

Build packages: Create custom packages for your organization
Sign and add to repository: Follow the process outlined above
Include in ISO: Reference your repository in the ISO build process
Offline installation: ISO includes all necessary packages

Troubleshooting Common Issues

Signature Verification Failures

Problem: error: signature from "..." is unknown trust

Solution:

# Import your GPG public key
sudo pacman-key --recv-keys YOUR_KEY_ID
sudo pacman-key --lsign-key YOUR_KEY_ID

For detailed GPG key management procedures, see the GPG operations guide.

Repository Database Corruption

Problem: Repository database becomes corrupted

Solution:

# Remove old database files
rm repo.db* repo.files*
 
# Recreate database
repo-add --verify --sign repo.db.tar.gz *.pkg.tar.zst

Package Installation Issues

Problem: Packages fail to install from custom repository

Solution:

Check repository priority in /etc/pacman.conf
Verify package dependencies are available
Ensure signature verification is properly configured

Best Practices

Repository Organization

Consistent naming: Use clear, descriptive repository names
Version control: Track repository changes with git
Documentation: Document package purposes and dependencies
Testing: Test packages before adding to production repository

Performance Optimization

Compression: Use efficient compression for packages
Caching: Implement HTTP caching for served repositories
Bandwidth: Consider repository size for network installations
Mirrors: Use multiple mirrors for high availability

Maintenance Schedule

Regular updates: Schedule periodic repository maintenance
Security patches: Monitor for security updates
Cleanup: Remove old package versions periodically
Monitoring: Track repository usage and performance

References and Resources

Questions Answered in This Document

Q: How do I create a custom Arch Linux repository? A: Create a directory, sign your packages with GPG, copy them to the repository directory, and use repo-add to create the database file.

Q: What is the purpose of signing packages in a custom repository? A: Package signing ensures authenticity and integrity, preventing tampered or malicious packages from being installed.

Q: How do I add my custom repository to pacman? A: Edit /etc/pacman.conf to include your repository section with the appropriate SigLevel and Server settings.

Q: Can I serve my repository over HTTP? A: Yes, you can configure nginx or another web server to serve your repository directory with directory indexing enabled.

Q: How do I add multiple packages to my repository at once? A: Use the command: repo-add .db.tar.zst /*.pkg.tar.zst

Q: What’s the difference between SigLevel Never and Required TrustedOnly? A: Never disables signature verification (development only), while Required TrustedOnly requires valid signatures from trusted keys (production).

Q: How do I troubleshoot signature verification failures? A: Import your GPG public key using pacman-key —recv-keys and then sign it locally with pacman-key —lsign-key.

Q: Can I use custom repositories for offline installations? A: Yes, custom repositories work well with offline installations and can be integrated into custom ISO creation workflows.

Q: How do I maintain and update my custom repository? A: Create automation scripts to regularly process new packages, update the repository database, and maintain proper file permissions.

Q: What security considerations should I keep in mind? A: Use dedicated GPG keys, implement HTTPS for production repositories, control access to private repositories, and regularly update repository software.

Flouda Vault

Creating and Managing Custom Arch Linux Repositories

Overview

Prerequisites

Creating Your First Custom Repository

Step 1: Prepare Your Package

Step 2: Sign the Package

Step 3: Create Repository Structure

Step 4: Add Package to Repository Database

Managing Multiple Packages

Adding Multiple Packages at Once

Batch Package Processing

Configuring Pacman for Custom Repository

Adding Repository to Pacman Configuration

Repository Priority

Testing Your Repository

Serving Repository Over HTTP

Setting Up Nginx

Repository Directory Structure

Pacman Configuration for HTTP Repository

Security Considerations

GPG Key Management

Repository Security

Package Verification

Automation and Maintenance

Repository Update Script

Automated Deployment

Integration with Custom ISO Creation

Troubleshooting Common Issues

Signature Verification Failures

Repository Database Corruption

Package Installation Issues

Best Practices

Repository Organization

Performance Optimization

Maintenance Schedule

References and Resources

Questions Answered in This Document

Graph View

Table of Contents

Backlinks