pulp-console/AIRGAP_DEPLOY.md

폐쇄망 반입·구동 가이드 (Python venv, 컨테이너 미사용)

서버관리망이 컨테이너 없이 Python 가상환경으로 구동하는 환경일 때의 반입 절차. 핵심은 소스 + wheelhouse(오프라인 .whl 묶음) 를 매체로 들고 들어가 거기서 venv로 설치·실행하는 것.

정적 자산(pico·htmx·Pretendard·JetBrains Mono)은 이미 app/static/에 동봉돼 있어 런타임 인터넷 불필요. 외부 의존은 Python 패키지(pip)뿐 → 이걸 wheelhouse로 해결한다.

---

0. 사전 확인 (가장 중요)

폐쇄망 타깃 서버에서 Python 버전·아키텍처를 확인한다. wheel은 이 값에 맞춰 받아야 한다.

python3 --version     # 예: Python 3.12.x  → cp312
uname -m              # 예: x86_64

• 타깃 Python이 3.11/3.12 등이면 wheelhouse도 그 버전으로 받아야 한다(컴파일 wheel: pydantic-core, psycopg 등).
• 가능하면 타깃과 같은 OS/파이썬(예: Rocky9 + python3.12)에서 wheelhouse를 만드는 게 가장 안전하다.

---

1. 인터넷 되는 곳에서 산출물 준비

(a) 소스 — git 메타·가상환경 제외하고 압축

git archive --format=tar.gz -o pulp-console-src.tgz HEAD
# (또는 repo 폴더에서 .git/.venv/tests 빼고 zip)

(b) wheelhouse — 타깃 Python/플랫폼에 맞춰 다운로드

# 타깃과 동일 환경(권장):
pip download -r requirements.txt -d vendor/

# 빌드 머신과 타깃이 다르면 플랫폼/버전 명시:
pip download -r requirements.txt -d vendor/ \
  --only-binary=:all: --implementation cp \
  --platform manylinux2014_x86_64 --python-version 312

vendor/에 모든 의존성 .whl이 모인다. (개수 확인: ls vendor | wc -l)

참고: uvicorn[standard]는 uvloop/httptools/watchfiles 등 컴파일 wheel을 포함한다. 버전 매칭이 까다로우면 requirements.txt의 uvicorn[standard]를 uvicorn(순정)으로 바꿔 wheel 세트를 줄일 수 있다 (운영은 --reload 안 쓰므로 watchfiles 불필요).

---

2. 반입 매체에 담을 것

• pulp-console-src.tgz (소스 — 정적자산 포함)
• vendor/ (wheelhouse)
• boknet-ca.pem (사내 HTTPS Pulp 검증용 CA)
• 환경변수 값 메모: PULP_BASE_URL / PULP_USERNAME / PULP_PASSWORD / DATABASE_URL (비밀번호는 안전한 방법으로)

---

3. 폐쇄망에서 설치·구동

mkdir -p /opt/pulp-console && cd /opt/pulp-console
tar xzf /media/pulp-console-src.tgz          # 소스 풀기
cp -r /media/vendor ./vendor                 # wheelhouse 복사

python3 -m venv .venv
.venv/bin/pip install --no-index --find-links vendor -r requirements.txt

환경변수(.env 또는 systemd) 설정 후 실행 — 운영은 --reload 금지:

PULP_BASE_URL=https://repo.서버관리망:8080 \
PULP_USERNAME=admin PULP_PASSWORD='***' \
PULP_VERIFY_TLS=true PULP_CA_FILE=/opt/pulp-console/boknet-ca.pem \
DATABASE_URL='postgresql://...' \
.venv/bin/uvicorn app.main:app --host 0.0.0.0 --port 8000

---

4. 상시 구동 (systemd 예시)

/etc/systemd/system/pulp-console.service:

[Unit]
Description=Pulp 패치 관리 콘솔
After=network.target

[Service]
WorkingDirectory=/opt/pulp-console
EnvironmentFile=/opt/pulp-console/.env
ExecStart=/opt/pulp-console/.venv/bin/uvicorn app.main:app --host 0.0.0.0 --port 8000
Restart=on-failure
User=pulpconsole

[Install]
WantedBy=multi-user.target

sudo systemctl daemon-reload && sudo systemctl enable --now pulp-console

.env(권한 600)에 PULP_*, DATABASE_URL, PULP_CA_FILE 등 기입.

---

5. 구동 확인

curl 127.0.0.1:8000/healthz        # {"ok": true} (앱 생존)
curl 127.0.0.1:8000/pulp-status    # Pulp 연결 배지 (실패 시 사유)

브라우저로 대시보드 접속 → 실제 저장소 목록 확인. 연동 검증은 PULP_INTEGRATION.md §5 체크리스트 참고.

---

6. 업데이트(다음 버전 반입)

• 소스만 바뀌면: 새 pulp-console-src.tgz만 반입해 교체 후 systemctl restart pulp-console.
• 의존성이 바뀌면(requirements.txt 변경): vendor/에 새 wheel도 함께 반입 후 pip install --no-index --find-links vendor -r requirements.txt 재실행.

---

venv / pip 가 없을 때 (대안)

venv는 필수가 아니다. 필요한 건 Python 인터프리터 하나뿐. 점점 더 미니멀한 순서:

① venv만 없음 — pip --target + PYTHONPATH

python3 -m pip install --no-index --find-links vendor --target ./libs -r requirements.txt
PYTHONPATH=./libs python3 -m uvicorn app.main:app --host 0.0.0.0 --port 8000

② pip도 없음 — pip wheel 부트스트랩 (반입물에 pip-*.whl 포함: pip download pip -d vendor/)

python3 vendor/pip-*.whl/pip install --no-index --find-links vendor --target ./libs -r requirements.txt
# wheel 은 zip 이라 설치 없이 바로 실행됨. (또는 python3 -m ensurepip)

③ pip 자체가 불가 — wheel 압축해제 + PYTHONPATH (pip 0개)

mkdir libs && cd libs
for w in ../vendor/*.whl; do unzip -oq "$w"; done   # wheel=zip, 컴파일 .so 포함
cd .. && PYTHONPATH=./libs python3 -m uvicorn app.main:app --host 0.0.0.0 --port 8000

④ Python 자체가 없음 — 독립 실행형 Python 반입

• python-build-standalone(astral-sh) tarball을 풀어 그 안의 bin/python3로 ①~③ 수행. 단, 그 Python 버전에 맞춰 wheelhouse를 받을 것(§0).

systemd 로 상시 구동 시 ExecStart를 위 실행 커맨드로 바꾸면 된다 (예: Environment=PYTHONPATH=/opt/pulp-console/libs + ExecStart=/usr/bin/python3 -m uvicorn ...).

---

폐쇄망에 이미 있어야 하는 것

• Python 3.x (타깃 버전 — §0). venv/pip 없어도 위 대안으로 가능.
• Pulp 서버 (붙는 대상, 이미 존재)
• Postgres (감사 로그용; 없으면 배포는 되나 "감사 로그 기록 실패" 경고)
• 사내 CA(.pem) (HTTPS Pulp 검증)