pulp-console/CLAUDE.md

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

What this is

A thin, self-hosted web admin console for Pulp 3, a Linux patch-repository server. Pulp has a full REST API (/pulp/api/v3/) but no usable official web UI, so this project builds a focused operator console on top of that API.

Context: it runs in an air-gapped (closed) network at the Bank of Korea IT Strategy Dept. cloud team. The console lets operators mirror, snapshot, verify, and deploy RPM/DEB patch repositories by clicking instead of running CLI commands.

The full implementation spec is pulp-console-spec.md (written in Korean, addressed to the implementing AI). It is the source of truth — read it before making design decisions. The codebase itself does not yet exist; the spec describes what to build and in what order.

Stack (decided — do not substitute)

• Backend / BFF: FastAPI (Python), using httpx to call Pulp.
• Frontend: HTMX + Jinja2 templates. No build step. Buttons trigger partial-HTML swaps; progress polling is done with hx-trigger="every 3s".
• Styling: Pico.css (preferred for air-gap simplicity) or Tailwind standalone.

Hard constraints (these are the point of the project)

• The browser never calls the Pulp API directly. All traffic goes through the FastAPI BFF, which holds Pulp Basic Auth credentials and proxies requests. This protects credentials and avoids CORS exposure.
• No heavy frontend tooling (React, Vite, npm build chains). HTML + HTMX only.
• Air-gap first: minimize CDN dependence. Bundle CSS / HTMX JS under static/ so the app runs with no internet access.
• View routes return HTML (full pages or fragments), not JSON — HTMX consumes HTML.
• Self-signed CA support from day one: the httpx client must accept a verify=PULP_CA_FILE option for the internal TLS CA (boknet CA family).

Architecture

Browser (HTMX + Jinja)  ──form/button──►  FastAPI BFF  ──Basic Auth──►  Pulp REST API (/pulp/api/v3/)
        ◄──── partial HTML ────                ◄──────── JSON ────────

The BFF receives Pulp JSON, renders it into Jinja partial templates, and returns HTML fragments that HTMX swaps into the page.

Pulp object model (essential to understand the flow)

Remote (source def) → Repository (container) → RepositoryVersion (snapshot) → Publication (deployable form) → Distribution (public URL)

The URL operators point yum/dnf baseurl at is the Distribution.

Two operations matter:

1. Sync (POST .../repositories/rpm/rpm/{uuid}/sync/): pulls from an external mirror and creates a new RepositoryVersion snapshot. Relatively safe — does not change what production servers receive. Returns an async task.
2. Deploy (create Publication → PATCH the Distribution's publication): dangerous — changes the version production actually fetches.

Pulp objects reference each other by pulp_href (a path string); use href, not name, in code. Sync and deploy return async tasks — capture task_href and poll GET {task_href} (state: waiting/running/completed/failed) for completion. RPM paths use rpm/rpm; the DEB equivalent swaps that segment for deb/apt.

Safety model (deploy is gated)

• Deploy must go through a confirmation modal (hx-confirm or an explicit step).
• The deploy button is disabled for versions that aren't verified (GPG / checksum passed). Verification comes from the Remote's gpgkey/tls_validation and the Repository repo_config (gpgcheck: 1, repo-gpgcheck: 1) — this is the basis for the "verified ✅" badge.
• Every deploy is written to an audit log (who / when / which repo / which version).

Planned route surface (BFF)

GET  /                       dashboard (full page)
GET  /repos                  repo list fragment
POST /repos/{uuid}/sync      start sync, return progress-bar fragment
GET  /repos/{uuid}/progress  progress-bar fragment (polled every 3s)
GET  /repos/{uuid}/versions  version list fragment/page
POST /repos/{uuid}/deploy    confirm deploy (publication + distribution), result fragment
GET  /healthz                proxy Pulp status

Pulp access is centralized in a pulp_client.py helper (get/post/patch with Basic Auth, list_repos, sync_repo, list_versions, create_publication, update_distribution, single task fetch — the page does the polling, not the client).

Configuration (env vars)

PULP_BASE_URL, PULP_USERNAME, PULP_PASSWORD (secret), PULP_VERIFY_TLS, PULP_CA_FILE (path to internal CA pem).

Build order (from the spec — build in working-screen increments)

1. Skeleton: FastAPI + Jinja2 + httpx, pulp_client.py stub, /healthz hitting Pulp status.
2. Dashboard (read-only repo list/cards).
3. Sync: POST sync → task_href → polling progress fragment.
4. Version list + verification badges.
5. Deploy: confirm modal → create publication → PATCH distribution → poll → audit log.
6. Styling, bundle static assets for air-gap, containerize.

Each step should produce a working screen. Do not build everything at once.

Conventions

• Python 3.14 is installed locally. Once code exists, prefer a virtualenv and pin dependencies (requirements.txt / lockfile) so they can be carried into the air-gapped network via pip.