diff --git a/.env.example b/.env.example index 2b0f55f..2eec8ee 100644 --- a/.env.example +++ b/.env.example @@ -1,3 +1,9 @@ +# --- 적용 방법 --- +# Docker Compose와 Vite는 프로젝트 루트의 `.env`만 자동으로 읽는다. +# 이 파일(`.env.example`)은 예시일 뿐이며, 적용하려면 복사해서 이름을 바꾼다. +# cp .env.example .env +# 그다음 `.env` 안의 값만 수정하면 된다. (`.example`을 뗀 `.env`가 실제 설정 파일이다.) + # 사용자에게 노출되는 웹앱 URL(끝 슬래시 없음). PWA manifest 식별 등에 사용 VITE_PUBLIC_APP_URL=https://todo.sori.studio @@ -8,6 +14,6 @@ VITE_POCKETBASE_URL=https://api.todo.sori.studio # VITE_PUBLIC_APP_URL=http://127.0.0.1:5173 # VITE_POCKETBASE_URL=http://127.0.0.1:8090 -# docker compose 기본 호스트 포트로 NAS LAN에서 접속할 때(포트는 docker-compose.yml과 맞출 것) +# docker compose 기본 호스트 포트로 NAS LAN에서 접속할 때(포트는 docker-compose.yaml과 맞출 것) # VITE_PUBLIC_APP_URL=http://192.168.0.50:42881 # VITE_POCKETBASE_URL=http://192.168.0.50:42917 diff --git a/docker-compose.yml b/docker-compose.yaml similarity index 92% rename from docker-compose.yml rename to docker-compose.yaml index 355c474..0ae15f8 100644 --- a/docker-compose.yml +++ b/docker-compose.yaml @@ -4,6 +4,7 @@ services: pocketbase: image: ghcr.io/muchobien/pocketbase:latest + container_name: todo-pocketbase restart: unless-stopped environment: PB_HOST: 0.0.0.0 @@ -19,6 +20,7 @@ services: args: VITE_POCKETBASE_URL: ${VITE_POCKETBASE_URL:-http://127.0.0.1:42917} VITE_PUBLIC_APP_URL: ${VITE_PUBLIC_APP_URL:-} + container_name: todo-web restart: unless-stopped ports: - "42881:80" diff --git a/docs/deploy.md b/docs/deploy.md index 2b082d3..8dd1ff8 100644 --- a/docs/deploy.md +++ b/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 비밀 관리 방식으로 주입한다. ## 단일 이미지(웹만) diff --git a/docs/history.md b/docs/history.md index c6f35f8..aa08083 100644 --- a/docs/history.md +++ b/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 배포 가이드 문서 분리 diff --git a/docs/map.md b/docs/map.md index b05d27f..b0e6f45 100644 --- a/docs/map.md +++ b/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 설정 순서 | diff --git a/docs/nas-deploy-guide.md b/docs/nas-deploy-guide.md index f433a4f..87f3dde 100644 --- a/docs/nas-deploy-guide.md +++ b/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`, 로컬 수정·비공개 저장소 자격 확인 | diff --git a/docs/spec.md b/docs/spec.md index b6859e5..ef64c70 100644 --- a/docs/spec.md +++ b/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` 형식을 맞춘다. diff --git a/docs/update.md b/docs/update.md index 8b9d61e..f615848 100644 --- a/docs/update.md +++ b/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