todo.sori.studio/docs/deploy.md

배포 가이드

현재 버전

• v0.0.8

NAS에 SSH로 올리는 전체 순서는 docs/nas-deploy-guide.md에 따로 정리했다.

로컬 개발

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
3. npm run dev

운영 예시는 .env.example에 https://todo.sori.studio / https://api.todo.sori.studio 로 적어 두었다.

운영 도메인(todo.sori.studio) 요약

• 웹앱: https://todo.sori.studio → 리버스 프록시에서 정적 웹 컨테이너(또는 빌드 산출물)로 연결.
• API(PocketBase): https://api.todo.sori.studio → 같은 프록시 또는 별도 가상 호스트로 PocketBase에 연결.
• 빌드 시 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.yaml의 ports를 따른다(기본값: 웹 42881→컨테이너 80, API 42917→컨테이너 8090).

Docker Compose(웹 + PocketBase)

프로젝트 루트에서(LAN IP 예시):

export VITE_PUBLIC_APP_URL="http://<이_기기_IP>:42881"
export VITE_POCKETBASE_URL="http://<이_기기_IP>:42917"
docker compose up -d --build

• 웹: http://<이_기기_IP>:42881
• PocketBase 관리자: http://<이_기기_IP>:42917/_/

중요: VITE_POCKETBASE_URL은 컨테이너가 아니라 브라우저에서 접근한다. 같은 PC에서만 쓸 때는 http://127.0.0.1:42917(compose 기본 호스트 포트)이 가능하지만, 휴대폰 등 다른 기기에서는 NAS LAN IP 또는 공인 도메인을 사용해야 한다. 외부에는 리버스 프록시 80/443만 열고 내부 포트는 NAS 안에서만 쓰는 구성도 가능하다.

PocketBase 초기 설정 요약

1. 관리자 UI에서 컬렉션 todos 생성(title text, done bool).
2. API 규칙을 배포 방식에 맞게 설정(인증 사용 시 로그인 사용자만 생성·수정 가능 등).
3. CORS 허용 출처에 웹 앱 출처를 추가한다. (LAN이면 http://<IP>:42881, 도메인이면 https://todo.sori.studio 등 주소창과 동일하게.)

선택: 관리자 자동 생성

docker-compose.yaml의 pocketbase 서비스에 PB_ADMIN_EMAIL, PB_ADMIN_PASSWORD 환경 변수를 추가할 수 있다. 값은 저장소에 넣지 말고 NAS 비밀 관리 방식으로 주입한다.

단일 이미지(웹만)

Dockerfile은 정적 빌드 결과를 nginx로 제공한다. 빌드 시점에 VITE_POCKETBASE_URL, VITE_PUBLIC_APP_URL이 번들·매니페스트에 반영된다.

docker build \
  --build-arg VITE_POCKETBASE_URL="https://api.todo.sori.studio" \
  --build-arg VITE_PUBLIC_APP_URL="https://todo.sori.studio" \
  -t todo-web .

PWA·HTTPS

홈 화면 추가·서비스 워커 동작은 브라우저마다 다르며, HTTPS를 쓰는 것이 안정적이다. NAS 리버스 프록시에서 TLS를 종료하는 구성을 권장한다.

API 도메인에서 ERR_SSL_VERSION_OR_CIPHER_MISMATCH가 날 때

PocketBase는 자체 TLS 없이 HTTP로 뜨는 경우가 많다. https://api.todo.sori.studio는 프록시가 TLS를 처리해야 한다. 443에 인증서가 없거나, 백엔드를 잘못된 프로토콜/포트로 넘기면 위 오류가 난다. 절차는 docs/nas-deploy-guide.md 11-1을 본다. Cloudflare Tunnel + NPM + SSL Full 조합은 11-2를 본다.