Docker Compose Nginx Node.js PostgreSQL 로컬 개발 환경 구축: 실전 가이드

튜토리얼

Docker Compose Nginx Node.js PostgreSQL 로컬 개발 환경 구축: 실전 가이드

강코의 코딩 일기 2026. 6. 25. 07:05

Docker Compose를 활용하여 Nginx, Node.js, PostgreSQL 기반의 안정적이고 효율적인 로컬 개발 환경을 구축하는 실전 가이드입니다. 각 컴포넌트의 역할과 설정 방법을 상세히 다룹니다.

복잡한 개발 환경 설정에 지치셨나요? 백엔드, 프론트엔드, 데이터베이스 등 여러 서비스가 얽혀 있는 프로젝트를 시작할 때마다 환경 설정에 귀한 시간을 낭비하고 계신가요? 이러한 문제점은 개발자의 생산성을 저해하고 프로젝트 시작을 더디게 만드는 주요 원인 중 하나입니다. 특히 Nginx, Node.js, PostgreSQL과 같이 다양한 기술 스택을 사용하는 프로젝트에서는 각 컴포넌트의 버전 관리와 의존성 해결이 더욱 까다로워집니다.

이 글에서는 Docker Compose를 활용하여 이러한 복잡성을 해소하고, 일관되고 재현 가능한 로컬 개발 환경을 구축하는 실전 가이드를 제공합니다. 각 서비스의 역할과 설정 방법을 심층적으로 분석하고, 단계별로 따라 할 수 있는 구체적인 예시를 통해 여러분의 개발 워크플로우를 혁신할 수 있도록 돕겠습니다.

📑 목차

1. 왜 Docker Compose로 개발 환경을 구축해야 하는가?
2. Docker Compose의 이해와 필요성
2.1. Docker와 Docker Compose의 차이점
2.2. Docker Compose의 핵심 장점
3. Nginx, Node.js, PostgreSQL 스택 선택의 배경
4. Docker Compose 파일(docker-compose.yml) 심층 분석 및 작성
4.1. 프로젝트 디렉토리 구조
4.2. docker-compose.yml 파일 작성
5. 로컬 개발 환경 구축 실전 가이드: 단계별 진행
5.1. 사전 준비
5.2. 프로젝트 디렉토리 및 파일 생성
5.3. Nginx 설정 (nginx/default.conf)
5.4. Node.js 애플리케이션 설정 (nodejs-app/)
5.5. Docker Compose 파일 최종 확인
5.6. 개발 환경 실행
5.7. 서비스 접속 및 테스트
6. 구축된 환경 활용 및 트러블슈팅 팁
6.1. 개발 환경 관리 명령어
6.2. 일반적인 트러블슈팅 시나리오
7. 결론: Docker Compose를 통한 개발 생산성 향상

Docker Compose를 활용한 Nginx, Node.js, PostgreSQL 기반 로컬 개발 환경 구축 실전 가이드 - belgium, antwerp, shipping, container, freight, cargo, transport, harbor, container, container, container, freight, cargo, cargo, cargo, cargo, cargo

Image by 2427999 on Pixabay

1. 왜 Docker Compose로 개발 환경을 구축해야 하는가?

개발 프로젝트는 일반적으로 여러 서비스의 조합으로 이루어집니다. 웹 서버, 애플리케이션 서버, 데이터베이스, 캐시 서버 등 다양한 구성 요소들이 서로 통신하며 하나의 시스템을 이룹니다. 이러한 다중 서비스 환경을 로컬 개발 환경에 직접 구축하는 것은 여러 문제점을 야기할 수 있습니다.

환경 불일치: 개발자마다 다른 운영체제나 라이브러리 버전을 사용하면 '내 컴퓨터에서는 되는데...'라는 문제가 발생하기 쉽습니다.
복잡한 설정: 각 서비스의 설치, 설정, 의존성 관리가 복잡하고 시간이 많이 소요됩니다.
자원 충돌: 여러 프로젝트를 동시에 진행할 때 포트 충돌이나 라이브러리 버전 충돌이 발생할 수 있습니다.
온보딩의 어려움: 새로운 팀원이 합류했을 때 개발 환경을 설정하는 데 많은 학습 곡선과 노력이 필요합니다.

Docker Compose는 이러한 문제들을 해결하기 위한 강력한 도구입니다. 컨테이너 기술을 기반으로 각 서비스를 격리된 환경에서 실행하며, 하나의 설정 파일(docker-compose.yml)로 전체 애플리케이션 스택을 정의하고 관리할 수 있게 합니다. 이는 개발 환경의 일관성을 보장하고, 설정 과정을 자동화하며, 협업 효율성을 극대화하는 데 결정적인 역할을 합니다.

2. Docker Compose의 이해와 필요성

Docker는 애플리케이션과 그 종속성을 컨테이너라는 독립적인 실행 단위로 묶어 어디서든 동일하게 작동하도록 돕는 플랫폼입니다. 반면, Docker Compose는 단일 컨테이너가 아닌, 여러 개의 컨테이너로 구성된 애플리케이션을 정의하고 실행하기 위한 도구입니다. 즉, Docker Compose는 다중 컨테이너 애플리케이션의 관리를 위한 오케스트레이션 도구로 볼 수 있습니다.

2.1. Docker와 Docker Compose의 차이점

두 도구는 상호 보완적이지만, 목적에 차이가 있습니다. 이를 비교해보면 Docker Compose의 필요성을 더욱 명확하게 이해할 수 있습니다.

특징	Docker (단일 컨테이너 관리)	Docker Compose (다중 컨테이너 관리)
주요 목적	단일 애플리케이션/서비스를 컨테이너화하고 실행	여러 컨테이너 서비스로 구성된 애플리케이션 스택 정의 및 실행
설정 방식	`Dockerfile`로 이미지 빌드, `docker run` 명령어로 컨테이너 실행	`docker-compose.yml` 파일로 전체 서비스 구성 정의
네트워킹	개별 컨테이너 네트워킹 설정	기본적으로 서비스 간 내부 네트워크 자동 구성
볼륨 관리	개별 컨테이너 볼륨 설정	모든 서비스에 대한 볼륨 정의 및 관리
실행 명령	`docker run [OPTIONS] IMAGE COMMAND`	`docker compose up` (구 `docker-compose up`)
사용 시나리오	단일 마이크로서비스, 간단한 유틸리티 실행	웹 애플리케이션 백엔드/프론트엔드, 데이터베이스 등 다중 서비스 통합

2.2. Docker Compose의 핵심 장점

간소화된 설정: 여러 컨테이너를 한 번에 정의하고 실행할 수 있어 설정 파일 하나로 전체 스택을 관리합니다.
재현 가능한 환경: docker-compose.yml 파일만 공유하면 누구든 동일한 개발 환경을 즉시 구축할 수 있습니다. 이는 온보딩 시간을 획기적으로 단축합니다.
격리된 환경: 각 서비스는 컨테이너 내에서 독립적으로 실행되므로, 호스트 시스템이나 다른 프로젝트에 영향을 주지 않습니다.
쉬운 스케일링: docker compose up --scale service_name=N 명령으로 특정 서비스의 인스턴스를 쉽게 늘릴 수 있습니다.
버전 관리: docker-compose.yml 파일을 Git과 같은 버전 관리 시스템에 통합하여 환경 변경 이력을 추적할 수 있습니다.

3. Nginx, Node.js, PostgreSQL 스택 선택의 배경

이번 가이드에서 다룰 Nginx, Node.js, PostgreSQL 조합은 풀스택 웹 애플리케이션 개발에 매우 보편적으로 사용되는 강력한 스택입니다. 각각의 컴포넌트는 특정 역할에 최적화되어 있으며, 함께 사용될 때 시너지를 발휘합니다.

Nginx (웹 서버 & 리버스 프록시):Nginx는 고성능 웹 서버이자 리버스 프록시 서버로 널리 사용됩니다. 웹 애플리케이션의 진입점(Entry Point) 역할을 수행하며, 다음과 같은 장점을 가집니다:
- 성능: 비동기 이벤트 기반 아키텍처로 인해 적은 자원으로 높은 동시 접속 처리가 가능합니다.
- 로드 밸런싱: 여러 Node.js 인스턴스 간에 트래픽을 분산하여 애플리케이션의 확장성과 안정성을 높일 수 있습니다.
- 정적 파일 서빙: 이미지, CSS, JavaScript와 같은 정적 파일들을 효율적으로 제공하여 Node.js 애플리케이션의 부하를 줄여줍니다.
- SSL/TLS 터미네이션: 보안 연결을 처리하여 애플리케이션 서버의 부담을 덜어줍니다.
Node.js (애플리케이션 서버):Node.js는 Chrome V8 JavaScript 엔진으로 빌드된 JavaScript 런타임으로, 서버 사이드 애플리케이션 개발에 사용됩니다. 특히 다음과 같은 특징으로 인해 웹 백엔드 개발에 인기가 많습니다:
- 단일 언어 스택: 프론트엔드와 백엔드를 모두 JavaScript로 개발할 수 있어 개발 생산성이 향상됩니다.
- 비동기, 이벤트 기반: I/O 작업이 많은 애플리케이션에서 높은 처리량과 확장성을 제공합니다.
- 방대한 생태계: NPM(Node Package Manager)을 통해 수많은 라이브러리와 프레임워크(Express, NestJS 등)를 활용할 수 있습니다.
PostgreSQL (관계형 데이터베이스):PostgreSQL은 강력하고 안정적인 오픈 소스 객체-관계형 데이터베이스 시스템입니다. 엔터프라이즈급 기능과 뛰어난 확장성을 제공하여 다양한 규모의 프로젝트에 적합합니다.
- 안정성 및 신뢰성: ACID(원자성, 일관성, 고립성, 지속성) 속성을 완벽하게 준수하여 데이터 무결성을 보장합니다.
- 풍부한 기능: JSONB, 배열, 사용자 정의 타입 등 다양한 데이터 타입을 지원하며, 고급 SQL 기능과 확장성을 제공합니다.
- 활발한 커뮤니티: 방대한 문서와 활발한 커뮤니티 지원을 받을 수 있습니다.

이 세 가지 기술 스택은 각각의 강점을 결합하여 견고하고 확장 가능한 웹 애플리케이션을 구축하는 데 이상적인 조합을 이룹니다. Docker Compose를 통해 이들을 통합 관리함으로써, 개발자는 환경 설정의 복잡성에서 벗어나 핵심 비즈니스 로직 개발에 집중할 수 있게 됩니다.

Docker Compose를 활용한 Nginx, Node.js, PostgreSQL 기반 로컬 개발 환경 구축 실전 가이드 - the bottle, plastic, segregation, processing, recycling, reflection, container, waste, garbage, responsibility, throw, blue, services, pollution, empty, shine, wet, problem, to treat with, transparent, plastic waste, earth day, plastic, plastic, plastic, plastic, plastic, recycling, waste, plastic waste

Image by pasja1000 on Pixabay

4. Docker Compose 파일(docker-compose.yml) 심층 분석 및 작성

Docker Compose의 핵심은 docker-compose.yml 파일입니다. 이 YAML 파일은 애플리케이션을 구성하는 서비스들, 네트워크, 볼륨 등을 정의합니다. 각 서비스를 어떻게 구성할 것인지 상세히 살펴보겠습니다.

4.1. 프로젝트 디렉토리 구조

먼저 프로젝트의 디렉토리 구조를 설정합니다. 각 서비스의 설정 파일과 코드를 깔끔하게 관리하기 위함입니다.


my-fullstack-app/
├── docker-compose.yml
├── nginx/
│   └── default.conf
├── nodejs-app/
│   ├── Dockerfile
│   ├── package.json
│   └── index.js
└── postgres-data/ (PostgreSQL 데이터 영속성을 위한 디렉토리)

4.2. docker-compose.yml 파일 작성

아래는 Nginx, Node.js, PostgreSQL 서비스를 정의하는 docker-compose.yml 파일의 예시입니다. 각 섹션의 의미를 자세히 설명하겠습니다.


version: '3.8'

services:
  nginx:
    image: nginx:stable-alpine
    container_name: my_nginx
    ports:
      - "80:80"
      - "443:443" # HTTPS를 사용할 경우
    volumes:
      - ./nginx/default.conf:/etc/nginx/conf.d/default.conf:ro
      # - ./nginx/cert:/etc/nginx/cert:ro # HTTPS 인증서 사용 시
    depends_on:
      - nodejs-app
    restart: always

  nodejs-app:
    build:
      context: ./nodejs-app
      dockerfile: Dockerfile
    container_name: my_nodejs_app
    ports:
      - "3000:3000" # Node.js 앱의 직접 접근을 허용할 경우
    volumes:
      - ./nodejs-app:/app
      - /app/node_modules # 호스트의 node_modules와 충돌 방지
    environment:
      NODE_ENV: development
      DATABASE_URL: postgres://user:password@db:5432/mydatabase
    depends_on:
      - db
    restart: always

  db:
    image: postgres:13
    container_name: my_postgres_db
    ports:
      - "5432:5432" # 외부에서 DB 접속 시
    environment:
      POSTGRES_DB: mydatabase
      POSTGRES_USER: user
      POSTGRES_PASSWORD: password
    volumes:
      - postgres-data:/var/lib/postgresql/data
    restart: always

volumes:
  postgres-data:

`version: '3.8'`

Docker Compose 파일의 문법 버전을 정의합니다. 최신 기능과 안정성을 위해 비교적 최신 버전을 사용하는 것이 좋습니다 (예: 3.8 또는 그 이상).

`services:`

애플리케이션을 구성하는 각 서비스를 정의하는 최상위 키입니다. 여기서는 nginx, nodejs-app, db 세 가지 서비스를 정의했습니다.

nginx 서비스:
- image: nginx:stable-alpine: Nginx 컨테이너를 생성할 때 사용할 Docker 이미지를 지정합니다. stable-alpine은 경량화된 안정 버전입니다.
- container_name: my_nginx: 컨테이너에 고유한 이름을 부여하여 식별을 용이하게 합니다.
- ports: - "80:80": 호스트의 80번 포트를 컨테이너의 80번 포트에 매핑합니다. 웹 브라우저에서 localhost로 접속할 수 있게 됩니다. HTTPS를 위해 443번 포트도 매핑할 수 있습니다.
- volumes: - ./nginx/default.conf:/etc/nginx/conf.d/default.conf:ro: 호스트의 ./nginx/default.conf 파일을 컨테이너 내부의 Nginx 설정 파일 경로에 마운트합니다. :ro는 읽기 전용(read-only)을 의미합니다.
- depends_on: - nodejs-app: nginx 서비스가 nodejs-app 서비스보다 먼저 시작되도록 의존성을 설정합니다. Nginx가 Node.js 앱을 프록시하기 때문에 Node.js 앱이 먼저 실행되는 것이 좋습니다.
- restart: always: 컨테이너가 종료될 때 항상 다시 시작되도록 설정합니다. 개발 중 오류로 인해 컨테이너가 중단되어도 자동으로 재시작됩니다.
nodejs-app 서비스:
- build:: Dockerfile을 사용하여 이미지를 빌드하도록 지시합니다.
  - context: ./nodejs-app: Dockerfile을 찾을 경로를 지정합니다.
  - dockerfile: Dockerfile: 빌드에 사용할 Dockerfile 이름을 지정합니다 (기본값과 동일).
- container_name: my_nodejs_app: 컨테이너 이름을 지정합니다.
- ports: - "3000:3000": 호스트의 3000번 포트를 컨테이너의 3000번 포트에 매핑합니다. Node.js 앱에 직접 접근할 필요가 없다면 이 포트 매핑은 생략 가능합니다. Nginx가 리버스 프록시 역할을 하기 때문입니다.
- volumes: - ./nodejs-app:/app: 호스트의 ./nodejs-app 디렉토리를 컨테이너 내부의 /app 디렉토리에 마운트합니다. 이를 통해 호스트에서 코드를 수정하면 컨테이너 내부에도 즉시 반영되어 개발 생산성을 높일 수 있습니다.
- volumes: - /app/node_modules: Node.js 프로젝트의 node_modules 디렉토리는 컨테이너 내부에만 존재하도록 익명 볼륨을 설정합니다. 호스트의 node_modules가 컨테이너 내부로 마운트되어 발생할 수 있는 호환성 문제를 방지하고, 컨테이너 환경에 맞는 패키지 설치를 보장합니다.
- environment:: 컨테이너 내부에서 사용할 환경 변수를 설정합니다. Node.js 애플리케이션이 PostgreSQL 데이터베이스에 접속하는 데 필요한 정보를 제공합니다. DATABASE_URL은 DB 서비스 이름(db)과 포트, 사용자 정보를 포함합니다.
- depends_on: - db: nodejs-app 서비스가 db 서비스보다 먼저 시작되도록 의존성을 설정합니다.
- restart: always: 컨테이너가 항상 재시작되도록 설정합니다.
db 서비스:
- image: postgres:13: PostgreSQL 13 버전을 사용합니다.
- container_name: my_postgres_db: 컨테이너 이름을 지정합니다.
- ports: - "5432:5432": 호스트의 5432번 포트를 컨테이너의 5432번 포트에 매핑합니다. DBeaver나 pgAdmin 같은 외부 DB 클라이언트로 접속할 때 사용합니다.
- environment:: PostgreSQL 컨테이너 초기 설정에 필요한 환경 변수(데이터베이스 이름, 사용자, 비밀번호)를 설정합니다.
- volumes: - postgres-data:/var/lib/postgresql/data: PostgreSQL 데이터가 컨테이너가 삭제되어도 유지되도록 명명된 볼륨(postgres-data)을 마운트합니다. 이는 데이터 영속성을 보장하는 매우 중요한 설정입니다.
- restart: always: 컨테이너가 항상 재시작되도록 설정합니다.

`volumes:`

최상위 volumes 키는 명명된 볼륨을 정의합니다. 여기서는 postgres-data 볼륨을 정의하여 PostgreSQL 컨테이너의 데이터를 영구적으로 저장하는 데 사용합니다.

5. 로컬 개발 환경 구축 실전 가이드: 단계별 진행

이제 docker-compose.yml 파일을 기반으로 실제 로컬 개발 환경을 구축하는 과정을 단계별로 살펴보겠습니다.

5.1. 사전 준비

시작하기 전에 Docker Desktop이 시스템에 설치되어 있어야 합니다. Docker Desktop은 Docker Engine, Docker CLI, Docker Compose 등 필요한 모든 도구를 포함하고 있습니다.

5.2. 프로젝트 디렉토리 및 파일 생성

다음 명령어를 사용하여 프로젝트 디렉토리를 생성하고 필요한 파일들을 준비합니다.


mkdir my-fullstack-app
cd my-fullstack-app

mkdir nginx nodejs-app postgres-data

touch docker-compose.yml
touch nginx/default.conf
touch nodejs-app/Dockerfile
touch nodejs-app/package.json
touch nodejs-app/index.js

5.3. Nginx 설정 (nginx/default.conf)

Nginx가 Node.js 애플리케이션으로 요청을 프록시하고 정적 파일을 서빙하도록 설정합니다.


# nginx/default.conf
server {
    listen 80;
    server_name localhost;

    location / {
        proxy_pass http://nodejs-app:3000; # nodejs-app 서비스로 요청 전달
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection 'upgrade';
        proxy_set_header Host $host;
        proxy_cache_bypass $http_upgrade;
    }

    # 정적 파일 서빙 예시 (실제 프로젝트에서는 별도 볼륨 마운트 고려)
    # location /static/ {
    #     alias /app/public/static/; # Node.js 앱의 정적 파일 경로
    #     expires 30d;
    #     add_header Cache-Control "public, no-transform";
    # }
}

위 설정에서 proxy_pass http://nodejs-app:3000;는 Nginx가 nodejs-app이라는 Docker Compose 서비스 이름과 해당 서비스의 포트(3000)를 사용하여 Node.js 컨테이너로 요청을 전달하도록 지시합니다. Docker Compose는 서비스 이름을 내부 DNS로 자동으로 등록하여 컨테이너 간 통신을 용이하게 합니다.

5.4. Node.js 애플리케이션 설정 (nodejs-app/)

간단한 Node.js Express 애플리케이션을 생성하고, 이를 위한 Dockerfile을 작성합니다.

nodejs-app/package.json


{
  "name": "nodejs-app",
  "version": "1.0.0",
  "description": "A simple Node.js Express app",
  "main": "index.js",
  "scripts": {
    "start": "node index.js"
  },
  "dependencies": {
    "express": "^4.18.2",
    "pg": "^8.11.3"
  }
}

nodejs-app/index.js

데이터베이스 연결을 테스트하는 간단한 API를 포함합니다.


// nodejs-app/index.js
const express = require('express');
const { Client } = require('pg'); // PostgreSQL 클라이언트
const app = express();
const port = 3000;

// PostgreSQL 클라이언트 설정 (환경 변수 사용)
const client = new Client({
  connectionString: process.env.DATABASE_URL || 'postgres://user:password@db:5432/mydatabase'
});

app.get('/', (req, res) => {
  res.send('Hello from Node.js App!');
});

app.get('/db-test', async (req, res) => {
  try {
    await client.connect(); // DB 연결 시도
    const result = await client.query('SELECT NOW() as current_time');
    await client.end(); // DB 연결 종료
    res.json({
      message: 'Database connection successful!',
      currentTime: result.rows[0].current_time
    });
  } catch (err) {
    console.error('Database connection error:', err.stack);
    res.status(500).json({
      message: 'Database connection failed',
      error: err.message
    });
  }
});

app.listen(port, () => {
  console.log(`Node.js app listening at http://localhost:${port}`);
});

nodejs-app/Dockerfile

Node.js 애플리케이션 이미지를 빌드하기 위한 Dockerfile입니다.


# nodejs-app/Dockerfile
FROM node:18-alpine

WORKDIR /app

COPY package*.json ./

RUN npm install

COPY . .

CMD ["npm", "start"]

FROM node:18-alpine: Node.js 18 버전 기반의 Alpine 리눅스 이미지를 사용합니다. Alpine은 경량화된 리눅스 배포판으로 이미지 크기를 줄이는 데 효과적입니다.
WORKDIR /app: 컨테이너 내부의 작업 디렉토리를 /app으로 설정합니다.
COPY package*.json ./: package.json 및 package-lock.json 파일을 작업 디렉토리로 복사합니다.
RUN npm install: 프로젝트의 의존성 패키지를 설치합니다.
COPY . .: 나머지 모든 애플리케이션 코드를 작업 디렉토리로 복사합니다.
CMD ["npm", "start"]: 컨테이너가 시작될 때 실행될 명령어를 정의합니다.

5.5. Docker Compose 파일 최종 확인

앞서 작성했던 docker-compose.yml 파일을 다시 한번 확인하여 모든 경로와 설정이 올바른지 확인합니다.

PostgreSQL의 경우, postgres-data/ 디렉토리는 초기에는 비어 있어도 됩니다. Docker Compose가 컨테이너를 시작할 때 자동으로 볼륨을 생성하고 데이터를 저장할 것입니다.

5.6. 개발 환경 실행

모든 파일 준비가 완료되었다면, 프로젝트 루트 디렉토리(my-fullstack-app)에서 다음 명령어를 실행하여 Docker Compose 스택을 시작합니다.


docker compose up -d

docker compose up: docker-compose.yml 파일에 정의된 모든 서비스를 빌드하고 시작합니다.
-d: 컨테이너를 백그라운드에서 실행합니다 (detached mode).

컨테이너가 성공적으로 시작되었는지 확인하려면 다음 명령어를 사용합니다.


docker compose ps

모든 서비스의 상태가 Up으로 표시되어야 합니다.

5.7. 서비스 접속 및 테스트

이제 웹 브라우저를 열고 다음 주소로 접속하여 Node.js 애플리케이션과 Nginx 리버스 프록시가 정상 작동하는지 확인합니다.

Nginx를 통한 Node.js 접속: http://localhost/
Nginx를 통한 DB 테스트 API 접속: http://localhost/db-test

db-test API에서 PostgreSQL 데이터베이스에 성공적으로 연결되었음을 나타내는 JSON 응답을 받아야 합니다. 만약 실패했다면, 다음 섹션의 트러블슈팅 팁을 참고하세요.

Docker Compose를 활용한 Nginx, Node.js, PostgreSQL 기반 로컬 개발 환경 구축 실전 가이드 - soil, pot plants, plantation, growth, nature, dirt, soil, soil, soil, soil, soil

Image by juairiaa on Pixabay

6. 구축된 환경 활용 및 트러블슈팅 팁

Docker Compose로 개발 환경을 구축한 후에는 이를 효과적으로 활용하고 발생할 수 있는 문제에 대처하는 방법을 아는 것이 중요합니다.

6.1. 개발 환경 관리 명령어

모든 서비스 중단: docker compose stop (컨테이너는 유지, 재시작 가능)
모든 서비스 중단 및 삭제: docker compose down (컨테이너, 네트워크, 볼륨 삭제. -v 옵션을 추가하면 명명된 볼륨도 삭제)
특정 서비스 재시작: docker compose restart [서비스 이름] (예: docker compose restart nodejs-app)
로그 확인: docker compose logs -f [서비스 이름] (예: docker compose logs -f nodejs-app)
컨테이너 내부 명령 실행: docker compose exec [서비스 이름] [명령어] (예: docker compose exec nodejs-app bash)

6.2. 일반적인 트러블슈팅 시나리오

Docker Compose 환경에서 자주 발생하는 문제와 해결책은 다음과 같습니다.

컨테이너 시작 실패:가장 먼저 docker compose logs [서비스 이름] 명령어로 해당 서비스의 로그를 확인해야 합니다. 오류 메시지를 통해 원인을 파악할 수 있습니다.
- 포트 충돌: 호스트 시스템의 다른 프로세스가 이미 사용 중인 포트를 Docker Compose 서비스가 사용하려 할 때 발생합니다. ports 설정을 변경하거나, 충돌하는 프로세스를 종료해야 합니다.
- 환경 변수 오류: environment 설정이 잘못되었거나 누락된 경우입니다. 특히 데이터베이스 연결 정보에 오타가 없는지 확인합니다.
- 볼륨 마운트 문제: 호스트 경로가 올바르지 않거나, 컨테이너 내부 경로에 쓰기 권한이 없는 경우입니다. volumes 설정과 경로 권한을 확인합니다.
서비스 간 통신 실패:예를 들어, Node.js 앱이 PostgreSQL에 연결하지 못하는 경우입니다.
- 서비스 이름 확인: docker-compose.yml 파일 내에서 서비스 간 통신 시에는 IP 주소 대신 서비스 이름을 사용해야 합니다 (예: db 대신 localhost 사용 시 오류).
- 네트워크 설정: Docker Compose는 기본적으로 서비스 간에 내부 네트워크를 자동으로 생성하지만, 복잡한 네트워크 구성의 경우 networks 설정을 명시적으로 정의해야 할 수도 있습니다.
- 방화벽: 호스트 시스템의 방화벽이 컨테이너 간 또는 호스트-컨테이너 간 통신을 차단하는지 확인합니다.
데이터 영속성 문제:컨테이너를 docker compose down 후 다시 up했을 때 데이터가 사라지는 경우입니다.
- 명명된 볼륨 사용: 데이터베이스와 같이 영속성이 필요한 서비스는 반드시 volumes 섹션에 명명된 볼륨을 사용해야 합니다. 위 예시의 postgres-data와 같습니다.
- 볼륨 마운트 경로: 볼륨이 올바른 컨테이너 내부 경로에 마운트되었는지 확인합니다 (예: PostgreSQL의 /var/lib/postgresql/data).
캐시 문제 (이미지 빌드):Dockerfile을 수정했지만 변경 사항이 반영되지 않는 경우입니다.
- docker compose build --no-cache [서비스 이름]: 캐시를 사용하지 않고 이미지를 다시 빌드합니다.

대부분의 문제는 로그를 면밀히 분석하고 Docker Compose의 기본 동작 원리를 이해하면 해결할 수 있습니다. 공식 문서와 커뮤니티 자료를 적극적으로 활용하는 것도 좋은 방법입니다.

7. 결론: Docker Compose를 통한 개발 생산성 향상

지금까지 Docker Compose를 활용하여 Nginx, Node.js, PostgreSQL 기반의 로컬 개발 환경을 구축하는 과정을 상세히 살펴보았습니다. 이 접근 방식은 개발 환경의 일관성을 보장하고, 설정 과정을 간소화하며, 팀원 간의 협업 효율성을 크게 향상시키는 강력한 이점을 제공합니다.

각 컴포넌트의 역할을 명확히 이해하고 docker-compose.yml 파일과 각 서비스의 설정 파일을 올바르게 구성함으로써, 개발자는 환경 설정에 소모되는 시간을 최소화하고 핵심 비즈니스 로직 개발에 집중할 수 있게 됩니다. 이는 궁극적으로 개발 생산성을 극대화하고 프로젝트 성공에 기여할 것입니다.

이 가이드가 여러분의 풀스택 개발 환경 구축에 실질적인 도움이 되었기를 바랍니다. 궁금한 점이나 추가하고 싶은 팁이 있다면 언제든지 댓글로 남겨주세요!

📌 함께 읽으면 좋은 글

[기술 리뷰] 크로스 플랫폼 모바일 개발 프레임워크 심층 비교: React Native, Flutter, Kotlin Multiplatform 완벽 분석
[커리어 취업] 개발자 시스템 설계 면접 완벽 대비 가이드: 고수처럼 문제를 해결하는 법
[이슈 분석] 기술 부채 관리 전략: 건강한 소프트웨어 개발 문화를 위한 현실적인 접근법

이 글이 도움이 되셨다면 공감(♥)과 댓글로 응원해 주세요!
궁금한 점이나 다루었으면 하는 주제가 있다면 댓글로 남겨주세요.

'튜토리얼' 카테고리의 다른 글

Node.js Apollo Server GraphQL API 구축: 개발자를 위한 실전 가이드 (1)	2026.06.26
GitHub Actions 활용 웹 애플리케이션 CI/CD 파이프라인 구축 실전 가이드 (0)	2026.06.26
PostgreSQL 성능 최적화: 인덱싱과 쿼리 튜닝 실전 가이드 (0)	2026.06.22
GitHub Actions를 활용한 웹 애플리케이션 CI/CD 파이프라인 구축 실습 가이드 (0)	2026.06.22
GraphQL API 서버 구축: Apollo Server와 TypeORM 연동 실습 가이드 (0)	2026.06.21

현재글Docker Compose Nginx Node.js PostgreSQL 로컬 개발 환경 구축: 실전 가이드

강코의 코딩 일기

[ Git ] https://github.com/Grren99 기억 해야 하는 것들이 너무 많다.

생산성, 웹 개발, Ai, 워크플로우, 컨테이너, 웹개발, 머신러닝, 개발도구, 개발 생산성, 리팩토링, 개발생산성, ci/cd, 개발 도구, DevOps, 프론트엔드, llm, 자동화, 개발자, 클린코드, 백엔드,

Today :
Yesterday :

강코의 코딩 일기