Docker 초보자 가이드: 첫 이미지부터 프로덕션 배포까지

spinny:~/writing $ vim docker-containers-complete-guide.md

1~
2Docker는 우리가 소프트웨어를 구축, 배포, 실행하는 방식을 바꿔놓았습니다. "내 컴퓨터에서는 작동해"가 아니라, Docker는 여러분의 애플리케이션이 어디서든 동일하게 실행되도록 보장합니다 - 노트북에서, 동료의 컴퓨터에서, CI/CD에서, 그리고 프로덕션에서. 이 가이드에서는 처음부터 실제 애플리케이션 배포까지 다루겠습니다.
3~
4## Docker란?
5~
6Docker는 애플리케이션과 모든 종속성을 **컨테이너**라는 표준화된 단위로 패키징하는 플랫폼입니다. 컨테이너는 호스트 OS 커널을 공유하면서도 자체 파일시스템, 네트워크, 프로세스 공간을 가진 격리된 경량 프로세스입니다.
7~
8```mermaid
9graph TD
10    subgraph "Traditional Deployment"
11        A1[App 1] --> OS1[Guest OS]
12        A2[App 2] --> OS2[Guest OS]
13        OS1 --> HV[Hypervisor]
14        OS2 --> HV
15        HV --> HW1[Hardware]
16    end
17~
18    subgraph "Docker Deployment"
19        B1[App 1] --> D1[Container]
20        B2[App 2] --> D2[Container]
21        D1 --> DE[Docker Engine]
22        D2 --> DE
23        DE --> HW2[Hardware]
24    end
25```
26~
27### 컨테이너 vs 가상 머신
28~
29| 항목 | 컨테이너 | 가상 머신 |
30|------|----------|----------|
31| **시작** | 초 단위 | 분 단위 |
32| **크기** | MB 단위 | GB 단위 |
33| **OS** | 호스트 커널 공유 | 전체 게스트 OS |
34| **격리** | 프로세스 수준 | 하드웨어 수준 |
35| **성능** | 거의 네이티브 | 하이퍼바이저 오버헤드 |
36| **밀도** | 호스트당 수백 개 | 호스트당 수십 개 |
37~
38## Docker 설치
39~
40```bash
41# macOS
42brew install --cask docker
43~
44# Ubuntu/Debian
45curl -fsSL https://get.docker.com | sh
46sudo usermod -aG docker $USER
47~
48# Verify installation
49docker --version
50docker run hello-world
51```
52~
53## 핵심 개념
54~
55### 이미지
56~
57이미지는 컨테이너를 생성하기 위한 명령이 담긴 읽기 전용 템플릿입니다. 애플리케이션과 환경의 스냅샷이라고 생각하세요.
58~
59```bash
60# Pull an image from Docker Hub
61docker pull node:20-alpine
62~
63# List local images
64docker images
65~
66# Remove an image
67docker rmi node:20-alpine
68```
69~
70### 컨테이너
71~
72컨테이너는 이미지의 실행 중인 인스턴스입니다. 컨테이너를 생성, 시작, 중지, 삭제할 수 있습니다.
73~
74```bash
75# Run a container
76docker run -d --name my-app -p 3000:3000 node:20-alpine
77~
78# List running containers
79docker ps
80~
81# List all containers (including stopped)
82docker ps -a
83~
84# Stop a container
85docker stop my-app
86~
87# Remove a container
88docker rm my-app
89~
90# View logs
91docker logs my-app
92~
93# Execute a command inside a running container
94docker exec -it my-app sh
95```
96~
97## Dockerfile 작성
98~
99Dockerfile은 이미지를 빌드하기 위한 명령이 담긴 텍스트 파일입니다. 각 명령은 하나의 레이어를 생성합니다.
100~
101### Node.js 앱을 위한 기본 Dockerfile
102~
103```dockerfile
104# Use an official Node.js runtime as base image
105FROM node:20-alpine
106~
107# Set working directory
108WORKDIR /app
109~
110# Copy package files first (better caching)
111COPY package.json package-lock.json ./
112~
113# Install dependencies
114RUN npm ci --only=production
115~
116# Copy application code
117COPY . .
118~
119# Expose the port the app runs on
120EXPOSE 3000
121~
122# Command to run the application
123CMD ["node", "server.js"]
124```
125~
126### 빌드 및 실행
127~
128```bash
129# Build the image
130docker build -t my-node-app .
131~
132# Run the container
133docker run -d -p 3000:3000 my-node-app
134~
135# Visit http://localhost:3000
136```
137~
138## 멀티 스테이지 빌드
139~
140멀티 스테이지 빌드는 빌드 환경을 런타임에서 분리하여 프로덕션 이미지를 작게 유지합니다.
141~
142```dockerfile
143# Stage 1: Build
144FROM node:20-alpine AS builder
145WORKDIR /app
146COPY package.json package-lock.json ./
147RUN npm ci
148COPY . .
149RUN npm run build
150~
151# Stage 2: Production
152FROM node:20-alpine AS runner
153WORKDIR /app
154COPY --from=builder /app/dist ./dist
155COPY --from=builder /app/node_modules ./node_modules
156COPY --from=builder /app/package.json ./
157EXPOSE 3000
158CMD ["node", "dist/server.js"]
159```
160~
161이렇게 하면 컴파일된 출력과 프로덕션 종속성만 포함된 이미지가 생성됩니다 - 소스 코드 없이, 개발 종속성 없이, 빌드 도구 없이.
162~
163### Next.js 멀티 스테이지 예제
164~
165```dockerfile
166FROM node:20-alpine AS deps
167WORKDIR /app
168COPY package.json package-lock.json ./
169RUN npm ci
170~
171FROM node:20-alpine AS builder
172WORKDIR /app
173COPY --from=deps /app/node_modules ./node_modules
174COPY . .
175RUN npm run build
176~
177FROM node:20-alpine AS runner
178WORKDIR /app
179ENV NODE_ENV=production
180COPY --from=builder /app/public ./public
181COPY --from=builder /app/.next/standalone ./
182COPY --from=builder /app/.next/static ./.next/static
183EXPOSE 3000
184CMD ["node", "server.js"]
185```
186~
187## 볼륨: 영구 데이터
188~
189기본적으로 컨테이너 내부의 데이터는 컨테이너가 제거되면 사라집니다. 볼륨이 이 문제를 해결합니다.
190~
191```bash
192# Create a named volume
193docker volume create my-data
194~
195# Run with a volume
196docker run -d -v my-data:/app/data my-app
197~
198# Bind mount (map host directory to container)
199docker run -d -v $(pwd)/data:/app/data my-app
200~
201# List volumes
202docker volume ls
203```
204~
205## 네트워킹
206~
207Docker는 컨테이너가 통신할 수 있도록 격리된 네트워크를 생성합니다.
208~
209```bash
210# Create a custom network
211docker network create my-network
212~
213# Run containers on the same network
214docker run -d --name api --network my-network my-api
215docker run -d --name db --network my-network postgres:16
216~
217# Containers can reach each other by name
218# From "api" container: postgres://db:5432
219```
220~
221```mermaid
222graph LR
223    subgraph "my-network"
224        API[api container\nport 3000] -- "db:5432" --> DB[db container\nport 5432]
225    end
226    User -- "localhost:3000" --> API
227```
228~
229## Docker Compose
230~
231Docker Compose를 사용하면 단일 YAML 파일로 멀티 컨테이너 애플리케이션을 정의하고 실행할 수 있습니다.
232~
233### docker-compose.yml
234~
235```yaml
236services:
237  api:
238    build: ./api
239    ports:
240      - "3000:3000"
241    environment:
242      - DATABASE_URL=postgres://user:pass@db:5432/mydb
243    depends_on:
244      - db
245~
246  db:
247    image: postgres:16-alpine
248    environment:
249      - POSTGRES_USER=user
250      - POSTGRES_PASSWORD=pass
251      - POSTGRES_DB=mydb
252    volumes:
253      - pgdata:/var/lib/postgresql/data
254    ports:
255      - "5432:5432"
256~
257  redis:
258    image: redis:7-alpine
259    ports:
260      - "6379:6379"
261~
262volumes:
263  pgdata:
264```
265~
266### 명령어
267~
268```bash
269# Start all services
270docker compose up -d
271~
272# View logs
273docker compose logs -f
274~
275# Stop all services
276docker compose down
277~
278# Rebuild and restart
279docker compose up -d --build
280~
281# Scale a service
282docker compose up -d --scale api=3
283```
284~
285## .dockerignore
286~
287`.gitignore`와 마찬가지로, 이 파일은 불필요한 파일이 이미지에 복사되는 것을 방지합니다.
288~
289```plaintext
290node_modules
291.git
292.env
293*.md
294.next
295dist
296coverage
297```
298~
299## 프로덕션 모범 사례
300~
301### 1. 작은 베이스 이미지 사용
302~
303```dockerfile
304# Bad: 1GB+
305FROM node:20
306~
307# Good: ~180MB
308FROM node:20-alpine
309```
310~
311### 2. Root로 실행하지 않기
312~
313```dockerfile
314FROM node:20-alpine
315RUN addgroup -S app && adduser -S app -G app
316USER app
317WORKDIR /home/app
318COPY --chown=app:app . .
319```
320~
321### 3. 특정 이미지 태그 사용
322~
323```dockerfile
324# Bad: can change unexpectedly
325FROM node:latest
326~
327# Good: pinned version
328FROM node:20.11-alpine3.19
329```
330~
331### 4. 빌드 캐시 활용
332~
333Dockerfile 명령을 변경 빈도가 낮은 것부터 높은 것 순으로 정렬하세요:
334~
335```dockerfile
336FROM node:20-alpine
337WORKDIR /app
338~
339# These change rarely - cached
340COPY package.json package-lock.json ./
341RUN npm ci --only=production
342~
343# This changes often - not cached
344COPY . .
345```
346~
347### 5. 헬스 체크
348~
349```dockerfile
350HEALTHCHECK --interval=30s --timeout=3s --retries=3 \
351  CMD wget -qO- http://localhost:3000/health || exit 1
352```
353~
354### 6. 환경 변수 사용
355~
356```dockerfile
357ENV NODE_ENV=production
358ENV PORT=3000
359```
360~
361## 자주 사용하는 Docker 명령어 치트 시트
362~
363```bash
364# Images
365docker build -t name:tag .        # Build image
366docker images                      # List images
367docker rmi image_name              # Remove image
368docker image prune                 # Remove unused images
369~
370# Containers
371docker run -d -p 3000:3000 image   # Run detached
372docker ps                          # List running
373docker stop container_name         # Stop
374docker rm container_name           # Remove
375docker logs -f container_name      # Follow logs
376docker exec -it container sh       # Shell into container
377~
378# Compose
379docker compose up -d               # Start services
380docker compose down                # Stop services
381docker compose logs -f             # Follow all logs
382docker compose ps                  # List services
383~
384# Cleanup
385docker system prune -a             # Remove everything unused
386```
387~
388## Docker에서 Kubernetes로
389~
390Docker는 개별 컨테이너를 관리합니다. 여러 서버에 걸쳐 수백 개의 컨테이너를 오케스트레이션해야 할 때 Kubernetes가 필요합니다. Docker와 Kubernetes는 상호 보완적입니다:
391~
3921. **Docker**: 컨테이너를 빌드하고 실행
3932. **Kubernetes**: 대규모로 컨테이너를 오케스트레이션 (스케줄링, 스케일링, 자가 복구)
394~
395다음 단계에 관심이 있다면, Kubernetes 소개에 대한 제 글을 확인해보세요.
396~
397## 결론
398~
399Docker는 현대 개발자에게 필수적인 기술입니다. 환경 불일치를 제거하고, 배포를 단순화하며, Kubernetes를 통한 컨테이너 오케스트레이션의 기반입니다. 간단한 Dockerfile로 시작하여, 멀티 서비스 앱에는 Docker Compose로 이동하고, 성장하면서 멀티 스테이지 빌드와 보안 모범 사례를 도입하세요.
400~
401Docker를 배우는 가장 좋은 방법은 이미 작업 중인 프로젝트를 컨테이너화하는 것입니다. 오늘 시작하세요.
402~

NORMAL · docker-containers-complete-guide.md [readonly]402 lines · :q to close

2Docker는 우리가 소프트웨어를 구축, 배포, 실행하는 방식을 바꿔놓았습니다. "내 컴퓨터에서는 작동해"가 아니라, Docker는 여러분의 애플리케이션이 어디서든 동일하게 실행되도록 보장합니다 - 노트북에서, 동료의 컴퓨터에서, CI/CD에서, 그리고 프로덕션에서. 이 가이드에서는 처음부터 실제 애플리케이션 배포까지 다루겠습니다.

4## Docker란?

6Docker는 애플리케이션과 모든 종속성을 **컨테이너**라는 표준화된 단위로 패키징하는 플랫폼입니다. 컨테이너는 호스트 OS 커널을 공유하면서도 자체 파일시스템, 네트워크, 프로세스 공간을 가진 격리된 경량 프로세스입니다.

8```mermaid

9graph TD

10 subgraph "Traditional Deployment"

11 A1[App 1] --> OS1[Guest OS]

12 A2[App 2] --> OS2[Guest OS]

13 OS1 --> HV[Hypervisor]

14 OS2 --> HV

15 HV --> HW1[Hardware]

16 end

17~

18 subgraph "Docker Deployment"

19 B1[App 1] --> D1[Container]

20 B2[App 2] --> D2[Container]

21 D1 --> DE[Docker Engine]

22 D2 --> DE

23 DE --> HW2[Hardware]

24 end

25```

26~

27### 컨테이너 vs 가상 머신

28~

29| 항목 | 컨테이너 | 가상 머신 |

30|------|----------|----------|

31| **시작** | 초 단위 | 분 단위 |

32| **크기** | MB 단위 | GB 단위 |

33| **OS** | 호스트 커널 공유 | 전체 게스트 OS |

34| **격리** | 프로세스 수준 | 하드웨어 수준 |

35| **성능** | 거의 네이티브 | 하이퍼바이저 오버헤드 |

36| **밀도** | 호스트당 수백 개 | 호스트당 수십 개 |

37~

38## Docker 설치

39~

40```bash

41# macOS

42brew install --cask docker

43~

44# Ubuntu/Debian

45curl -fsSL https://get.docker.com | sh

46sudo usermod -aG docker $USER

47~

48# Verify installation

49docker --version

50docker run hello-world

51```

52~

53## 핵심 개념

54~

55### 이미지

56~

57이미지는 컨테이너를 생성하기 위한 명령이 담긴 읽기 전용 템플릿입니다. 애플리케이션과 환경의 스냅샷이라고 생각하세요.

58~

59```bash

60# Pull an image from Docker Hub

61docker pull node:20-alpine

62~

63# List local images

64docker images

65~

66# Remove an image

67docker rmi node:20-alpine

68```

69~

70### 컨테이너

71~

72컨테이너는 이미지의 실행 중인 인스턴스입니다. 컨테이너를 생성, 시작, 중지, 삭제할 수 있습니다.

73~

74```bash

75# Run a container

76docker run -d --name my-app -p 3000:3000 node:20-alpine

77~

78# List running containers

79docker ps

80~

81# List all containers (including stopped)

82docker ps -a

83~

84# Stop a container

85docker stop my-app

86~

87# Remove a container

88docker rm my-app

89~

90# View logs

91docker logs my-app

92~

93# Execute a command inside a running container

94docker exec -it my-app sh

95```

96~

97## Dockerfile 작성

98~

99Dockerfile은 이미지를 빌드하기 위한 명령이 담긴 텍스트 파일입니다. 각 명령은 하나의 레이어를 생성합니다.

100~

101### Node.js 앱을 위한 기본 Dockerfile

102~

103```dockerfile

104# Use an official Node.js runtime as base image

105FROM node:20-alpine

106~

107# Set working directory

108WORKDIR /app

109~

110# Copy package files first (better caching)

111COPY package.json package-lock.json ./

112~

113# Install dependencies

114RUN npm ci --only=production

115~

116# Copy application code

117COPY . .

118~

119# Expose the port the app runs on

120EXPOSE 3000

121~

122# Command to run the application

123CMD ["node", "server.js"]

124```

125~

126### 빌드 및 실행

127~

128```bash

129# Build the image

130docker build -t my-node-app .

131~

132# Run the container

133docker run -d -p 3000:3000 my-node-app

134~

135# Visit http://localhost:3000

136```

137~

138## 멀티 스테이지 빌드

139~

140멀티 스테이지 빌드는 빌드 환경을 런타임에서 분리하여 프로덕션 이미지를 작게 유지합니다.

141~

142```dockerfile

143# Stage 1: Build

144FROM node:20-alpine AS builder

145WORKDIR /app

146COPY package.json package-lock.json ./

147RUN npm ci

148COPY . .

149RUN npm run build

150~

151# Stage 2: Production

152FROM node:20-alpine AS runner

153WORKDIR /app

154COPY --from=builder /app/dist ./dist

155COPY --from=builder /app/node_modules ./node_modules

156COPY --from=builder /app/package.json ./

157EXPOSE 3000

158CMD ["node", "dist/server.js"]

159```

160~

161이렇게 하면 컴파일된 출력과 프로덕션 종속성만 포함된 이미지가 생성됩니다 - 소스 코드 없이, 개발 종속성 없이, 빌드 도구 없이.

162~

163### Next.js 멀티 스테이지 예제

164~

165```dockerfile

166FROM node:20-alpine AS deps

167WORKDIR /app

168COPY package.json package-lock.json ./

169RUN npm ci

170~

171FROM node:20-alpine AS builder

172WORKDIR /app

173COPY --from=deps /app/node_modules ./node_modules

174COPY . .

175RUN npm run build

176~

177FROM node:20-alpine AS runner

178WORKDIR /app

179ENV NODE_ENV=production

180COPY --from=builder /app/public ./public

181COPY --from=builder /app/.next/standalone ./

182COPY --from=builder /app/.next/static ./.next/static

183EXPOSE 3000

184CMD ["node", "server.js"]

185```

186~

187## 볼륨: 영구 데이터

188~

189기본적으로 컨테이너 내부의 데이터는 컨테이너가 제거되면 사라집니다. 볼륨이 이 문제를 해결합니다.

190~

191```bash

192# Create a named volume

193docker volume create my-data

194~

195# Run with a volume

196docker run -d -v my-data:/app/data my-app

197~

198# Bind mount (map host directory to container)

199docker run -d -v $(pwd)/data:/app/data my-app

200~

201# List volumes

202docker volume ls

203```

204~

205## 네트워킹

206~

207Docker는 컨테이너가 통신할 수 있도록 격리된 네트워크를 생성합니다.

208~

209```bash

210# Create a custom network

211docker network create my-network

212~

213# Run containers on the same network

214docker run -d --name api --network my-network my-api

215docker run -d --name db --network my-network postgres:16

216~

217# Containers can reach each other by name

218# From "api" container: postgres://db:5432

219```

220~

221```mermaid

222graph LR

223 subgraph "my-network"

224 API[api container\nport 3000] -- "db:5432" --> DB[db container\nport 5432]

225 end

226 User -- "localhost:3000" --> API

227```

228~

229## Docker Compose

230~

231Docker Compose를 사용하면 단일 YAML 파일로 멀티 컨테이너 애플리케이션을 정의하고 실행할 수 있습니다.

232~

233### docker-compose.yml

234~

235```yaml

236services:

237 api:

238 build: ./api

239 ports:

240 - "3000:3000"

241 environment:

242 - DATABASE_URL=postgres://user:pass@db:5432/mydb

243 depends_on:

244 - db

245~

246 db:

247 image: postgres:16-alpine

248 environment:

249 - POSTGRES_USER=user

250 - POSTGRES_PASSWORD=pass

251 - POSTGRES_DB=mydb

252 volumes:

253 - pgdata:/var/lib/postgresql/data

254 ports:

255 - "5432:5432"

256~

257 redis:

258 image: redis:7-alpine

259 ports:

260 - "6379:6379"

261~

262volumes:

263 pgdata:

264```

265~

266### 명령어

267~

268```bash

269# Start all services

270docker compose up -d

271~

272# View logs

273docker compose logs -f

274~

275# Stop all services

276docker compose down

277~

278# Rebuild and restart

279docker compose up -d --build

280~

281# Scale a service

282docker compose up -d --scale api=3

283```

284~

285## .dockerignore

286~

287`.gitignore`와 마찬가지로, 이 파일은 불필요한 파일이 이미지에 복사되는 것을 방지합니다.

288~

289```plaintext

290node_modules

291.git

292.env

293*.md

294.next

295dist

296coverage

297```

298~

299## 프로덕션 모범 사례

300~

301### 1. 작은 베이스 이미지 사용

302~

303```dockerfile

304# Bad: 1GB+

305FROM node:20

306~

307# Good: ~180MB

308FROM node:20-alpine

309```

310~

311### 2. Root로 실행하지 않기

312~

313```dockerfile

314FROM node:20-alpine

315RUN addgroup -S app && adduser -S app -G app

316USER app

317WORKDIR /home/app

318COPY --chown=app:app . .

319```

320~

321### 3. 특정 이미지 태그 사용

322~

323```dockerfile

324# Bad: can change unexpectedly

325FROM node:latest

326~

327# Good: pinned version

328FROM node:20.11-alpine3.19

329```

330~

331### 4. 빌드 캐시 활용

332~

333Dockerfile 명령을 변경 빈도가 낮은 것부터 높은 것 순으로 정렬하세요:

334~

335```dockerfile

336FROM node:20-alpine

337WORKDIR /app

338~

339# These change rarely - cached

340COPY package.json package-lock.json ./

341RUN npm ci --only=production

342~

343# This changes often - not cached

344COPY . .

345```

346~

347### 5. 헬스 체크

348~

349```dockerfile

350HEALTHCHECK --interval=30s --timeout=3s --retries=3 \

351 CMD wget -qO- http://localhost:3000/health || exit 1

352```

353~

354### 6. 환경 변수 사용

355~

356```dockerfile

357ENV NODE_ENV=production

358ENV PORT=3000

359```

360~

361## 자주 사용하는 Docker 명령어 치트 시트

362~

363```bash

364# Images

365docker build -t name:tag . # Build image

366docker images # List images

367docker rmi image_name # Remove image

368docker image prune # Remove unused images

369~

370# Containers

371docker run -d -p 3000:3000 image # Run detached

372docker ps # List running

373docker stop container_name # Stop

374docker rm container_name # Remove

375docker logs -f container_name # Follow logs

376docker exec -it container sh # Shell into container

377~

378# Compose

379docker compose up -d # Start services

380docker compose down # Stop services

381docker compose logs -f # Follow all logs

382docker compose ps # List services

383~

384# Cleanup

385docker system prune -a # Remove everything unused

386```

387~

388## Docker에서 Kubernetes로

389~

390Docker는 개별 컨테이너를 관리합니다. 여러 서버에 걸쳐 수백 개의 컨테이너를 오케스트레이션해야 할 때 Kubernetes가 필요합니다. Docker와 Kubernetes는 상호 보완적입니다:

391~

3921. **Docker**: 컨테이너를 빌드하고 실행

3932. **Kubernetes**: 대규모로 컨테이너를 오케스트레이션 (스케줄링, 스케일링, 자가 복구)

394~

395다음 단계에 관심이 있다면, Kubernetes 소개에 대한 제 글을 확인해보세요.

396~

397## 결론

398~

399Docker는 현대 개발자에게 필수적인 기술입니다. 환경 불일치를 제거하고, 배포를 단순화하며, Kubernetes를 통한 컨테이너 오케스트레이션의 기반입니다. 간단한 Dockerfile로 시작하여, 멀티 서비스 앱에는 Docker Compose로 이동하고, 성장하면서 멀티 스테이지 빌드와 보안 모범 사례를 도입하세요.

400~

401Docker를 배우는 가장 좋은 방법은 이미 작업 중인 프로젝트를 컨테이너화하는 것입니다. 오늘 시작하세요.

402~