deploy: compose.yaml, container_name, .env 적용 안내

Made-with: Cursor

docs/deploy.md

@@ -8,7 +8,7 @@ NAS에 SSH로 올리는 **전체 순서**는 `docs/nas-deploy-guide.md`에 따
 
 ## 로컬 개발
 
-1. `cp .env.example .env` 후 아래를 실제 주소로 맞춘다.
+1. `cp .env.example .env` 후 **`.env`만** 실제 주소로 맞춘다. (Compose·Vite는 `.env.example`을 자동으로 읽지 않는다.)
    - `VITE_PUBLIC_APP_URL`: 브라우저에서 웹앱을 여는 URL(로컬이면 `http://127.0.0.1:5173` 등).
    - `VITE_POCKETBASE_URL`: PocketBase URL(로컬이면 `http://127.0.0.1:8090` 등).
 2. `npm install`
@@ -23,7 +23,7 @@ NAS에 SSH로 올리는 **전체 순서**는 `docs/nas-deploy-guide.md`에 따
 - 빌드 시 `VITE_POCKETBASE_URL=https://api.todo.sori.studio`, `VITE_PUBLIC_APP_URL=https://todo.sori.studio` 를 넣는다. (`docker compose`는 프로젝트 루트의 `.env`를 읽어 `todo-web` 빌드 인자로 전달할 수 있다.)
 - PocketBase **CORS** 허용 출처에 `https://todo.sori.studio` 를 추가한다.
 
-PocketBase는 Docker로 띄우려면 `docker compose up pocketbase`만 실행해도 된다. 컨테이너 **내부**에서는 PocketBase가 `8090`을 쓰고, **호스트에 노출되는 포트**는 `docker-compose.yml`의 `ports`를 따른다(기본값: 웹 `42881`→컨테이너 `80`, API `42917`→컨테이너 `8090`).
+PocketBase는 Docker로 띄우려면 `docker compose up pocketbase`만 실행해도 된다. 컨테이너 **내부**에서는 PocketBase가 `8090`을 쓰고, **호스트에 노출되는 포트**는 `docker-compose.yaml`의 `ports`를 따른다(기본값: 웹 `42881`→컨테이너 `80`, API `42917`→컨테이너 `8090`).
 
 ## Docker Compose(웹 + PocketBase)
 
@@ -48,7 +48,7 @@ docker compose up -d --build
 
 ### 선택: 관리자 자동 생성
 
-`docker-compose.yml`의 `pocketbase` 서비스에 `PB_ADMIN_EMAIL`, `PB_ADMIN_PASSWORD` 환경 변수를 추가할 수 있다. 값은 저장소에 넣지 말고 NAS 비밀 관리 방식으로 주입한다.
+`docker-compose.yaml`의 `pocketbase` 서비스에 `PB_ADMIN_EMAIL`, `PB_ADMIN_PASSWORD` 환경 변수를 추가할 수 있다. 값은 저장소에 넣지 말고 NAS 비밀 관리 방식으로 주입한다.
 
 ## 단일 이미지(웹만)
 

docs/history.md

@@ -10,7 +10,7 @@ NAS에서 `git pull`만으로 갱신이 안 되는 경우(브랜치 불일치,
 
 ## 2026-04-13 · v0.0.4 — Compose 호스트 포트 분리
 
-NAS에 동시에 띄우는 서비스가 많아 **8080/8090 고정 매핑이 충돌**할 수 있어, `docker-compose.yml`에서 호스트 포트를 **42881(웹)·42917(PocketBase)** 로 바꿨다. 컨테이너 내부 포트(웹 80, PocketBase 8090)는 그대로 두어 이미지·설정 호환을 유지한다. 기본 `VITE_POCKETBASE_URL`은 `http://127.0.0.1:42917`으로 맞춘다.
+NAS에 동시에 띄우는 서비스가 많아 **8080/8090 고정 매핑이 충돌**할 수 있어, `docker-compose.yaml`에서 호스트 포트를 **42881(웹)·42917(PocketBase)** 로 바꿨다. 컨테이너 내부 포트(웹 80, PocketBase 8090)는 그대로 두어 이미지·설정 호환을 유지한다. 기본 `VITE_POCKETBASE_URL`은 `http://127.0.0.1:42917`으로 맞춘다.
 
 ## 2026-04-13 · v0.0.2 — NAS 배포 가이드 문서 분리
 

docs/map.md

@@ -15,7 +15,7 @@
 | `src/composables/useTodos.js` | 목록 로드·추가·완료 토글              |
 | `vite.config.js`          | Vue 플러그인, PWA 매니페스트(`VITE_PUBLIC_APP_URL` 반영) |
 | `tailwind.config.js`      | 테마 색·폰트                              |
-| `docker-compose.yml`      | PocketBase + 정적 웹(nginx), 호스트 포트 기본 42881·42917 |
+| `docker-compose.yaml`     | PocketBase + 정적 웹(nginx), `container_name`·호스트 포트 기본 42881·42917 |
 | `Dockerfile`              | Vite 빌드 후 nginx 이미지                 |
 | `nginx.conf`              | SPA 폴백 라우팅                           |
 | `docs/nas-deploy-guide.md` | NAS SSH·Git 클론·Compose·PocketBase 설정 순서 |

docs/nas-deploy-guide.md

@@ -92,7 +92,7 @@ cd /volume1/docker/projects/apps/todo
 ls
 ```
 
-`docker-compose.yml`, `Dockerfile`, `package.json` 등이 보이면 된다.
+`docker-compose.yaml`, `Dockerfile`, `package.json` 등이 보이면 된다.
 
 ---
 
@@ -103,7 +103,7 @@ ls
 
 예시:
 
-- `docker-compose.yml`에 적어 둔 **호스트 포트**(웹 `42881`, PocketBase `42917`)는 다른 스택과 겹치지 않게 잡은 값이다. 겹치면 해당 파일의 `ports`만 바꾼 뒤, 아래 `export`·`.env`의 포트도 같이 맞춘다.
+- `docker-compose.yaml`에 적어 둔 **호스트 포트**(웹 `42881`, PocketBase `42917`)는 다른 스택과 겹치지 않게 잡은 값이다. 겹치면 해당 파일의 `ports`만 바꾼 뒤, 아래 `export`·`.env`의 포트도 같이 맞춘다.
 - 같은 NAS 안의 브라우저만: `http://127.0.0.1:42917`처럼 **호스트에 열린 포트**로 접근한다. **폰이나 다른 PC**에서는 `127.0.0.1` 대신 **NAS LAN IP**를 써야 한다.
 - 집 안에서 여러 기기: `http://192.168.x.x:42917`(API), `http://192.168.x.x:42881`(웹) 형태로 쓴다.
 
@@ -115,7 +115,7 @@ IP 확인은 NAS 관리 화면의 네트워크 정보를 보거나, SSH에서 NA
 
 ## 6. 환경 변수 설정 후 Compose 실행
 
-`docker compose`는 프로젝트 루트에 **`.env` 파일이 있으면 자동으로 읽는다.** (Git에 올리지 말 것. `.gitignore`에 포함됨.)
+`docker compose`는 프로젝트 루트에 **`.env` 파일이 있으면 자동으로 읽는다.** (Git에 올리지 말 것. `.gitignore`에 포함됨.) **`.env.example`은 읽지 않는다.** 적용하려면 `cp .env.example .env` 후 `.env`만 수정한다.
 
 ### 6-0. 운영 도메인을 쓰는 경우(예: todo.sori.studio)
 
@@ -155,7 +155,7 @@ docker compose up -d --build
 docker compose ps
 ```
 
-`pocketbase`, `todo-web`(또는 compose에 정의된 웹 서비스 이름)이 `running`에 가깝게 보이면 된다.
+`todo-pocketbase`, `todo-web`(컨테이너 이름·`docker-compose.yaml`의 `container_name`)이 `running`에 가깝게 보이면 된다.
 
 ### 6-3. 로그가 궁금할 때
 
@@ -282,6 +282,7 @@ docker compose up -d --build
 | 폰에서만 안 됨 | `VITE_POCKETBASE_URL`이 `127.0.0.1`이 아닌지, 폰이 같은 Wi‑Fi인지, NAS IP가 맞는지 |
 | 빌드 후에도 주소가 이상함 | `docker compose build --no-cache` 후 다시 `up`, 또는 `export`를 잊지 않았는지 |
 | ARM NAS에서 이미지 오류 | 사용 중인 이미지가 해당 CPU 아키텍처를 지원하는지 로그로 확인한다. |
+| 컨테이너 이름 충돌 | `todo-pocketbase`·`todo-web`이 이미 있으면 `docker-compose.yaml`의 `container_name`을 바꾼다. |
 | `fatal: not a git repository` | `apps`가 아니라 **`cd todo`(클론한 폴더)** 안에서 실행했는지 확인한다. |
 | `git pull`이 안 되거나 안 받아짐 | 10절 순서대로 `git status`·`fetch`·`checkout main`·`pull --ff-only`, 로컬 수정·비공개 저장소 자격 확인 |
 

docs/spec.md

@@ -30,13 +30,15 @@
 
 ## Docker Compose 기본 호스트 포트
 
-다른 서비스와의 충돌을 줄이기 위해 **호스트**에 붙는 포트를 4만 번대로 둔다. `docker-compose.yml` 상단 주석과 `ports` 항목을 기준으로 한다.
+다른 서비스와의 충돌을 줄이기 위해 **호스트**에 붙는 포트를 4만 번대로 둔다. `docker-compose.yaml` 상단 주석과 `ports` 항목을 기준으로 한다.
 
 - 웹(nginx 정적): 호스트 **42881** → 컨테이너 `80`
 - PocketBase: 호스트 **42917** → 컨테이너 `8090`
 
 포트를 바꾼 경우 `VITE_POCKETBASE_URL`·`VITE_PUBLIC_APP_URL`의 포트·도메인도 동일하게 맞춘 뒤 이미지를 다시 빌드한다.
 
+Compose에서 **`container_name`** 을 고정해 두었다: `todo-pocketbase`, `todo-web`. NAS에 같은 이름의 컨테이너가 이미 있으면 `docker-compose.yaml`에서 바꾼다.
+
 ## 버전 정책
 
 - 앱 버전은 `package.json`의 `version`과 문서의 `v0.0.x` 형식을 맞춘다.

docs/update.md

@@ -10,7 +10,7 @@
 
 ## v0.0.4
 
-- ~수정. Docker Compose 호스트 포트: 웹 `42881`, PocketBase `42917`(충돌 시 `docker-compose.yml`만 조정).
+- ~수정. Docker Compose 호스트 포트: 웹 `42881`, PocketBase `42917`(충돌 시 `docker-compose.yaml`만 조정).
 - ~수정. `docs/deploy.md`, `docs/nas-deploy-guide.md`, `docs/spec.md`, `.env.example` 포트 안내 동기화.
 
 ## v0.0.3