Install Pulp with a container (podman, CLI, UI)

This guide deploys a working Pulp instance in a single container, configures the pulp CLI, opens the web interface, then exposes everything properly over HTTPS behind Traefik. Intended audience: administrators comfortable with podman or docker. Prerequisites: a Linux machine with podman (or Docker) and access to /dev/fuse. At the end you will have an artifact repository ready to receive your packages, local for testing, over HTTPS for production.

The official pulp/pulp image runs all of Pulp's services in a single container: the API, the content application, the workers, plus PostgreSQL, Redis and nginx. It is the recommended method for a small installation that does not need to scale across several machines.

What you will learn

• Run Pulp in a single container with podman.
• Set the administrator password and the CONTENT_ORIGIN setting.
• Install and configure the pulp CLI.
• Open the web interface served by the image.
• Expose the instance over HTTPS behind Traefik.

Prerequisites

• podman 4+ (or Docker) and the /dev/fuse device available (required by the container plugin).
• A free HTTP port on the host (here 8080).
• About 2 GB of RAM free for PostgreSQL, Redis and the workers.

Run Pulp in a single container

Pulp needs persistent directories for the database, the artifact storage and its configuration. You create them next to the container before starting.

1. Prepare the directory tree and a minimal settings file:

   mkdir -p pulp/{settings,pulp_storage,pgsql,containers}
   cd pulp
   echo 'CONTENT_ORIGIN="http://localhost:8080"' > settings/settings.py

   The CONTENT_ORIGIN parameter is critical: it is the public URL at which your clients reach Pulp. All published metadata (PyPI index, container registry realm) uses it to build its links. If it does not match the port actually exposed, pip install and podman pull fail with broken links.

2. Start the container:

   podman run --detach --publish 8080:80 --name pulp \
     --volume "$(pwd)/settings":/etc/pulp \
     --volume "$(pwd)/pulp_storage":/var/lib/pulp \
     --volume "$(pwd)/pgsql":/var/lib/pgsql \
     --volume "$(pwd)/containers":/var/lib/containers \
     --device /dev/fuse \
     docker.io/pulp/pulp:3.114@sha256:a9e03d2bf3f40fea366f9f795a146ef91cabf6ea3d7b7ed8bc4b882f4353060c

   The image is pulled by version tag and by digest, not by latest. The tag tells the reader the version; the @sha256: pins byte for byte what is actually pulled, because a tag can be moved to other content without its name changing. Digest retrieved on 2026-10-21.

3. Wait for initialisation (database migrations, ~1 minute), then check the API:

   curl -s http://localhost:8080/pulp/api/v3/status/ | head

   The command must return a JSON listing the installed components (core, file, python, container...). As long as you get a connection error, the container is still starting: it is not a failure.

SELinux enabled?

On a machine with SELinux in enforcing mode (Fedora, RHEL, Rocky), add the :Z suffix to each volume (--volume "$(pwd)/settings":/etc/pulp:Z) so the container can write to the mounted directories.

Set the administrator password

The image sets no default password. You define it with the pulpcore-manager tool, run inside the container.

podman exec pulp bash -c 'pulpcore-manager reset-admin-password --password "VotreMotDePasseFort"'

The output confirms Successfully set password for "admin" user. This admin account is the one you will use in the CLI and the web interface.

Install and configure the CLI

The pulp CLI is the most direct way to drive the instance. You install it in an isolated Python environment, so as not to pollute the system.

With uv

uv tool install "pulp-cli[pygments]"

With pipx

pipx install "pulp-cli[pygments]"

You then record the instance's coordinates:

pulp config create \
  --username admin \
  --base-url http://localhost:8080 \
  --password "VotreMotDePasseFort"

Check that the CLI talks to the server:

pulp status

The output shows the core version (3.114.0) and the list of active plugins. You now drive Pulp without touching curl.

Keep the password out of your history

To avoid the password lingering in the shell history, omit --password: the CLI then asks for it interactively, and stores it in ~/.config/pulp/cli.toml with restricted permissions.

Open the web interface

The image serves a graphical interface, Pulp UI, under the /ui/ path. Open in a browser:

http://localhost:8080/ui/

Log in with the admin account and the password set above. Authentication goes through a session (sessionid and csrftoken cookies), like any ordinary web application.

A still-young interface

Pulp UI (a separate project under the Apache-2.0 licence) lets you browse repositories, remotes, distributions, tasks, users and roles. It is handy for visualising the state of the instance, but does not yet cover every operation: some actions (such as the container pull-through cache) can only be created through the API or the CLI. For day-to-day work with Pulp, the pulp CLI remains the reference.

Expose Pulp over HTTPS behind Traefik

The installation above, on localhost:8080, is only a local bootstrap to check that the instance starts. You never publish Pulp over HTTP for real clients: you place a reverse proxy that terminates TLS and forwards the traffic to the container. Traefik is a good fit thanks to its label-based configuration. On an isolated network, with no public authority, the same exposure works with a self-signed authority that you trust on the clients (see Pulp air-gapped).

Two rules govern correct operation behind a proxy:

• CONTENT_ORIGIN must be the public HTTPS URL (for example https://pulp.exemple.com). It feeds the links in the indexes and the container registry realm.
• The proxy must forward the Host header and set X-Forwarded-Proto: https, which Traefik does automatically. Without it, Pulp generates http:// URLs and clients refuse the redirects.

1. Adjust the settings for the public URL, in settings/settings.py:

   CONTENT_ORIGIN = "https://pulp.exemple.com"
   TOKEN_SERVER = "https://pulp.exemple.com/token/"
   TOKEN_SIGNATURE_ALGORITHM = "ES256"
   PUBLIC_KEY_PATH = "/etc/pulp/certs/token_public_key.pem"
   PRIVATE_KEY_PATH = "/etc/pulp/certs/token_private_key.pem"

   The last four lines enable token authentication for the container registry; without a key pair consistent with the public URL, podman pull returns a 500 error that says nothing about its cause.

2. Add the Traefik labels to the Pulp service. If you already have a Traefik listening on an HTTPS entrypoint (websecure) with a certificate resolver (le), four labels on the Pulp container are enough, nothing else to declare:

   services:
     pulp:
       image: docker.io/pulp/pulp:3.114@sha256:a9e03d2bf3f40fea366f9f795a146ef91cabf6ea3d7b7ed8bc4b882f4353060c
       devices:
         - "/dev/fuse"
       volumes:
         - "./settings:/etc/pulp"
         - "./pulp_storage:/var/lib/pulp"
         - "./pgsql:/var/lib/pgsql"
         - "./containers:/var/lib/containers"
       labels:
         - "traefik.enable=true"
         - "traefik.http.routers.pulp.rule=Host(`pulp.exemple.com`)"
         - "traefik.http.routers.pulp.tls.certresolver=le"
         - "traefik.http.services.pulp.loadbalancer.server.port=80"

   A single routing rule is enough: it covers the API (/pulp/api/), the content (/pulp/content/), the registry (/v2/, /token/) and the interface (/ui/), all served by the same port 80 of the container. The certresolver terminates TLS and Traefik adds the Host and X-Forwarded-Proto headers on its own.

3. Start and verify:

   podman-compose up -d   # or `docker compose up -d` depending on your engine
   curl -s https://pulp.exemple.com/pulp/api/v3/status/ | head

   The CLI and the clients now point to https://pulp.exemple.com, and podman login pulp.exemple.com works without --tls-verify=false.

Air-gapped: a self-signed certificate instead of ACME

The le resolver above relies on Let's Encrypt, which requires Internet access and a public domain: unusable on an isolated network. Offline, you give Traefik a self-signed certificate instead of a certresolver. You declare it in a dynamic configuration file loaded by the file provider:

# certs.yaml (mounted and referenced via --providers.file.filename)
tls:
  certificates:
    - certFile: /certs/pulp.crt
      keyFile: /certs/pulp.key

The router label then simply becomes traefik.http.routers.pulp.tls=true (without certresolver). Generating the pulp.crt / pulp.key pair and, above all, trusting the authority on the clients are detailed in Pulp air-gapped, the logical next step of this guide.

Large uploads

Unlike nginx, which caps request bodies at 1 MB by default, Traefik imposes no size limit. You can push large artifacts (container images, RPMs) with no extra tuning. Watch the disk space of the pulp_storage volume instead.

And the container's internal nginx?

The all-in-one pulp/pulp image bundles its own nginx, which routes requests to the API and the content application. In the setup above, Traefik does not replace it: it sits in front, terminates TLS, and forwards to port 80 of the container, where the internal nginx takes over. This double proxy is normal and fully supported.

If you want to make Traefik the only web layer (no internal nginx), you have to move from the single container to the multi-container deployment: the pulp-minimal image provides pulp-api (port 24817) and pulp-content (port 24816) separately, and the pulp-web image is just the nginx. You then drop pulp-web and replicate its routing in Traefik:

Path	Target service
/pulp/content/	pulp-content:24816
/v2/ (OCI registry)	pulp-content:24816
/pulp/api/v3/, /auth/, /token/, /	pulp-api:24817

Swipe to see more

It is more flexible but more delicate: the slightest forgotten route (the container registry's /token/, for example) breaks a feature. For most installations, keeping the internal nginx and putting Traefik in front remains the safest choice.

Hands-on practice

The lab gives you depot.lab, a Debian 13 machine without Pulp. You install the instance there as a rootless container, set its configuration, and leave it running. The validation does not check that a container exists: it queries the status API, checks that the workers are seen as online, that the storage is reachable, and that a client on another machine reaches the repository. A final check reboots the host: a rootless instance without enable-linger does not come back, and the lab detects it.

Guided lab Practice

Learn how to do it

Put Pulp into service, and prove the API answers

$ dsoxlab run pulp-01-installer

Environment: VM·Duration: ~35 min

How it is checked: the state of the system is checked after a reboot, not the command you typed.

First time? What DSOXLab is and how to install it

DSOXLab is the command line that prepares a disposable environment (an isolated shell or a VM), runs the lab scenario, then checks the real state of the system and computes a score. Nothing is installed or broken on your workstation.

It needs Python 3.11 or later, uv or pipx, and git. The installation guide details these prerequisites; on Windows, or on a Mac without Python, use the appliance instead.

This lab starts virtual machines: it also needs ansible-playbook, a hypervisor (KVM or Incus), Terraform and hardware virtualization (/dev/kvm), which inside a VirtualBox VM means nested virtualization. The first time, dsoxlab start pulp-01-installer checks all of it before creating the machines. Prepare your machine for vm labs.

Install the CLI and add the catalogue, once:

uv tool install dsoxlab   # or: pipx install dsoxlab
dsoxlab catalog add https://github.com/stephrobert/artefacts-dsoxlab-training

Before you run the lab, check:

• DSOXLab installed
• catalogue available
• compatible environment (isolated shell or VM)

To check, nothing is probed from this page: run dsoxlab doctor. Read the diagnosis

Run this lab, then validate your work:

dsoxlab run pulp-01-installer
dsoxlab check pulp-01-installer

See every lab: dsoxlab list-labs. Track your progress: dsoxlab progress. The full dsoxlab guide covers scoring and the pitfalls.

Troubleshooting

Symptom	Likely cause	Solution
pip install downloads a file with the wrong digest	CONTENT_ORIGIN does not match the port or the public URL	Fix CONTENT_ORIGIN, restart the container
podman pull returns 500 on /v2/	TOKEN_SERVER or the ES256 key pair is missing	Add the token settings and generate the keys
The API takes a long time to answer on first start	PostgreSQL migrations in progress	Wait ~1 minute, watch podman logs pulp
podman pull refuses access (denied)	Anonymous pull not allowed	podman login with the admin account

Swipe to see more

Key points

• The pulp/pulp image runs the whole Pulp stack in a single container, ideal for getting started.
• The admin password is set with pulpcore-manager reset-admin-password.
• The CONTENT_ORIGIN parameter must always reflect the real public URL, otherwise the published links are broken.
• The pulp CLI drives the instance; the /ui/ interface explores it but remains young.
• In production, a Traefik reverse proxy terminates TLS with a single routing rule to port 80 of the container.

Knowledge check

Eight questions on what makes an instance usable: what the all-in-one image carries, the public URL that builds every published link, and how to prove the service rather than the container.

Knowledge check

Check what you have learned with this interactive quiz

8 questions

8 min

70% to pass

How it works

• The timer starts when you click Start
• Multiple choice, true/false and short answer questions
• You can move between questions
• Detailed results are shown at the end

Start the quiz

Starts the quiz and the timer

×

See in the glossary →