diff --git a/.cline-context.md b/.cline-context.md index c9e7d3e..0f898b5 100644 --- a/.cline-context.md +++ b/.cline-context.md @@ -26,9 +26,9 @@ - Added localized i18n strings for Export across English, Korean, and Japanese. - Configured production multi-stage `Dockerfile` with standalone Next.js runner, Prisma CLI migrations support, and automated `docker-entrypoint.sh` startup script. - Added `.dockerignore` for minimal context transfer and fast build times. - - Refined `docker-compose.yml` and `.env.example` to support prebuilt registry images (`CHECKFLOW_IMAGE`) and automated database migrations. + - Refined `docker-compose.yml` and `.env.example` to support prebuilt registry images (`CHECKFLOW_IMAGE`), Watchtower auto-updating labels, and automated database migrations. - Automated Gitea Actions CI workflow (`.gitea/workflows/docker-build.yaml`) for building & pushing container images to Gitea Container Registry with lowercase repository name normalization (`env.REPO`) and OCI source labels (`org.opencontainers.image.source`) for automatic repository package linkage. - - Completely revamped `README.md` to reflect project design philosophy, architecture, Docker setup, and open-standard CalDAV sync guidelines. + - Completely revamped `README.md` to reflect project design philosophy, architecture, Docker setup, Watchtower auto-update, and open-standard CalDAV sync guidelines. - Validated that `npm run lint` and `npm run build` execute with 0 errors and 0 warnings. - **Next Steps (Todo):** diff --git a/.env.example b/.env.example index ccd331f..09c79a1 100644 --- a/.env.example +++ b/.env.example @@ -1,14 +1,19 @@ -# Database password (change in production!) +# ============================================================================== +# CheckFlow — Environment Variables Configuration +# ============================================================================== + +# [필수] PostgreSQL 데이터베이스 접속 비밀번호 (프로덕션 환경에서는 안전한 난수로 변경) POSTGRES_PASSWORD=changeme -# App URL (set to your domain or server IP) +# [필수] 웹 서비스 외부 접속 기본 URL (리버스 프록시/도메인 또는 IP 및 포트) NEXTAUTH_URL=http://localhost:3000 -# Auth secret — generate with: openssl rand -base64 32 -NEXTAUTH_SECRET=change-this-to-a-random-string +# [필수] NextAuth 세션 암호화 키 — 생성 명령: openssl rand -base64 32 +NEXTAUTH_SECRET=change-this-to-a-secure-random-secret -# Port to expose (default 3000) +# [선택] 호스트 머신에 노출할 포트 번호 (기본값: 3000) PORT=3000 -# Container Registry Image (Optional, default: checkflow:latest) -# CHECKFLOW_IMAGE=gitea.example.com/username/checkflow:latest +# [선택/배포] Gitea 또는 Docker 레지스트리 컨테이너 이미지 주소 (Watchtower 자동 갱신 지원) +# 예: CHECKFLOW_IMAGE=git.yourdomain.com/neru_han/checkflow:latest +CHECKFLOW_IMAGE=git.yourdomain.com/neru_han/checkflow:latest diff --git a/README.md b/README.md index 0a9e254..b5311c0 100644 --- a/README.md +++ b/README.md @@ -72,7 +72,7 @@ ## 🚀 빠른 시작 (Docker 배포) -CheckFlow는 프로덕션 컨테이너 이미지와 자동 데이터베이스 마이그레이션을 지원하여 `docker compose` 명령 하나로 즉시 구동됩니다. +CheckFlow는 빌드된 레지스트리 이미지와 자동 데이터베이스 마이그레이션 진입점(`docker-entrypoint.sh`)을 지원하여 `docker compose` 명령 하나로 즉시 배포 및 구동됩니다. ### 1. 환경 변수 구성 `.env.example` 파일을 복사하여 환경 변수를 설정합니다: @@ -81,13 +81,13 @@ CheckFlow는 프로덕션 컨테이너 이미지와 자동 데이터베이스 cp .env.example .env ``` -`.env` 파일 예시: +`.env` 파일 설정: ```env # 데이터베이스 비밀번호 (프로덕션 환경에서는 안전한 비밀번호로 변경하세요) POSTGRES_PASSWORD=your_secure_password # 서비스 도메인 또는 접근 IP -NEXTAUTH_URL=http://localhost:3000 +NEXTAUTH_URL=https://todo.yourdomain.com # NextAuth 인증 시크릿 키 (openssl rand -base64 32 등으로 생성) NEXTAUTH_SECRET=your_generated_random_secret_string @@ -95,17 +95,34 @@ NEXTAUTH_SECRET=your_generated_random_secret_string # 외부 노출 포트 (기본값: 3000) PORT=3000 -# (선택사항) 커스텀 레지스트리 이미지를 사용할 경우 -# CHECKFLOW_IMAGE=gitea.example.com/username/checkflow:latest +# Gitea / Docker 컨테이너 레지스트리 이미지 주소 +CHECKFLOW_IMAGE=git.yourdomain.com/neru_han/checkflow:latest ``` -### 2. 컨테이너 실행 +### 2. 최신 이미지 가져오기 및 컨테이너 실행 ```bash +# 최신 배포 이미지 다운로드 +docker compose pull + +# 백그라운드 컨테이너 실행 docker compose up -d ``` -> 💡 컨테이너가 실행될 때 `docker-entrypoint.sh`가 PostgreSQL 헬스체크 후 **Prisma 스키마 마이그레이션을 자동으로 수행**하므로 별도의 수동 DB 설정 명령이 필요하지 않습니다. +> 💡 **자동 DB 마이그레이션**: 컨테이너 구동 시 `docker-entrypoint.sh`가 PostgreSQL 헬스체크를 확인한 후 `prisma migrate deploy`를 자동 실행하므로 수동 DB 마이그레이션 절차가 필요하지 않습니다. -브라우저에서 `http://localhost:3000`에 접속하여 첫 관리자/사용자 계정을 생성하세요. +### 🔄 Watchtower 기반 자동 갱신 권장 +`docker-compose.yml`의 `app` 서비스에는 `com.centurylinklabs.watchtower.enable=true` 라벨이 포함되어 있습니다. +Gitea Actions CI 파이프라인에서 새 이미지가 푸시되면 Watchtower가 이를 감지하여 무중단에 가깝게 컨테이너를 최신 버전으로 자동 갱신할 수 있습니다: + +```bash +# Watchtower를 실행 중인 경우 자동 감지 (또는 원클릭 업데이트 지원) +docker run -d \ + --name watchtower \ + --restart unless-stopped \ + -v /var/run/docker.sock:/var/run/docker.sock \ + containrrr/watchtower --interval 300 --cleanup --label-enable +``` + +브라우저에서 설정한 도메인(또는 `http://localhost:3000`)에 접속하여 첫 관리자 계정을 등록하고 사용을 시작하세요. --- diff --git a/docker-compose.yml b/docker-compose.yml index 3208bf8..e98f3b2 100644 --- a/docker-compose.yml +++ b/docker-compose.yml @@ -19,9 +19,10 @@ services: app: image: ${CHECKFLOW_IMAGE:-checkflow:latest} - build: - context: . - dockerfile: Dockerfile + # 로컬 소스코드로 직접 빌드하여 실행하려면 아래 build 블록의 주석을 해제하세요: + # build: + # context: . + # dockerfile: Dockerfile container_name: checkflow-app restart: unless-stopped depends_on: @@ -34,6 +35,8 @@ services: NEXTAUTH_URL: ${NEXTAUTH_URL:-http://localhost:3000} NEXTAUTH_SECRET: ${NEXTAUTH_SECRET:-change-this-secret-in-production} NODE_ENV: production + labels: + - "com.centurylinklabs.watchtower.enable=true" volumes: - ./prisma:/app/prisma