From 8a8af275a9859a9b1f6ce86d11af05f77a07815c Mon Sep 17 00:00:00 2001
From: caadiq <caadiq@gmail.com>
Date: Mon, 19 Jan 2026 09:51:26 +0900
Subject: [PATCH] =?UTF-8?q?docs:=20=EC=BB=A8=ED=85=8C=EC=9D=B4=EB=84=88=20?=
 =?UTF-8?q?=EB=B6=84=EB=A6=AC=20=EB=B0=98=EC=98=81=ED=95=98=EC=97=AC=20?=
 =?UTF-8?q?=EA=B0=9C=EB=B0=9C=20=EA=B0=80=EC=9D=B4=EB=93=9C=20=EC=97=85?=
 =?UTF-8?q?=EB=8D=B0=EC=9D=B4=ED=8A=B8?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- 컨테이너 구성 표 추가
- 개별 컨테이너 로그/재시작 명령어 추가
- 배포 모드 Dockerfile 예시 분리
- 네트워크 구조 다이어그램 수정

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
---
 docker-compose.yml  | 38 ++++++++++-----------
 docs/development.md | 83 +++++++++++++++++++++++++++++++++++----------
 2 files changed, 85 insertions(+), 36 deletions(-)

diff --git a/docker-compose.yml b/docker-compose.yml
index 9d977c1..9c5ded3 100644
--- a/docker-compose.yml
+++ b/docker-compose.yml
@@ -1,23 +1,5 @@
 services:
-  backend:
-    build: ./backend
-    container_name: fromis9-backend
-    labels:
-      - "com.centurylinklabs.watchtower.enable=false"
-    env_file:
-      - .env
-    # 개발 모드
-    volumes:
-      - ./backend:/app
-      - backend_modules:/app/node_modules
-    # 배포 모드 (사용 시 위 volumes를 주석처리)
-    # volumes: []
-    networks:
-      - app
-      - db
-    restart: unless-stopped
-
-  frontend:
+  fromis9-frontend:
     build: ./frontend
     container_name: fromis9-frontend
     labels:
@@ -36,6 +18,24 @@ services:
       - app
     restart: unless-stopped
 
+  fromis9-backend:
+    build: ./backend
+    container_name: fromis9-backend
+    labels:
+      - "com.centurylinklabs.watchtower.enable=false"
+    env_file:
+      - .env
+    # 개발 모드
+    volumes:
+      - ./backend:/app
+      - backend_modules:/app/node_modules
+    # 배포 모드 (사용 시 위 volumes를 주석처리)
+    # volumes: []
+    networks:
+      - app
+      - db
+    restart: unless-stopped
+
   meilisearch:
     image: getmeili/meilisearch:v1.6
     container_name: fromis9-meilisearch
diff --git a/docs/development.md b/docs/development.md
index ea97df0..b9c487f 100644
--- a/docs/development.md
+++ b/docs/development.md
@@ -8,44 +8,93 @@ cd /docker/fromis_9
 docker compose up -d --build
 ```
 
-### 구성
-- **Vite** (포트 80): 프론트엔드 개발 서버, HMR 지원
-- **Fastify** (포트 3000): 백엔드 API, --watch 모드
-- Vite가 `/api`, `/docs` 요청을 localhost:3000으로 프록시
+### 컨테이너 구성
+| 컨테이너 | 포트 | 설명 |
+|---------|------|------|
+| `fromis9-frontend` | 80 | Vite 개발 서버, HMR 지원 |
+| `fromis9-backend` | 80 | Fastify API, --watch 모드 |
+| `fromis9-meilisearch` | 7700 | 검색 엔진 |
+| `fromis9-redis` | 6379 | 캐시 |
+
+- Vite가 `/api`, `/docs` 요청을 백엔드로 프록시
 
 ### 로그 확인
 ```bash
+# 전체 로그
+docker compose logs -f
+
+# 백엔드만
+docker compose logs -f fromis9-backend
+
+# 프론트엔드만
 docker compose logs -f fromis9-frontend
 ```
 
 ### 코드 수정
-- `frontend/`, `backend/` 폴더가 볼륨 마운트됨
+- `frontend/`, `backend/` 폴더가 각각 볼륨 마운트됨
 - 코드 수정 시 자동 반영 (HMR, watch)
 
+### 재시작
+```bash
+# 백엔드만 재시작
+docker compose restart fromis9-backend
+
+# 프론트엔드만 재시작
+docker compose restart fromis9-frontend
+
+# 전체 재시작
+docker compose restart
+```
+
 ---
 
 ## 배포 모드 전환
 
 ### 1. Dockerfile 수정
+
+**backend/Dockerfile:**
 ```dockerfile
 # 개발 모드 주석처리
 # FROM node:20-alpine
-# WORKDIR /app
 # ...
 
 # 배포 모드 주석해제
-FROM node:20-alpine AS frontend-builder
-...
+FROM node:20-alpine
+WORKDIR /app
+RUN apk add --no-cache ffmpeg
+COPY package*.json ./
+RUN npm install --production
+COPY . .
+EXPOSE 3000
+CMD ["npm", "start"]
+```
+
+**frontend/Dockerfile:**
+```dockerfile
+# 개발 모드 주석처리
+# FROM node:20-alpine
+# ...
+
+# 배포 모드 주석해제
+FROM node:20-alpine AS builder
+WORKDIR /app
+COPY package*.json ./
+RUN npm install
+COPY . .
+RUN npm run build
+
+FROM nginx:alpine
+COPY --from=builder /app/dist /usr/share/nginx/html
+EXPOSE 80
+CMD ["nginx", "-g", "daemon off;"]
 ```
 
 ### 2. docker-compose.yml 수정
 ```yaml
 # volumes 주석처리
 # volumes:
-#   - ./backend:/app/backend
-#   - ./frontend:/app/frontend
-#   - backend_modules:/app/backend/node_modules
-#   - frontend_modules:/app/frontend/node_modules
+#   - ./frontend:/app
+#   - frontend_modules:/app/node_modules
 ```
 
 ### 3. 빌드 및 실행
@@ -115,9 +164,9 @@ docker exec caddy caddy reload --config /etc/caddy/Caddyfile
 
 ### 네트워크 구조
 ```
-인터넷 → Caddy (:443) → fromis9-frontend (:80) → Fastify (:3000)
-                                              ↓
-                            MariaDB, Redis, Meilisearch (내부 네트워크)
+인터넷 → Caddy (:443) → fromis9-frontend (:80) → fromis9-backend (:80)
+                                               ↓
+                         MariaDB, Redis, Meilisearch (내부 네트워크)
 ```
 
 ---
@@ -125,8 +174,8 @@ docker exec caddy caddy reload --config /etc/caddy/Caddyfile
 ## 유용한 명령어
 
 ```bash
-# 컨테이너 재시작
-docker compose restart fromis9-frontend
+# 컨테이너 상태 확인
+docker compose ps
 
 # 볼륨 포함 완전 재시작
 docker compose down -v && docker compose up -d --build