From 1487e9da767bbfbfde4fef39d0b78ad16eecb3c9 Mon Sep 17 00:00:00 2001 From: zenn Date: Thu, 14 May 2026 12:26:10 +0900 Subject: [PATCH] =?UTF-8?q?Docker=20=EB=84=A4=ED=8A=B8=EC=9B=8C=ED=81=AC?= =?UTF-8?q?=20=EC=B6=A9=EB=8F=8C=20=EB=8C=80=EC=9D=91?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .env.example | 1 + docker-compose.yml | 11 +++++++++++ docs/changelog.md | 4 ++++ docs/deploy.md | 20 ++++++++++---------- docs/history.md | 6 ++++++ docs/spec.md | 1 + docs/update.md | 6 ++++++ package-lock.json | 4 ++-- package.json | 2 +- 9 files changed, 42 insertions(+), 13 deletions(-) diff --git a/.env.example b/.env.example index 267238a..b22196f 100644 --- a/.env.example +++ b/.env.example @@ -31,3 +31,4 @@ NUXT_PUBLIC_SITE_TITLE=sori.studio # Server APP_PORT=43118 +DOCKER_SUBNET=10.250.50.0/24 diff --git a/docker-compose.yml b/docker-compose.yml index b05553b..826fe7b 100644 --- a/docker-compose.yml +++ b/docker-compose.yml @@ -12,6 +12,8 @@ services: - ./public/uploads:/app/public/uploads depends_on: - sori-studio-db + networks: + - sori-studio-network restart: unless-stopped sori-studio-db: @@ -28,7 +30,16 @@ services: volumes: - sori-studio-postgres:/var/lib/postgresql/data - ./db/migrations:/docker-entrypoint-initdb.d:ro + networks: + - sori-studio-network restart: unless-stopped volumes: sori-studio-postgres: + +networks: + sori-studio-network: + driver: bridge + ipam: + config: + - subnet: ${DOCKER_SUBNET:-10.250.50.0/24} diff --git a/docs/changelog.md b/docs/changelog.md index d6d8e7c..8c30e97 100644 --- a/docs/changelog.md +++ b/docs/changelog.md @@ -1,5 +1,9 @@ # 업데이트 요약 +## v1.0.1 + +- Docker Compose 네트워크 충돌 대응을 위해 전용 브리지 네트워크와 `DOCKER_SUBNET` 설정 추가. + ## v1.0.0 - 운영 시작 기준 버전. diff --git a/docs/deploy.md b/docs/deploy.md index 20e496a..3e982cc 100644 --- a/docs/deploy.md +++ b/docs/deploy.md @@ -117,7 +117,7 @@ ssh [NAS_IP] ```bash # 프로젝트 디렉토리로 이동 -cd /volume1/docker/sori.studio +cd /volume1/docker/projects/apps/ # 프로젝트 클론 git clone https://git.sori.studio/zenn/sori.studio.git @@ -127,24 +127,23 @@ cd sori.studio # 운영 환경 변수 설정 # .env.production은 Git에 올리지 않는 운영 전용 파일 -cp .env.example .env.production +cp .env.production # .env.production 파일에 운영 DB 연결 정보, 운영 전용 랜덤 비밀번호, APP_PORT=43118 입력 # MEMBER_SESSION_SECRET은 ADMIN_PASSWORD와 다른 긴 난수 문자열로 반드시 입력 +# Docker 네트워크 대역이 NAS 기존 컨테이너와 겹치면 DOCKER_SUBNET을 다른 사설 대역으로 변경 # Docker 내부 앱에서 PostgreSQL에 접근할 때는 sori-studio-db:5432 사용 # Docker 빌드 및 실행 -docker compose --env-file .env.production up -d +docker compose --env-file .env.production up -d --build ``` -### 프로덕션 빌드 (NAS에서) +### Docker 네트워크 충돌 대응 + +NAS에 Docker 컨테이너가 많이 실행 중이면 `could not find an available, non-overlapping IPv4 address pool` 오류가 날 수 있다. 이 프로젝트는 기본 `DOCKER_SUBNET=10.250.50.0/24`를 사용한다. 해당 대역도 NAS 내부망 또는 다른 Docker 네트워크와 겹치면 `.env.production`에서 예를 들어 아래처럼 바꾼 뒤 다시 실행한다. ```bash -# 프로덕션 빌드 -npm run build - -# 또는 Docker로 빌드 -docker build -t sori.studio:latest . -docker run -d -p 3000:3000 sori.studio:latest +DOCKER_SUBNET=10.250.51.0/24 +docker compose --env-file .env.production up -d --build ``` ### 포트 @@ -153,6 +152,7 @@ docker run -d -p 3000:3000 sori.studio:latest - NAS Docker 외부: 43118 - 컨테이너 내부: 3000 - PostgreSQL 외부: 43119 +- Docker 내부 네트워크 기본값: `10.250.50.0/24` - HTTPS: 3001 (SSL 설정 시) --- diff --git a/docs/history.md b/docs/history.md index c38f445..b2f80a2 100644 --- a/docs/history.md +++ b/docs/history.md @@ -1,5 +1,11 @@ # 의사결정 이력 +## 2026-05-14 v1.0.1 + +### Docker Compose 전용 네트워크 대역 명시 + +NAS에서 이미 실행 중인 Docker 서비스가 많으면 Docker가 자동으로 고르는 기본 브리지 네트워크 주소 풀이 기존 네트워크와 겹쳐 Compose 실행이 실패할 수 있다. 기존 네트워크를 정리할 수 없는 운영 환경을 고려해 이 프로젝트 전용 브리지 네트워크와 기본 subnet을 명시하고, 필요 시 `.env.production`의 `DOCKER_SUBNET`으로 다른 사설 대역을 지정할 수 있게 했다. + ## 2026-05-14 v1.0.0 ### 운영 환경의 샘플 콘텐츠 fallback 차단 diff --git a/docs/spec.md b/docs/spec.md index 1a6ea34..8a845d7 100644 --- a/docs/spec.md +++ b/docs/spec.md @@ -199,6 +199,7 @@ components/content/ - 로컬 개발 서버는 개발 DB만 연결 - NAS 배포 환경은 운영 DB만 연결 - 운영 환경(`NODE_ENV=production`)에서는 `DATABASE_URL` 누락 시 샘플 콘텐츠로 대체하지 않고 서버 오류로 즉시 실패 +- Docker Compose는 전용 브리지 네트워크를 사용하며 기본 subnet은 `DOCKER_SUBNET`(`10.250.50.0/24`)으로 관리 - 운영 DB 접속 정보는 로컬 기본 `.env`에 기록하지 않음 - DB 관리 도구는 CloudBeaver 등을 사용할 수 있도록 접속 정보를 환경별로 분리 diff --git a/docs/update.md b/docs/update.md index 372439f..f6ed757 100644 --- a/docs/update.md +++ b/docs/update.md @@ -1,5 +1,11 @@ # 업데이트 이력 +## v1.0.1 + +- Docker Compose 기본 네트워크 주소 풀 충돌을 피하기 위해 전용 브리지 네트워크와 `DOCKER_SUBNET` 설정 추가. +- 배포 문서에 NAS Docker 네트워크 충돌 시 `DOCKER_SUBNET` 변경 기준 추가. +- 패키지 버전 `1.0.1`로 갱신. + ## v1.0.0 - 운영 환경에서 `DATABASE_URL` 누락 시 샘플 콘텐츠 fallback 대신 즉시 실패하도록 수정. diff --git a/package-lock.json b/package-lock.json index 52a9a52..2074680 100644 --- a/package-lock.json +++ b/package-lock.json @@ -1,12 +1,12 @@ { "name": "sori.studio", - "version": "1.0.0", + "version": "1.0.1", "lockfileVersion": 3, "requires": true, "packages": { "": { "name": "sori.studio", - "version": "1.0.0", + "version": "1.0.1", "hasInstallScript": true, "dependencies": { "@nuxtjs/tailwindcss": "^6.14.0", diff --git a/package.json b/package.json index 07e6ff3..affb6ad 100644 --- a/package.json +++ b/package.json @@ -1,6 +1,6 @@ { "name": "sori.studio", - "version": "1.0.0", + "version": "1.0.1", "private": true, "type": "module", "imports": {