From 5c5f7eb76cfb24f8c8ed5168c2e2b7430fd28f6c Mon Sep 17 00:00:00 2001
From: jaehwang <jhyeu@o2o.kr>
Date: Tue, 8 Sep 2026 08:50:28 +0900
Subject: [PATCH] add docker

---
 backend/.dockerignore | 10 ++++++
 backend/Dockerfile    | 29 ++++++++++++++++++
 backend/README.md     | 71 ++++++++++++++++++++++++++++++++++++++++++-
 3 files changed, 109 insertions(+), 1 deletion(-)
 create mode 100644 backend/.dockerignore
 create mode 100644 backend/Dockerfile

diff --git a/backend/.dockerignore b/backend/.dockerignore
new file mode 100644
index 0000000..9332e1a
--- /dev/null
+++ b/backend/.dockerignore
@@ -0,0 +1,10 @@
+.venv/
+__pycache__/
+*.py[cod]
+.env
+.env.*
+tests/test_result/
+test_image/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
diff --git a/backend/Dockerfile b/backend/Dockerfile
new file mode 100644
index 0000000..dc46676
--- /dev/null
+++ b/backend/Dockerfile
@@ -0,0 +1,29 @@
+# python:3.14-slim은 Debian 12(glibc 2.36)라 PyAV manylinux_2_28 휠이 그대로 붙는다.
+# Ubuntu 18.04(glibc 2.27)에서 소스 빌드로 넘어가던 문제를 이걸로 피한다.
+FROM python:3.14-slim
+
+# Higgsfield CLI가 npm 패키지다 — ③ upscale과 ⑨ i2v가 이 바이너리를 부른다.
+RUN apt-get update \
+    && apt-get install -y --no-install-recommends nodejs npm ca-certificates \
+    && npm install -g @higgsfield/cli \
+    && npm cache clean --force \
+    && rm -rf /var/lib/apt/lists/*
+
+COPY --from=ghcr.io/astral-sh/uv:latest /uv /usr/local/bin/uv
+
+WORKDIR /app
+
+# 의존성만 먼저 깔아 레이어를 캐시한다
+COPY pyproject.toml uv.lock ./
+RUN uv sync --frozen --no-install-project
+
+COPY . .
+RUN uv sync --frozen
+
+ENV PATH="/app/.venv/bin:$PATH" \
+    PYTHONUNBUFFERED=1
+
+# CLI 토큰은 컨테이너가 켜질 때 호스트의 것을 참조한다:
+#   -v ~/.config/higgsfield:/root/.config/higgsfield
+EXPOSE 35000
+CMD ["uvicorn", "main:app", "--host", "0.0.0.0", "--port", "35000"]
diff --git a/backend/README.md b/backend/README.md
index 48d0521..a6c5d62 100644
--- a/backend/README.md
+++ b/backend/README.md
@@ -2,9 +2,49 @@
 
 ## Requirements
 
+### Python
+
+Python 3.14와 uv를 쓴다.
+
+```bash
+uv python install 3.14      # 없을 때만
+cd backend
+uv sync
+```
+
+`uv sync`가 `pyproject.toml`·`uv.lock` 기준으로 `.venv`를 만들고 패키지를 깐다.
+`uv run`은 실행 전에 알아서 sync 한다.
+
+### .env
+
+`backend/.env`에 둔다. `CHATGPT_API_KEY`만 없으면 기동이 안 되고, 나머지는 해당 단계를
+쓸 때 필요하다.
+
+| 키 | 쓰는 곳 |
+|---|---|
+| `CHATGPT_API_KEY` | detect · narration · motion · split 태깅 · 캐스트 · 제목 게이트 |
+| `TYPECAST_API_KEY` | 롱컷 tts (축제는 OpenAI를 써서 필요 없다) |
+| `SUNO_API_KEY` · `SUNO_CALLBACK_URL` | bgm |
+| `HIGGSFIELD_ACCOUNT` | upscale · i2v 계정 가드 |
+| `MYSQL_URL` | DB 세션 |
+| `AZURE_BLOB_BASE_URL` · `AZURE_BLOB_SAS_TOKEN` | blob 업로드 |
+
+### Docker
+
+```bash
+cd backend
+docker build -t poster-alive-backend .
+docker run --rm -p 35000:35000 \
+  --env-file .env \
+  -v ~/.config/higgsfield:/root/.config/higgsfield \
+  poster-alive-backend
+```
+
+Higgsfield CLI 토큰은 컨테이너가 켜질 때 호스트의 것을 참조한다.
+
 ### Higgsfield CLI
 
-⑥ i2v는 Higgsfield CLI를 서브프로세스로 부른다. 인증이 API 키가 아니라
+③ upscale과 ⑨ i2v가 Higgsfield CLI를 서브프로세스로 부른다. 인증이 API 키가 아니라
 `~/.config/higgsfield/credentials.json`의 CLI 토큰이라 머신마다 한 번씩 로그인해야 한다.
 
 ```bash
@@ -16,3 +56,32 @@ higgsfield workspace set <workspace-id>
 로그인 후 `higgsfield account status --json`이 돌려주는 이메일을 `.env`의
 `HIGGSFIELD_ACCOUNT`에 넣는다. 계정 가드가 이 값과 대조해, 다른 계정 토큰으로
 남의 크레딧이 빠지는 것을 막는다.
+
+## 실행
+
+파이프라인 둘은 게이트에서 끊어 돌린다. 게이트에서 사람이 확인하고 다음 스크립트를 부른다.
+
+### 축제 숏폼 — 포스터 1장
+
+```bash
+tests/run_poster_alive.sh            test_image/<poster>.jpg   # detect · narration · motion
+tests/run_poster_alive_after_gate.sh test_image/<poster>.jpg   # tts · bgm · i2v · render
+```
+
+### Playreel 롱컷 — NOL 상품 id
+
+```bash
+tests/run_playreel.sh             26007416   # fetch · split · 캐스트
+tests/run_playreel_after_gate1.sh 26007416   # upscale · analyze
+tests/run_playreel_after_gate2.sh 26007416   # motion · narration
+tests/run_playreel_after_gate3.sh 26007416   # tts · bgm · i2v
+tests/run_playreel_after_gate4.sh 26007416   # hybrid · compose
+```
+
+단계 하나만 돌리려면 모듈로 부른다. `backend/`에서 실행해야 한다.
+
+```bash
+uv run python -m tests.playreel.test_tts 26007416
+```
+
+산출물은 `tests/test_result/<플로우>/` 아래에 쌓인다.