Hyemin Lee
b24d76ad08
- Dockerfile (python:3.13-slim, uvicorn, 비루트, PORT, /healthz HEALTHCHECK) - .dockerignore - README: 로컬/컨테이너/Coolify 배포 + 폐쇄망 wheelhouse 반입 절차 - CLAUDE.md 갱신(현재 구현 상태/라우트/명령/배포), MANUAL.md 추가 - 정적자산은 이미 로컬 동봉(런타임 CDN 0) → 최종 폐쇄망 반입은 의존성 wheelhouse만 Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
88 lines
3.6 KiB
Markdown
88 lines
3.6 KiB
Markdown
# Pulp 패치 관리 콘솔
|
||
|
||
공식 관리 UI가 없는 **Pulp 3**을 운영자가 클릭만으로 다루게 해주는 사내용 얇은 관리 콘솔.
|
||
핵심 가치: **검증이 끝난 특정 스냅샷(버전)만 운영 서버에 배포되도록 사람이 통제하는 화면.**
|
||
|
||
- 스택: **FastAPI + HTMX + Jinja2** (프론트 빌드 단계 없음), Pulp REST API를 **BFF가 프록시**.
|
||
- 브라우저는 Pulp를 직접 호출하지 않는다(인증정보·CORS 보호). 정적자산은 로컬 동봉(런타임 CDN 0개).
|
||
- 자세한 스펙은 `pulp-console-spec.md`, 단계별 진행은 `PLAN.md`, 디자인 기준은 `ref/`.
|
||
|
||
## 빠른 시작 (로컬)
|
||
|
||
```bash
|
||
python -m venv .venv
|
||
.venv/Scripts/python.exe -m pip install -r requirements-dev.txt # Windows
|
||
# (리눅스/맥: .venv/bin/pip install -r requirements-dev.txt)
|
||
|
||
# 실행
|
||
.venv/Scripts/python.exe -m uvicorn app.main:app --reload # http://127.0.0.1:8000
|
||
# 테스트 / 린트
|
||
.venv/Scripts/python.exe -m pytest -q
|
||
.venv/Scripts/python.exe -m ruff check app tests
|
||
```
|
||
|
||
**데모 모드** — 실제 Pulp 없이 화면을 보려면:
|
||
```bash
|
||
PULP_DEMO=true .venv/Scripts/python.exe -m uvicorn app.main:app --reload
|
||
```
|
||
|
||
## 환경변수
|
||
|
||
| 변수 | 용도 | 비고 |
|
||
|---|---|---|
|
||
| `PULP_BASE_URL` | Pulp API 주소 | 예 `http://repo.internal:8080` |
|
||
| `PULP_USERNAME` / `PULP_PASSWORD` | Pulp Basic Auth | 비밀번호는 git에 두지 않음 |
|
||
| `PULP_VERIFY_TLS` | TLS 검증 on/off | 사내 self-signed면 `PULP_CA_FILE` 사용 |
|
||
| `PULP_CA_FILE` | 사내 CA(.pem) 경로 | HTTPS Pulp + 사내 CA일 때 |
|
||
| `DATABASE_URL` | 감사 로그용 Postgres | 미설정 시 배포는 되나 감사 기록 실패 경고 |
|
||
| `PORT` | 서버 포트 | 기본 8000 |
|
||
| `PULP_DEMO` | 데모 모드 | 기본 off |
|
||
|
||
## 헬스 / 상태
|
||
|
||
- `GET /healthz` — 앱 라이브니스. Pulp와 무관하게 항상 `{"ok": true}` (컨테이너 health check용).
|
||
- `GET /pulp-status` — Pulp 연결 상태 배지(대시보드가 폴링).
|
||
|
||
## 컨테이너 빌드 (배포 전 점검 — MANUAL §10)
|
||
|
||
```bash
|
||
podman build -t pulp-console .
|
||
podman run --rm -p 8000:8000 \
|
||
-e PULP_BASE_URL=... -e PULP_USERNAME=... -e PULP_PASSWORD=... \
|
||
-e DATABASE_URL="$DATABASE_URL" pulp-console
|
||
curl 127.0.0.1:8000/healthz # {"ok":true}
|
||
```
|
||
|
||
## Coolify 배포 (MANUAL §11–12)
|
||
|
||
1. Gitea에 push.
|
||
2. Coolify에서 **Public Repository** → repo 전체 URL → **Build Pack: `Dockerfile`**, Branch `main`, **Port `8000`**.
|
||
3. **Environment Variables**에 위 표의 값 입력(`PULP_*`, `DATABASE_URL`, `PORT`). 비밀번호/`DATABASE_URL`은 여기에만.
|
||
4. 도메인은 `*.apps.bokdev.in`으로 지정 → Deploy.
|
||
|
||
## 감사 로그 (배포 기록)
|
||
|
||
배포 확정은 Postgres `deploy_audit` 테이블에 기록된다(누가/언제/repo/이전→대상 버전, 롤백 추적).
|
||
테이블은 최초 기록 시 자동 생성(`CREATE TABLE IF NOT EXISTS`). `DATABASE_URL` 필요.
|
||
|
||
## 폐쇄망 반입 (최종 산출물)
|
||
|
||
정적자산(Pico/htmx/Pretendard)은 이미 `app/static/`에 동봉되어 인터넷 없이 동작한다.
|
||
Python 의존성만 오프라인으로 넣으면 된다 — 인터넷 가능 리눅스에서 wheelhouse를 받아 동봉:
|
||
|
||
```bash
|
||
pip download -r requirements.txt -d vendor/ \
|
||
--platform manylinux2014_x86_64 --python-version 313 --only-binary=:all:
|
||
```
|
||
|
||
그리고 `Dockerfile`의 설치 단계를 오프라인으로 교체:
|
||
|
||
```dockerfile
|
||
COPY requirements.txt .
|
||
COPY vendor/ ./vendor/
|
||
RUN pip install --no-cache-dir --no-index --find-links=vendor -r requirements.txt
|
||
```
|
||
|
||
> 현재(데모) 배포는 Coolify가 빌드 시 의존성을 받는 `pip install` 방식이다.
|
||
> Coolify 빌드에서 PyPI 접근이 막히면 위 wheelhouse 방식으로 전환한다.
|