custom_apt_repo

Synced from the repo

This page is generated from ansible/playbooks/roles/custom_apt_repo/README.md. Edit it there — changes here are overwritten on the next build.

Configure custom APT repositories on Ubuntu/Debian systems with GPG key authentication.

Description

This role:

1. Installs GPG signing key to system trusted keyring
2. Adds custom APT repository to sources list
3. Updates APT cache
4. Verifies repository accessibility

Requirements

• Ubuntu/Debian-based system
• GPG signing key for the repository (included in role files/)
• Repository must be accessible from target hosts

Role Variables

Required Variables

None - all variables have sensible defaults for the Toolsera Nexus repository.

Optional Variables

• apt_repo_url: Base URL of the APT repository (default: https://nexus.toolsera.lan/repository/toolsera/)
• apt_repo_distribution: Distribution/suite name (default: stable)
• apt_repo_components: Space-separated component names (default: main)
• apt_repo_key_source: Key source type - 'file' or 'url' (default: 'file')
• apt_repo_key_file: GPG key filename in role files/ - used when source is 'file' (default: public.gpg.key)
• apt_repo_key_url: GPG key URL - used when source is 'url' (default: '')
• apt_repo_key_dest: Destination path for GPG key (default: /etc/apt/trusted.gpg.d/toolsera-repo.asc)
• apt_repo_sources_file: APT sources list filename (default: /etc/apt/sources.list.d/toolsera.list)
• apt_repo_options: Additional repository options (default: '')

See defaults/main.yml for all available variables.

Dependencies

None.

Example Playbook

Default Configuration (Toolsera Nexus)

---
- hosts: all
  roles:
    - custom_apt_repo

This configures:

deb https://nexus.toolsera.lan/repository/toolsera/ stable main

Custom Repository with File-Based Key

---
- hosts: all
  roles:
    - role: custom_apt_repo
      apt_repo_url: 'https://repo.example.com/ubuntu/'
      apt_repo_distribution: 'focal'
      apt_repo_components: 'main contrib'
      apt_repo_key_source: 'file'
      apt_repo_key_file: 'my-custom-key.gpg'

Repository with URL-Based Key

---
- hosts: all
  roles:
    - role: custom_apt_repo
      apt_repo_url: 'https://packages.example.com/debian'
      apt_repo_distribution: 'stable'
      apt_repo_components: 'main'
      apt_repo_key_source: 'url'
      apt_repo_key_url: 'https://packages.example.com/keys/repo-key.gpg'
      apt_repo_sources_file: '/etc/apt/sources.list.d/example.list'

Multiple Repositories

---
- hosts: all
  roles:
    # Toolsera Nexus - file-based key
    - role: custom_apt_repo
      apt_repo_url: 'https://nexus.toolsera.lan/repository/toolsera/'
      apt_repo_distribution: 'stable'
      apt_repo_key_source: 'file'
      apt_repo_key_file: 'public.gpg.key'
      apt_repo_sources_file: '/etc/apt/sources.list.d/toolsera.list'

    # Smallstep - URL-based key
    - role: custom_apt_repo
      apt_repo_url: 'https://packages.smallstep.com/stable/debian'
      apt_repo_distribution: 'debs'
      apt_repo_key_source: 'url'
      apt_repo_key_url: 'https://packages.smallstep.com/keys/apt/repo-signing-key.gpg'
      apt_repo_key_dest: '/etc/apt/trusted.gpg.d/smallstep.asc'
      apt_repo_sources_file: '/etc/apt/sources.list.d/smallstep.list'

With Architecture Restrictions

---
- hosts: all
  roles:
    - role: custom_apt_repo
      apt_repo_options: 'arch=amd64,arm64'

This generates:

deb [arch=amd64,arm64] https://nexus.toolsera.lan/repository/toolsera/ stable main

Post-Installation

After the role completes, you can:

# Verify repository is configured
cat /etc/apt/sources.list.d/toolsera.list

# Check GPG key is installed
ls -la /etc/apt/trusted.gpg.d/toolsera-repo.asc

# Search for packages from the repository
apt-cache search <package-name>

# Install packages from the repository
apt install <package-name>

# View repository in apt-cache policy
apt-cache policy

Tags

The role supports the following tags:

• apt-key / gpg - Only install GPG key
• apt-repo / repository - Only configure repository

Usage:

# Install GPG key only
ansible-playbook site.yml --tags apt-key

# Configure repository only (assumes key is already installed)
ansible-playbook site.yml --tags apt-repo

Updating the GPG Key

To update the GPG key:

1. Replace roles/custom_apt_repo/files/public.gpg.key with the new key
2. Re-run the playbook

The role is idempotent and will update the key if the file changes.

Troubleshooting

Repository not found after configuration:

• Check URL is accessible: curl -I https://nexus.toolsera.lan/repository/toolsera/
• Verify DNS resolution: ping nexus.toolsera.lan
• Check firewall allows HTTPS (port 443)

GPG signature verification failed:

• Ensure public.gpg.key matches the key used to sign repository packages
• Verify key format: gpg --list-packets files/public.gpg.key
• Check key was copied correctly: ls -la /etc/apt/trusted.gpg.d/toolsera-repo.asc

Package installation fails:

• Update APT cache: apt update
• Check repository is in sources: apt-cache policy
• Verify package exists: apt-cache search <package-name>

License

MIT

Author Information

Created for ubuntu-server-config repository.