From 6bfd48d3c47b747294aaf8f327f5f0c38b5b82e8 Mon Sep 17 00:00:00 2001 From: Mina Choi Date: Mon, 31 Aug 2026 17:15:47 +0900 Subject: [PATCH] =?UTF-8?q?=EB=AC=B8=EC=84=9C:=20=EC=84=A4=EC=A0=95=20?= =?UTF-8?q?=ED=8C=8C=EC=9D=BC=EC=9D=B4=206=EA=B0=9C=20=ED=95=84=EC=9A=94?= =?UTF-8?q?=ED=95=9C=20=EA=B2=83=EC=B2=98=EB=9F=BC=20=EC=A0=81=ED=98=80=20?= =?UTF-8?q?=EC=9E=88=EB=8D=98=20=EA=B2=83=EC=9D=84=20=EB=B0=94=EB=A1=9C?= =?UTF-8?q?=EC=9E=A1=EB=8A=94=EB=8B=A4?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 앞 커밋의 표가 여섯 줄을 나란히 놓아서 "클론하면 여섯 개를 만들어야 한다" 로 읽혔다. 실제로 세어 보니 compose 로 띄우는 데 필요한 건 둘이다. - .env compose 가 env_file 로 읽는다 - nginx/site.conf compose 가 bind mount 한다 나머지 넷은 필수가 아니다. - config.local.toml : 도커 이미지가 example 사본을 구워서 나온다(Dockerfile:24). 호스트에서 python web_main.py 를 직접 돌릴 때만 손으로 만든다. - config.test.toml : pytest 를 돌릴 때만. - 프론트 .env 둘 : VITE_* 가 전부 코드 폴백을 갖고 있고(?? 'http://localhost:9800', ?? window.location.host) compose 는 값을 직접 주입한다. 만들 이유가 없다. 표를 필수/선택/안 만들어도 됨으로 갈랐다. 클론 직후 명령도 둘로 줄이고, toml 은 "호스트에서 돌릴 때만" 이라는 조건을 붙여 아래로 내렸다. --- AGENTS.md | 36 +++++++++++++++++++----------------- README.md | 6 +++--- 2 files changed, 22 insertions(+), 20 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index 693fc9e..4b25a46 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -107,17 +107,19 @@ docker compose logs -f worker ## 설정 파일은 어느 폴더에 두나 -**실제 값은 하나도 커밋되지 않는다.** 커밋되는 건 `*.example` 뿐이고, 클론 직후 그걸 복사해 -값을 채우는 게 세팅의 전부다. +**`docker compose up -d` 에 꼭 필요한 건 두 개다.** 나머지는 호스트에서 파이썬을 직접 +돌릴 때만 붙는다 — 앱마다 설정이 흩어져 있는 게 아니다. -| 폴더 | 파일 | 담는 것 | 템플릿 | +| | 폴더 | 파일 | 없으면 | |---|---|---|---| -| **레포 루트** | `.env` | DB · JWT · 외부 API 키 · 수집 어댑터 · 발행/색인 · 포트 바인딩 | `.env.example` | -| `solution/backend/config/` | `config.local.toml` | DB 접속 · JWT · 포트 · CORS(`client_url`) | `config.local.toml.example` | -| `solution/backend/config/` | `config.test.toml` | 테스트 DB(`web4ai_test_db`) | `config.test.toml.example` | -| `solution/frontend/` | `.env` | 이 앱의 `VITE_*` (API :9800 · 발행 호스트 · 개발 자동로그인) | `.env.example` | -| `admin/frontend/` | `.env` | 이 앱의 `VITE_*` (API **:9801**) | `.env.example` | -| `nginx/` | `site.conf` | 발행 사이트 정적 서빙 규칙 | `site.conf.example` | +| **필수** | 레포 루트 | `.env` | compose 가 `env_file` 로 읽는다. DB·JWT·API 키가 안 들어간다 | +| **필수** | `nginx/` | `site.conf` | compose 가 bind mount 한다. **Docker 가 그 자리에 디렉토리를 만들어** nginx 가 설정 없이 뜬다 | +| 선택 | `solution/backend/config/` | `config.local.toml` | 호스트에서 백엔드를 직접 돌릴 때만. **도커 이미지는 이걸 구워서 나온다**(`Dockerfile:24`) | +| 선택 | `solution/backend/config/` | `config.test.toml` | `pytest` 가 conftest import 단계에서 죽는다 | +| 안 만들어도 됨 | `solution/frontend/` | `.env` | 코드에 폴백이 다 있고(`?? 'http://localhost:9800'`), compose 는 값을 직접 주입한다 | +| 안 만들어도 됨 | `admin/frontend/` | `.env` | 〃 | + +전부 `*.example` 이 짝으로 있고, 실제 값은 하나도 커밋되지 않는다. **두지 않는 곳** — 두면 조용히 무시된다. @@ -125,22 +127,22 @@ docker compose logs -f worker |---|---| | `solution/backend/` | `.env` 를 여기 두면 아무도 안 읽는다. dotenv 가 **레포 루트**를 본다 (`config/server_configs.py`) | | `admin/backend/` | 진입점 두 파일뿐이다. `config/` 는 `PYTHONPATH` 로 `solution/backend` 것을 그대로 쓴다 | -| `solution/site/` | 렌더러는 런타임 env 를 안 쓴다 — 사이트별 값은 전부 `SitePayload` 로 들어온다. 그래야 payload 하나로 같은 HTML 이 재현된다. 프리렌더 옵션은 CLI 인자(`--payload` `--out`)이고, `INDEXNOW_KEY`·`PORT` 는 compose 가 프로세스에 넣는다 | +| `solution/site/` | 렌더러는 런타임 env 를 안 쓴다 — 사이트별 값은 전부 `SitePayload` 로 들어온다. 프리렌더 옵션은 CLI 인자(`--payload` `--out`)이고, `INDEXNOW_KEY`·`PORT` 는 compose 가 프로세스에 넣는다 | | `solution/shared/` | 코드만 있다 | ### 클론 직후 한 번 ```bash -cp .env.example .env +cp .env.example .env # JWT_* 는 반드시 채운다(아래 참고) cp nginx/site.conf.example nginx/site.conf -cp solution/backend/config/config.local.toml.example solution/backend/config/config.local.toml -cp solution/backend/config/config.test.toml.example solution/backend/config/config.test.toml -cp solution/frontend/.env.example solution/frontend/.env # compose 로만 쓰면 생략 가능 -cp admin/frontend/.env.example admin/frontend/.env # 〃 ``` -`site.conf` 를 빼먹으면 Docker 가 그 자리에 **디렉토리**를 만들어 nginx 가 설정 없이 뜬다. -`config.test.toml` 이 없으면 `pytest` 가 conftest import 단계에서 죽는다. +호스트에서 백엔드를 돌리거나 `pytest` 를 쓸 때만 추가로: + +```bash +cp solution/backend/config/config.local.toml.example solution/backend/config/config.local.toml +cp solution/backend/config/config.test.toml.example solution/backend/config/config.test.toml +``` ### 누가 무엇을 읽나 — 우선순위 diff --git a/README.md b/README.md index aa7a431..d7d59ff 100644 --- a/README.md +++ b/README.md @@ -13,10 +13,10 @@ ## 실행 ```bash -# 클론 직후 1회 — 설정 파일 복사 목록은 AGENTS.md "설정 파일은 어느 폴더에 두나" -cp .env.example .env +# 클론 직후 1회 — compose 에 필요한 건 이 둘뿐이다. +# 호스트에서 백엔드·pytest 를 직접 돌릴 때 붙는 toml 은 AGENTS.md 참고. +cp .env.example .env # JWT_* 를 채운다 cp nginx/site.conf.example nginx/site.conf -cp solution/backend/config/config.local.toml.example solution/backend/config/config.local.toml docker compose up -d docker compose logs -f worker