Skip to content

Administration Guide — APT Repo Manager

Version: 1.0 — May 2026
Audience: System administrators, security officers (CISO/RSSI), package maintainers

Table of Contents

  1. Accessing the Interface
  2. Dashboard
  3. Package Management
  4. 3.1 Listing and Searching Packages
  5. 3.2 Uploading a Package
  6. 3.3 Importing from an Upstream APT Source
  7. 3.4 Promoting Packages Between Distributions
  8. Security Monitoring — CVE and Security Review Workflow
  9. SBOM and Compliance Export
  10. User and Role Management
  11. API Tokens for CI/CD
  12. System Settings
  13. Statistics and Health Monitoring
  14. Configuring APT Clients
  15. Backup and Restore

1. Accessing the Interface

The web interface is available at the address configured during deployment:

Edition Default URL
Community http://<REPO_HOST>:3103
Enterprise http://<REPO_HOST>:3003

Navigation is handled through the left sidebar. The sections available depend on the role of the logged-in user:

Role Access
reader Dashboard, Packages (read-only), Statistics
uploader + Upload, Import
maintainer + Package deletion, CVE decisions, Audit
auditor Read-only: Audit logs, CVE review queue, Packages
admin Full access, Users, Settings, CVE decisions

Authentication can be performed via local accounts or LDAP/AD depending on the configuration (see section 8).

2. Dashboard

The dashboard is the first page displayed after login. It provides a high-level view of the repository state.

Key Indicators

  • Package count: total number of packages hosted in the repository.
  • Distributions: number of configured distributions (e.g. focal, jammy, noble, bookworm…).
  • Last sync: timestamp of the most recent synchronization with upstream APT sources.

Download Chart

The chart displays download activity over 7, 30, or 90 days (selector in the top-right corner of the chart). It allows you to quickly identify usage trends.

Recent Activity Feed

The feed lists the latest repository events: uploads, imports, security decisions, deletions, settings changes. Each entry shows the user who triggered the action and the timestamp.

3. Package Management

3.1 Listing and Searching Packages

The Packages section displays the full list of hosted packages with the following information for each:

  • Name and version
  • Architecture (amd64, arm64, all…)
  • Target distribution
  • CVE status (no vulnerability / pending review / confirmed vulnerability)

Filtering packages

Use the search bar to filter by name. The distribution selector restricts the view to a specific distribution.

Package detail view

Click on a package to access:

  • History: all imported or uploaded versions with their status.
  • CVE details: list of detected CVEs, CVSS score, EPSS score, CISA KEV indicator.
  • SBOM export: generate the package SBOM in CycloneDX or SPDX format.

Deleting a package

Available to maintainer role and above. Deletion is permanent and recorded in the audit trail. A confirmation dialog is shown before execution.

3.2 Uploading a Package

Navigate to the Upload section via the sidebar.

Steps

  1. Drag and drop the .deb file into the upload zone (or click to browse for a file).
  2. Select the target distribution from the dropdown menu.
  3. Click Submit.

Real-time validation pipeline

Once received, the file goes through the following stages (displayed live):

Stage Description
Format Structural validation of the .deb package
SHA256 File checksum and provenance verification
Antivirus Malware scan against known signature database
CVE analysis Known vulnerability analysis with EPSS/KEV enrichment
GPG Cryptographic signature verification
Dependencies Dependency resolution within the repository

Possible statuses after validation

  • Accepted: the package is published to the APT repository and immediately available.
  • Pending review (pending_review): one or more CVEs were detected. The package is placed in quarantine and a notification is sent to the security officer.
  • Rejected: the package is refused (virus detected, invalid signature, incorrect format). It is quarantined and will not be published.

3.3 Importing from an Upstream APT Source

The Import section allows you to import packages directly from synchronized Ubuntu or Debian sources.

Procedure

  1. Type the package name in the search bar. The synchronized APT index is queried in real time.
  2. Select the package and desired version from the results.
  3. Click Resolve dependencies to visualize the complete dependency tree.
  4. Click Import to launch the validation pipeline.

Batch import

To import multiple packages at once, check each package in the results list, then click Import selection. The pipeline runs sequentially for each package.

Note: available APT sources depend on the configuration (Settings > APT Sources). Only enabled sources are queried.

3.4 Promoting Packages Between Distributions

The Distributions section lists configured distributions along with the package count hosted in each.

Promoting a package

  1. Select the source distribution.
  2. Locate the package to promote in the list.
  3. Click Promote and select the target distribution.
  4. Confirm the operation.

The promotion is recorded in the audit trail. The promoted package goes through the same validation pipeline as a direct upload.

Migrating packages

The Migrate option allows you to move a set of packages from one distribution to another in a single operation.

4. Security Monitoring — CVE and Security Review Workflow

CVE Review Queue

The Security section is accessible to maintainer, auditor, and admin roles. It centralizes vulnerability management.

Review Queue

Lists all packages with pending_review status, i.e. awaiting a security officer decision. For each package:

  • Name, version, distribution
  • Detected CVE(s) with CVSS score
  • EPSS score (exploitation probability)
  • CISA KEV indicator (Known Exploited Vulnerability)
  • Remaining SLA (decision deadline configured per severity)

Vulnerability dashboard

Summary view classifying all known vulnerabilities in the repository by severity:

Severity Color
Critical Red
High Orange
Medium Yellow
Low Blue

Security Decision Workflow

  1. An uploaded or imported package triggers CVE analysis.
  2. If a vulnerability is detected according to the configured policy (Settings > CVE Policy), the package moves to pending_review status.
  3. A notification is sent via webhook (Slack/Teams/Mattermost) and/or email.
  4. The security officer (maintainer or admin) goes to Security > Review Queue.
  5. They review the details of each CVE, EPSS scores, and KEV indicators.
  6. They make a decision with a mandatory justification:
  7. Approve (accept_risk / exception): the package is published to the APT repository.
  8. Reject: the package is moved to quarantine and will not be published.
  9. The decision, justification, and timestamp are recorded as a SECURITY_DECISION entry in the audit trail.

Antivirus Status

The antivirus status is displayed in the Security section (signature version, last update date). An Update signatures button triggers an immediate manual update (admin only).

5. SBOM and Compliance Export

Enterprise Edition only

SBOM export requires the Enterprise Edition. Community Edition endpoints return HTTP 402.

The SBOM (Software Bill of Materials) section allows you to generate and export a comprehensive list of software components present in the repository.

Export Parameters

Parameter Options
Format CycloneDX JSON (OWASP) or SPDX JSON (ISO/IEC 5962)
Distribution All or a specific distribution

Interface

  • Package count: number of packages included in the selected SBOM.
  • Preview: display of the first 5 components for verification before export.
  • Full export: download the complete SBOM file (requires valid authentication).

Per-package SBOM Export

From a package detail view (in the Packages section), it is possible to export the SBOM individually for that package only, in the desired format.

Regulatory Use

Exported SBOM files comply with NIS2 requirements and CISA guidelines for software component traceability. Archive them together with audit logs for compliance purposes.

6. User and Role Management

The Users section is restricted to administrators (admin).

User List

Displays all accounts with: username, role, last login date, status (active/inactive).

Creating a User

  1. Click New user.
  2. Fill in the fields: username, password, role, full name, email address.
  3. Validate.

The account is immediately active.

Editing a User

  • Role: modifiable via the dropdown menu in the list.
  • Activate / Deactivate: the toggle takes effect immediately. A deactivated user can no longer log in.
  • Reset password: generates a new temporary password displayed only once.
  • Delete: permanent deletion after confirmation.

Available Roles

Role Description
reader Read-only access to packages and dashboard
uploader Upload and import packages
maintainer + Deletion, CVE decisions, audit access
auditor Read-only: audit logs, CVE queue — no write access
admin Full access including user management and settings

LDAP/AD Authentication

If LDAP is configured (Settings > LDAP/AD), users can log in with their directory credentials. LDAP groups can be mapped to application roles. Auto-provisioning automatically creates a local account on first login.

7. API Tokens for CI/CD

API tokens allow external systems (CI/CD pipelines, scripts) to interact with the repository without using an interactive session.

Creating a Token

  1. Go to Settings > API Tokens (or from the user profile page).
  2. Click Create token.
  3. Fill in:
  4. Name: descriptive identifier (e.g. gitlab-ci-prod).
  5. Role: the uploader role is recommended for publishing pipelines.
  6. Expiry: optional (leave empty for a permanent token).
  7. Click Generate.
  8. Copy the token immediately — it will not be displayed again after closing the dialog.

Using a Token

Add the following HTTP header to each API request:

Authorization: Bearer repod_xxxxxxxxxxxxx

Example with curl (replace 8100 with 8000 for Enterprise):

curl -H "Authorization: Bearer repod_xxxxxxxxxxxxx" \
     http://REPO_HOST:8100/packages/

Example in a GitLab CI pipeline:

upload:
  script:
    - |
      curl -s -X POST \
        -H "Authorization: Bearer $REPOD_TOKEN" \
        -F "file=@mypackage_1.0_amd64.deb" \
        -F "distribution=jammy" \
        http://REPO_HOST:8100/upload/

Store the token in the secret variables of your CI/CD tool — never hardcode it in source files.

Revoking a Token

From Settings > API Tokens, click Revoke next to the token to remove. Revocation is immediate.

8. System Settings

The Settings section is restricted to administrators. It groups all global application configuration options.

General

  • Application URL: public URL used in notifications and generated links.
  • Sync schedule: hour and minute of the daily synchronization with upstream APT sources.
  • Enable / Disable automatic synchronization.

APT Sources

List of available Ubuntu and Debian sources. Enable or disable each source individually according to the distributions to synchronize.

Typical available sources:

  • Ubuntu: focal (20.04), jammy (22.04), noble (24.04)
  • Debian: buster (10), bullseye (11), bookworm (12)

Notifications

  • Webhook URL: Slack, Microsoft Teams, or Mattermost endpoint for automatic alerts (new packages pending review, RSSI decisions, system errors).
  • Test button: sends a test message to the configured webhook.

Email SMTP

Configure email sending for notifications and alerts:

Field Description
SMTP host Mail server address
Port Typically 587 (STARTTLS) or 465 (TLS)
Username / Password Credentials of the sending account
From address Address displayed in outgoing emails
To address(es) Alert recipient address(es)
TLS Enable/disable encryption

The Test button sends a test email to the configured recipients.

GPG

  • Key fingerprint: fingerprint of the GPG key used to sign packages.
  • Public key: display and copy of the public key (to distribute to APT clients).
  • Generate new key: creates a new GPG key pair. Note: APT clients will need to update their keyring.

LDAP/AD

Configuration of the enterprise directory for centralized authentication:

Field Description
Host LDAP/AD server address
Port 389 (LDAP), 636 (LDAPS)
SSL / STARTTLS Encryption mode
TLS certificate validation Enable in production
Bind DN Service account for LDAP queries
Bind password Service account password
Base DN Search root in the directory
User filter LDAP filter (e.g. (objectClass=person))
Attribute mapping LDAP attribute → application field mapping
Group-to-role mapping Map LDAP group to an application role (5 roles)
Auto-provisioning Automatically create an account on first login

The Test button verifies connectivity and authentication with the current settings.

Retention

  • Audit log retention: number of days before automatic purge of audit entries.
  • Import cleanup: number of days before temporary import files are cleaned up.

CVE Policy

Defines the validation pipeline behavior when vulnerabilities are found:

Severity Available actions
Critical block (automatic rejection) / review (RSSI queue) / warn / allow
High same
Medium same
Low same

Other parameters:

  • SLA (days): maximum decision delay per severity, tracked in the review queue.
  • Auto-enrich CVEs (auto_enrich): automatically fetch EPSS exploitation probability scores and CISA KEV indicators inline during CVE analysis.

Validation

  • Enable antivirus scan (clamav_scan): enable/disable antivirus scanning in the pipeline.
  • Enable CVE analysis (grype_scan): enable/disable CVE analysis in the pipeline.
  • Max upload size: file size limit in MB for uploaded .deb files.

9. Statistics and Health Monitoring

Statistics (Downloads)

The Statistics section provides a detailed view of repository usage.

Global metrics

  • Total download count
  • Number of unique packages downloaded
  • Number of unique clients (IP addresses)
  • Total volume served (GB/MB)

Daily chart

Bar chart of downloads over 7, 30, or 90 days.

Top downloaded packages

Table of the most popular packages with a relative popularity bar.

50 most recent downloads

Detailed list including: client IP address, user-agent, package name, size, timestamp.

Health (Supervision)

The Health section provides a real-time view of the system's operational state. It refreshes automatically every 30 seconds.

Checks performed

Check Description
Volume Manifests Disk space used by APT manifests
Volume Pool Disk space used by .deb files
Volume Audit Disk space used by audit logs
ClamAV Antivirus signature version
Packages Counts per distribution and status
Scheduler Next scheduled task runs

Disk usage indicators

  • Green: < 75% used
  • Orange: between 75% and 90%
  • Red: > 90% (action required)

Plan storage expansion as soon as an indicator turns orange.

Audit Log

The Audit section displays a chronological log of all actions performed in the application.

Available filters

  • By action type (upload, import, deletion, security decision, settings change…)
  • By user
  • By package

Export

The audit log can be exported in JSONL format for archival or integration into a SIEM system.

10. Configuring APT Clients

For a client machine to use the APT repository, it must be configured to trust it and know its address.

Manual Method

Replace APT_PORT with your edition's APT port (8180 for Community, 80 for Enterprise).

1. Import the public GPG key

curl -sL http://REPO_HOST:APT_PORT/repos/dists/jammy/Release.gpg \
  | gpg --dearmor \
  > /etc/apt/trusted.gpg.d/repod.gpg

2. Declare the repository

echo "deb http://REPO_HOST:APT_PORT/repos jammy main" \
  > /etc/apt/sources.list.d/repod.list

Replace jammy with the name of the target distribution (focal, noble, bookworm, etc.).

3. Update the APT cache

apt update

4. Install a package

apt install package-name

GPG Key

The GPG public key is accessible from Settings > GPG. It must be redistributed to clients whenever a new key is generated.

11. Backup and Restore

Backup Script

A backup.sh script is provided at the project root. It backs up critical data: package pool, manifests, database, audit logs.

Manual backup (default directory)

./backup.sh

Backup to a NAS or external storage

BACKUP_DIR=/mnt/nas ./backup.sh

Dry run (preview only)

./backup.sh --dry-run

Displays the files that would be backed up without performing any operation.

Scheduling

It is recommended to schedule the backup daily via cron:

# Daily backup at 02:00
0 2 * * * /opt/repod/backup.sh >> /var/log/repod-backup.log 2>&1

Restore Procedure

To restore from a backup, stop the service, replace the Docker volumes with backed-up data, then restart:

docker compose down
# Restore data into the corresponding Docker volumes
docker compose up -d

Refer to the project README for details on Docker volumes and their mapping to backup paths.

Data Covered by Backups

Data Importance
Package pool (.deb files) Critical
APT manifests Critical
Application database Critical
Audit logs (.jsonl) High
GPG configuration High
Application settings Medium

Recommendations

  • Test the restore procedure regularly in a test environment.
  • Retain a minimum of 30 days of backups.
  • Store backups off the server hosting the repository (NAS, S3-compatible object storage).
  • Encrypt backup archives containing proprietary packages.

Guide generated for APT Repo Manager — May 2026