n8n Docker 설치 가이드: 나만의 자동화 서버 구축하기

반복되는 업무에 지치셨나요? 😥 수동으로 처리하던 잡무들을 자동으로 처리하고 싶으신가요? n8n은 워크플로우 자동화를 위한 강력하고 유연한 오픈 소스 도구입니다. 웹훅, API, 데이터베이스, 클라우드 서비스 등 다양한 연결을 통해 여러분만의 자동화 로직을 구축할 수 있게 해줍니다.

그리고 이 n8n을 가장 쉽고 안정적으로 배포하는 방법 중 하나가 바로 Docker를 사용하는 것입니다! 🐳 이 가이드에서는 n8n을 Docker를 이용해 설치하고, 나만의 자동화 서버를 구축하는 모든 과정을 상세하게 알려드리겠습니다.

🚀 1. 서론: 왜 n8n과 Docker인가?

1.1. n8n이란? ✨

n8n은 “Node-based Workflow Automation”의 약자로, 시각적인 인터페이스를 통해 복잡한 자동화 워크플로우를 쉽게 만들 수 있도록 돕는 도구입니다. Zapier, Make (Integromat)와 같은 서비스와 유사하지만, 가장 큰 장점은 바로 오픈 소스이며 셀프 호스팅이 가능하다는 점입니다. 즉, 여러분의 서버에 직접 설치하여 모든 데이터를 직접 관리하고, 사용량 제한 없이 무료로 사용할 수 있습니다.

1.2. 왜 Docker를 사용해야 할까요? 📦

• 쉬운 배포: 복잡한 의존성 설치 없이 docker-compose up 명령 하나로 n8n 환경을 쉽게 구축할 수 있습니다.
• 격리된 환경: n8n과 관련된 모든 파일 및 프로세스가 독립된 컨테이너 내부에서 실행되므로, 기존 시스템에 영향을 주지 않습니다.
• 이식성 (Portability): Docker가 설치된 어떤 환경에서든 동일한 설정으로 n8n을 실행할 수 있습니다. 개발 환경에서 테스트하고, 프로덕션 서버로 그대로 옮길 수 있죠.
• 버전 관리 및 롤백: 특정 버전의 n8n 이미지를 지정하여 사용하거나, 문제가 발생할 경우 이전 버전으로 쉽게 되돌릴 수 있습니다.
• 유지보수 용이: 업데이트, 백업, 복구 등이 컨테이너 단위로 이루어져 관리가 편리합니다.

🛠️ 2. 사전 준비물

n8n Docker 설치를 시작하기 전에 아래의 준비물들이 필요합니다.

• Linux 또는 Windows/macOS 서버: n8n을 설치할 컴퓨터 (클라우드 VPS, 라즈베리 파이, 개인 PC 등). 안정적인 서비스를 위해서는 Linux 기반의 VPS를 추천합니다.
• Docker 설치:
  • Linux: 공식 문서를 참조하여 OS에 맞는 Docker를 설치합니다.
  • Windows/macOS: Docker Desktop을 설치합니다.
• Docker Compose 설치: (Docker Desktop에는 기본 포함되어 있습니다.)
  • Linux: 공식 문서를 참조하여 설치합니다.
• 기본적인 터미널 (CLI) 사용 능력: 파일 생성, 디렉토리 이동 등의 기본적인 명령어를 알아야 합니다.

⚠️ Docker 및 Docker Compose 설치 예시 (Ubuntu 기준):

# Docker 설치
sudo apt update
sudo apt install ca-certificates curl gnupg lsb-release -y
sudo mkdir -p /etc/apt/keyrings
curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gpg --dearmor -o /etc/apt/keyrings/docker.gpg
echo \
  "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.gpg] https://download.docker.com/linux/ubuntu \
  $(lsb_release -cs) stable" | sudo tee /etc/apt/sources.list.d/docker.list > /dev/null
sudo apt update
sudo apt install docker-ce docker-ce-cli containerd.io docker-compose-plugin -y

# (선택 사항) sudo 없이 Docker 사용 설정
sudo usermod -aG docker $USER
newgrp docker # 현재 세션에 적용

설치 후 docker --version 및 docker compose version 명령어로 정상 설치되었는지 확인하세요.

🏗️ 3. n8n Docker 설치 단계별 가이드

이제 본격적으로 n8n을 설치해 봅시다! 우리는 n8n의 데이터를 영속적으로 저장하고, 안정적인 서비스 제공을 위해 PostgreSQL 데이터베이스와 함께 구성할 것입니다.

3.1. 프로젝트 디렉토리 생성 📂

n8n 관련 파일들을 관리할 전용 디렉토리를 생성합니다.

mkdir n8n-server
cd n8n-server

3.2. docker-compose.yml 파일 작성 📝

n8n-server 디렉토리 안에 docker-compose.yml 파일을 생성하고 아래 내용을 복사하여 붙여넣습니다. vi 또는 nano 에디터를 사용하거나, FTP/SFTP 클라이언트를 이용할 수 있습니다.

# vi docker-compose.yml

version: '3.8'

services:
  n8n:
    image: n8nio/n8n # n8n Docker 이미지
    restart: always # 컨테이너가 종료되면 항상 재시작
    ports:
      - "5678:5678" # 호스트의 5678 포트와 n8n 컨테이너의 5678 포트 연결
    volumes:
      - n8n_data:/home/node/.n8n # n8n 데이터를 영속적으로 저장할 볼륨
    environment:
      # 이메일 전송에 필요한 SMTP 설정 (자세한 내용은 n8n 문서 참조)
      # - N8N_SMTP_HOST=your.smtp.host.com
      # - N8N_SMTP_PORT=587
      # - N8N_SMTP_USER=your_smtp_username
      # - N8N_SMTP_PASS=your_smtp_password
      # - N8N_SMTP_SENDER=notifications@yourdomain.com

      # n8n이 실행될 URL (매우 중요!)
      # 외부에서 접근 가능한 도메인이나 IP 주소:포트 번호로 설정
      # 예: https://your.n8n.domain.com 또는 http://your.server.ip:5678
      - N8N_HOST=${N8N_HOST}
      - N8N_PROTOCOL=${N8N_PROTOCOL}
      - WEBHOOK_URL=${N8N_PROTOCOL}://${N8N_HOST} # 워크플로우 웹훅을 위한 전체 URL

      # n8n에 사용할 데이터베이스 설정 (PostgreSQL 사용)
      - DB_TYPE=postgresdb
      - DB_POSTGRESDB_HOST=postgres
      - DB_POSTGRESDB_PORT=5432
      - DB_POSTGRESDB_DATABASE=${POSTGRES_DB}
      - DB_POSTGRESDB_USER=${POSTGRES_USER}
      - DB_POSTGRESDB_PASSWORD=${POSTGRES_PASSWORD}

      # 시간대 설정 (선택 사항, 서버와 일치시키는 것이 좋음)
      - GENERIC_TIMEZONE=Asia/Seoul # 예: Asia/Seoul, America/New_York

  postgres:
    image: postgres:13 # PostgreSQL 13 버전 이미지
    restart: always
    environment:
      - POSTGRES_DB=${POSTGRES_DB}
      - POSTGRES_USER=${POSTGRES_USER}
      - POSTGRES_PASSWORD=${POSTGRES_PASSWORD}
    volumes:
      - db_data:/var/lib/postgresql/data # PostgreSQL 데이터를 영속적으로 저장할 볼륨

volumes:
  n8n_data: # n8n 데이터를 위한 볼륨
  db_data: # PostgreSQL 데이터를 위한 볼륨

⚠️ 환경 변수 설정 (.env 파일): docker-compose.yml 파일은 위와 같이 작성하고, 실제 값들은 .env 파일에 넣어 관리하는 것이 좋습니다. n8n-server 디렉토리에 .env 파일을 새로 만듭니다.

# vi .env

# .env 파일 내용
N8N_HOST=your.server.ip.or.domain.com # 실제 서버 IP 주소 또는 도메인으로 변경하세요!
N8N_PROTOCOL=http # HTTPS를 설정할 경우 "https"로 변경 (초기에는 http로 시작)

# PostgreSQL 데이터베이스 설정 (보안을 위해 강력한 비밀번호 사용!)
POSTGRES_DB=n8n_database
POSTGRES_USER=n8n_user
POSTGRES_PASSWORD=your_strong_password_here # << 이 부분은 반드시 변경!

각 설정 항목 설명:

• n8n 서비스: n8n 애플리케이션 컨테이너를 정의합니다.
  • image: n8nio/n8n: n8n 공식 Docker 이미지를 사용합니다.
  • restart: always: 컨테이너가 예기치 않게 종료되거나 서버가 재시작될 때 자동으로 n8n을 재시작합니다.
  • ports: "5678:5678": 호스트 머신의 5678 포트로 들어오는 요청을 n8n 컨테이너의 5678 포트로 연결합니다. 웹 브라우저에서 http://[서버_IP]:5678로 접속하게 됩니다.
  • volumes: n8n_data:/home/node/.n8n: n8n의 워크플로우, 자격 증명(Credentials) 등 중요한 데이터가 /home/node/.n8n 경로에 저장됩니다. 이를 n8n_data라는 Docker 볼륨에 연결하여 컨테이너가 삭제되어도 데이터가 손실되지 않도록 합니다.
  • environment: n8n 애플리케이션 내부에서 사용될 환경 변수들입니다.
    • N8N_HOST, N8N_PROTOCOL, WEBHOOK_URL: n8n이 워크플로우 웹훅을 생성할 때 사용할 외부 접속 URL입니다. 이 부분이 정확해야 워크플로우가 제대로 동작합니다. 초기에는 http://[서버_IP]:5678 등으로 설정하고, 나중에 도메인 및 HTTPS 설정 시 변경해야 합니다.
    • DB_TYPE, DB_POSTGRESDB_HOST, …: PostgreSQL 데이터베이스 연결 정보입니다. postgres 서비스의 이름이 DB_POSTGRESDB_HOST 값으로 사용됩니다.
    • GENERIC_TIMEZONE: n8n 내부에서 시간 관련 로직에 사용될 시간대를 설정합니다.
• postgres 서비스: n8n의 데이터를 저장할 PostgreSQL 데이터베이스 컨테이너를 정의합니다.
  • image: postgres:13: PostgreSQL 13 버전 이미지를 사용합니다. (원하는 다른 버전도 가능)
  • environment: PostgreSQL 데이터베이스의 이름, 사용자, 비밀번호를 설정합니다. .env 파일의 값과 동일하게 설정됩니다.
  • volumes: db_data:/var/lib/postgresql/data: PostgreSQL의 실제 데이터 파일들이 db_data라는 Docker 볼륨에 저장되어 영속성을 가집니다.
• volumes: Docker 볼륨들을 정의합니다. 이 볼륨들은 호스트 머신의 특정 경로에 실제 데이터를 저장하여 컨테이너가 삭제되어도 데이터가 유지되도록 합니다.

3.3. n8n 컨테이너 실행 🚀

docker-compose.yml 파일과 .env 파일 작성을 완료했다면, 이제 컨테이너를 실행할 차례입니다. n8n-server 디렉토리 안에서 다음 명령어를 실행합니다.

docker compose up -d

• -d 옵션은 컨테이너를 백그라운드에서 실행하여 터미널을 점유하지 않도록 합니다.
• 처음 실행하는 경우, 필요한 Docker 이미지들을 다운로드받는 시간이 소요될 수 있습니다.

실행 후 컨테이너들이 잘 동작하는지 확인하려면 다음 명령어를 사용합니다:

docker compose ps

Up 상태로 표시되어야 합니다.

3.4. n8n 접속 확인 ✅

모든 컨테이너가 성공적으로 실행되었다면, 웹 브라우저를 열고 다음 주소로 접속합니다.

http://[여러분의_서버_IP_주소]:5678

예시: http://192.168.1.100:5678 또는 http://your.n8n.domain.com:5678

성공적으로 접속하면 n8n의 시작 화면 (관리자 계정 생성 페이지)이 나타날 것입니다! 🎉

⚙️ 4. n8n 고급 설정 및 관리

4.1. 데이터 영속성 (Persistence) 💾

위 docker-compose.yml 설정에서 volumes 섹션을 통해 n8n의 워크플로우 데이터 (n8n_data)와 PostgreSQL 데이터 (db_data)가 영구적으로 저장되도록 설정했습니다. 이 볼륨들은 Docker가 관리하는 특정 위치에 저장되며, 컨테이너를 삭제하고 다시 생성하더라도 이전 데이터가 그대로 유지됩니다.

💡 중요: 볼륨 데이터는 컨테이너 외부에 저장되므로, 서버를 백업할 때 이 볼륨 데이터도 함께 백업해야 안전합니다. 볼륨의 실제 경로를 찾으려면 docker volume inspect n8n_data 명령어를 사용할 수 있습니다.

4.2. HTTPS (SSL) 설정: 보안 강화 🔒

n8n 서버에 외부에서 접속하고, 특히 웹훅을 사용할 예정이라면 HTTPS (SSL) 설정을 통해 통신을 암호화하는 것이 필수적입니다. 이는 보안뿐만 아니라, 많은 외부 서비스 (예: Stripe, Slack 등)가 HTTPS로만 웹훅을 보내기 때문입니다.

Docker로 n8n을 배포할 때 HTTPS를 설정하는 가장 일반적인 방법은 역방향 프록시(Reverse Proxy)를 사용하는 것입니다. Nginx, Caddy 등이 널리 사용됩니다.

설정 단계 개요:

1. 도메인 연결: n8n 서버의 IP 주소에 연결된 도메인(예: n8n.yourdomain.com)을 준비합니다.
2. 역방향 프록시 설치: Nginx 또는 Caddy를 서버에 설치합니다 (Docker 컨테이너로 설치할 수도 있습니다).
3. SSL 인증서 발급: Let's Encrypt와 같은 서비스를 통해 무료 SSL 인증서를 발급받습니다 (Certbot 도구 사용).
4. 프록시 설정: 역방향 프록시가 443 포트 (HTTPS 기본 포트)로 들어오는 요청을 n8n 컨테이너의 5678 포트로 포워딩하도록 설정합니다.

Nginx를 이용한 간략한 설정 예시:

Nginx 설정 파일 (/etc/nginx/sites-available/n8n.conf 등)에 아래와 유사한 내용을 추가합니다.

server {
    listen 80;
    listen 443 ssl;
    server_name n8n.yourdomain.com; # 여러분의 n8n 도메인으로 변경

    ssl_certificate /etc/letsencrypt/live/n8n.yourdomain.com/fullchain.pem; # 인증서 경로
    ssl_certificate_key /etc/letsencrypt/live/n8n.yourdomain.com/privkey.pem; # 키 경로

    location / {
        proxy_pass http://localhost:5678; # n8n 컨테이너가 호스트의 5678 포트에 노출됨
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
        proxy_buffering off; # 실시간 웹훅에 중요
    }
}

⚠️ 중요:

• Nginx 설정 후 N8N_PROTOCOL=https 와 WEBHOOK_URL=https://n8n.yourdomain.com 로 .env 파일을 업데이트하고 docker compose up -d 를 다시 실행해야 합니다.
• docker-compose.yml에서 ports: "5678:5678" 부분을 제거하여 n8n 컨테이너가 직접 외부에 노출되지 않도록 하는 것이 보안상 더 좋습니다. (역방향 프록시만 n8n에 접근)

4.3. n8n 관리자 계정 생성 🔑

n8n에 처음 접속하면 관리자 계정을 생성하는 화면이 나옵니다. 이메일 주소와 비밀번호를 입력하여 계정을 생성하고, 대시보드에 접속하세요. 이 계정은 n8n 인터페이스에 로그인할 때 사용됩니다.

4.4. n8n 업데이트 방법 🔄

n8n을 최신 버전으로 업데이트하는 것은 매우 간단합니다. n8n-server 디렉토리에서 다음 명령어를 실행합니다.

# 최신 n8n 이미지 다운로드
docker compose pull n8n

# 기존 컨테이너 중지 및 삭제 후 새로운 이미지로 컨테이너 재시작
docker compose up -d

이 명령어는 docker-compose.yml에 정의된 n8nio/n8n 이미지의 최신 버전을 다운로드하고, 기존 컨테이너를 새로운 이미지로 교체합니다. 데이터는 n8n_data 볼륨에 저장되어 있으므로 안전하게 유지됩니다.

🚧 5. 문제 해결 팁 (Troubleshooting)

• 컨테이너가 실행되지 않아요!
  • docker compose logs 명령어를 사용하여 컨테이너의 로그를 확인하세요. 에러 메시지가 문제의 원인을 알려줄 것입니다.
  • docker compose ps 명령어로 컨테이너 상태를 확인하고, Exited 상태라면 로그를 확인하세요.
• n8n에 접속할 수 없어요!
  • ports: "5678:5678" 설정이 올바른지 확인하세요.
  • 서버의 방화벽 (firewall)에서 5678 포트가 열려 있는지 확인하세요. (AWS EC2의 보안 그룹, UFW 등)
  • N8N_HOST, N8N_PROTOCOL, WEBHOOK_URL 환경 변수가 올바르게 설정되었는지 다시 확인하세요. 특히 WEBHOOK_URL은 외부에서 n8n에 접근할 수 있는 완전한 URL이어야 합니다.
• PostgreSQL 관련 에러가 발생해요!
  • POSTGRES_DB, POSTGRES_USER, POSTGRES_PASSWORD 환경 변수들이 n8n 서비스와 postgres 서비스 모두에서 일치하는지 확인하세요.
  • db_data 볼륨에 권한 문제가 있을 수 있습니다. 경우에 따라 docker volume rm db_data 후 다시 시작해야 할 수도 있습니다 (데이터는 초기화됨).
• docker compose 명령을 찾을 수 없어요!
  • Docker Compose가 제대로 설치되었는지 확인하세요. docker compose version으로 확인합니다.
  • 혹은 구버전 Docker Compose를 사용 중이라면 docker-compose (하이픈 포함) 명령어를 사용해야 할 수 있습니다.

💡 6. 마치며: 나만의 자동화 세계를 펼치다

축하합니다! 🎉 이 가이드를 통해 자신만의 n8n 자동화 서버를 성공적으로 구축하셨기를 바랍니다. 이제 여러분은 반복되는 업무를 줄이고, 시간을 절약하며, 비즈니스 프로세스를 최적화할 수 있는 강력한 도구를 손에 넣게 되었습니다.

n8n은 매우 유연하고 다양한 기능을 제공합니다. 공식 문서와 커뮤니티를 통해 더 많은 워크플로우 아이디어를 얻고, 여러분의 필요에 맞는 자동화를 만들어나가세요.

• n8n 공식 문서: https://docs.n8n.io/
• n8n 커뮤니티 포럼: https://community.n8n.io/

이제 여러분의 창의력을 발휘하여 무한한 자동화의 가능성을 탐험해 보세요! 🚀✨ D