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

spinny:~/writing $ less 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

:Docker 초보자 가이드: 첫 이미지부터 프로덕션 배포까지lines 1-402 (END) — press 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

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```

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

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

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

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

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

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

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

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

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

38## Docker 설치

40```bash

41# macOS

42brew install --cask docker

44# Ubuntu/Debian

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

46sudo usermod -aG docker $USER

48# Verify installation

49docker --version

50docker run hello-world

51```

53## 핵심 개념

55### 이미지

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

59```bash

60# Pull an image from Docker Hub

61docker pull node:20-alpine

63# List local images

64docker images

66# Remove an image

67docker rmi node:20-alpine

68```

70### 컨테이너

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

74```bash

75# Run a container

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

78# List running containers

79docker ps

81# List all containers (including stopped)

82docker ps -a

84# Stop a container

85docker stop my-app

87# Remove a container

88docker rm my-app

90# View logs

91docker logs my-app

93# Execute a command inside a running container

94docker exec -it my-app sh

95```

97## Dockerfile 작성

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