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 (Korean). PLAN.md tracks staged progress (checkboxes); ref/design-ref.md is the visual design standard; MANUAL.md is the Coder/Gitea/Coolify dev+deploy environment guide.

Status: stages 0–4 are implemented and tested (dashboard, sync+polling, version list, gated deploy+audit). Stage 5 = containerization/packaging. Code lives under app/ (config.py, pulp_client.py, deps.py, views.py, audit.py, task_store.py, routes/, templates/, static/); tests under tests/.

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 + a custom layer (app/static/app.css) applying the ref/design-ref.md tokens (Toss-style). Pretendard font is vendored locally. No decorative emoji in chrome — status uses colored chips/dots.

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) — implemented in routes/deploy.py

• Verification gate (re-checked server-side): only repo_config GPG-passing repos are deployable; the button is disabled otherwise. Note verification is repo-level config, so it indicates "verification is configured", not a per-snapshot cryptographic proof (real package checks happen at sync time).
• Confirmation modal with a preview (current → target version, net package delta) and type-to-confirm (operator must type the repo name).
• Audit log → Postgres (audit.py, table deploy_audit): who / when / repo / from-version → to-version (rollback trail). DB write failure does not 500 a completed deploy — it surfaces an audit_ok=False warning (TODO: hard-fail if audit becomes mandatory policy).
• Two-step clarity: deploy = create publication → PATCH distribution; on failure the UI states clearly whether production was changed.
• Auth is a TODO (operator is a placeholder; deploy-time password re-entry 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 page
GET  /repos/{uuid}/deploy/confirm   deploy confirmation modal (preview + type-to-confirm)
POST /repos/{uuid}/deploy           gated deploy (publication + distribution) + audit
GET  /healthz                       app liveness — always {"ok": true} (container health)
GET  /pulp-status                   Pulp connectivity badge (dashboard polls this)

Pulp access is centralized in pulp_client.py (get/post/patch with Basic Auth, plus status, list_repos, get_repo, get_version, list_versions, sync_repo, get_task, list_distributions, get_publication, create_publication, update_distribution, wait_for_task). HTML polling is the page's job; the client only single-fetches — except wait_for_task, used only for the compound deploy (publication→distribution) where server-side waiting is needed. In-flight syncs are tracked in task_store.py (in-memory; single instance only). View-model shaping (pure, httpx-free) lives in views.py.

Configuration (env vars)

PULP_BASE_URL, PULP_USERNAME, PULP_PASSWORD (secret), PULP_VERIFY_TLS, PULP_CA_FILE (internal CA pem), DATABASE_URL (Postgres for audit log), PORT (default 8000), PULP_DEMO (fake data for screen preview, default off).

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.

Commands

.venv/Scripts/python.exe -m uvicorn app.main:app --reload   # run (http://127.0.0.1:8000)
.venv/Scripts/python.exe -m pytest -q                        # tests
.venv/Scripts/python.exe -m ruff check app tests             # lint
.venv/Scripts/python.exe -m ruff format app tests            # format

Tests mock the Pulp client via FastAPI dependency_overrides (route tests) or respx (client tests); views.py is unit-tested as pure functions. Audit DB writes are intercepted by monkeypatching app.audit._write.

Deployment

Now (demo): Coolify builds the repo Dockerfile (Build Pack: Dockerfile, Port 8000) and injects env vars — see README.md / MANUAL.md. /healthz is liveness only so Pulp being down doesn't fail the container.

Final target is the air-gapped network: static assets are already vendored (no runtime CDN); only Python deps need offline reintroduction via a wheelhouse (pip download → swap the Dockerfile install step). Procedure in README.md.

Conventions

• Python 3.14 local venv; deps pinned in requirements.txt (container uses python:3.13-slim). Reference Pulp objects by pulp_href, not name.
• Each stage should produce a working screen and stay green (tests + ruff) before commit.