n8n 셀프호스팅 방법과 Docker Nginx PostgreSQL 프로덕션 구축 가이드

목차

• 1부: n8n 서버 환경 구성 가이드 시작하기
  • 1.1. 시스템 요구사항 파악하기
  • 1.2. 사전 준비 사항
• 2부: Docker 기반으로 n8n 셀프호스팅 설치하기
  • 2.1. Docker Compose 파일 작성
  • 2.2. .env 파일을 통한 환경변수 관리
  • 2.3. PostgreSQL로 프로덕션 데이터베이스 구성하기
• 3부: n8n 보안 설정 및 권한 관리 실전 가이드
  • 3.1. Nginx 리버스 프록시와 Let’s Encrypt로 HTTPS 설정
  • 3.2. 사용자 인증 및 접근 제어
  • 3.3. 기타 보안 강화 조치
• 4부: 문제 해결 (Troubleshooting)
  • 4.1. 컨테이너는 실행되는데 접속이 안 되는 경우
  • 4.2. Webhook이 동작하지 않는 경우
  • 4.3. Docker 재시작 시 데이터가 초기화되는 문제
• 결론: 당신만의 자동화 엔진, 이제 시작입니다

1부: n8n 서버 환경 구성 가이드 시작하기

본격적인 설치에 앞서, n8n이 쾌적하게 동작할 수 있는 서버의 사양과 필요한 소프트웨어들을 준비합니다. 이 단계는 집을 짓기 전 땅을 다지는 것과 같이 중요합니다. 튼튼한 기반 위에서 안정적인 자동화 시스템이 시작됩니다.

1.1. 시스템 요구사항 파악하기

아래 사양은 동시 워크플로우 10~20개, 개인 사이드 프로젝트 또는 소규모 팀 자동화 운영을 기준으로 합니다. 워크플로우의 복잡성과 실행 빈도에 따라 필요 사양은 달라질 수 있습니다.

• 운영체제: 이 가이드는 Ubuntu 22.04 LTS를 기준으로 설명하지만, 다른 리눅스 배포판에서도 동일한 개념으로 적용 가능합니다.
• 필수 소프트웨어:
  • Docker: 최신 안정 버전 (예: 25.x)
  • Docker Compose: 최신 안정 버전 (예: v2.x)

Docker를 사용하면 n8n 구동에 필요한 Node.js 등이 컨테이너 안에 미리 포함되어 있으므로, 서버에 별도로 설치할 필요가 없어 편리합니다.

1.2. 사전 준비 사항

설치를 시작하기 전, 아래 세 가지를 미리 준비해야 합니다.

• 서버: 안정적인 VPS(가상 사설 서버)를 준비하세요. Vultr, DigitalOcean, AWS Lightsail 등 신뢰할 수 있는 클라우드 서비스 제공업체를 이용하는 것을 권장합니다.
• 도메인: 외부에서 접속하고 HTTPS 보안 설정을 적용하려면 고유 도메인이 필요합니다. n8n.your-domain.com과 같이 서브도메인을 사용하는 것이 일반적입니다.
• DNS 설정: 준비한 도메인(또는 서브도메인)의 A 레코드가 서버의 공인 IP 주소를 가리키도록 미리 설정해주세요. 이 설정이 적용되기까지는 몇 분에서 몇 시간까지 걸릴 수 있습니다.

이제 서버에 접속하여 Docker와 Docker Compose를 설치합니다. 아래 명령어를 터미널에 입력하세요.

sudo apt-get update && sudo apt-get install docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin -y

2부: Docker 기반으로 n8n 셀프호스팅 설치하기

이 단계에서는 Docker Compose를 사용하여 n8n 애플리케이션과 데이터를 저장할 PostgreSQL 데이터베이스를 함께 설치하고 실행합니다.

이 단계에서 할 일
Docker Compose 설정 파일 작성 → PostgreSQL 데이터베이스 컨테이너 실행 → n8n 컨테이너 실행 → 웹 UI 접속 확인

2.1. Docker Compose 파일 작성

n8n과 데이터베이스를 한 번에 관리하기 위해 docker-compose.yml 파일을 사용합니다. 이 파일 하나로 모든 서비스의 설정과 연결을 정의할 수 있어 매우 편리합니다. 서버에 n8n 폴더를 만들고, 그 안에 docker-compose.yml 파일을 생성하여 아래 내용을 붙여넣으세요.

version: '3.8'

services:
  postgres:
    image: postgres:15
    restart: always
    environment:
      - POSTGRES_USER=${POSTGRES_USER}
      - POSTGRES_PASSWORD=${POSTGRES_PASSWORD}
      - POSTGRES_DB=${POSTGRES_DB}
    volumes:
      - postgres_data:/var/lib/postgresql/data # 데이터 영속성을 위한 볼륨
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U ${POSTGRES_USER} -d ${POSTGRES_DB}"]
      interval: 10s
      timeout: 5s
      retries: 5

  n8n:
    image: docker.n8n.io/n8nio/n8n:latest
    restart: always
    environment:
      - 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}
      - N8N_HOST=${SUBDOMAIN}.${DOMAIN_NAME}
      - N8N_PORT=5678
      - N8N_PROTOCOL=https
      - WEBHOOK_URL=https://${SUBDOMAIN}.${DOMAIN_NAME}/
      - GENERIC_TIMEZONE=${GENERIC_TIMEZONE}
      - N8N_ENCRYPTION_KEY=${N8N_ENCRYPTION_KEY} # 워크플로우 자격증명 암호화 키
    ports:
      - "127.0.0.1:5678:5678" # 보안을 위해 localhost로만 포트 개방
    volumes:
      - n8n_data:/home/node/.n8n
    depends_on:
      postgres:
        condition: service_healthy

volumes:
  postgres_data:
  n8n_data:

2.2. .env 파일을 통한 환경변수 관리

민감한 정보(비밀번호, 도메인 등)를 docker-compose.yml 파일에 직접 작성하는 대신, 별도의 .env 파일로 관리하는 것이 보안상 안전하고 편리합니다. docker-compose.yml과 같은 위치에 .env 파일을 만들고 아래 내용을 작성하세요.

# PostgreSQL 설정
POSTGRES_DB=n8n
POSTGRES_USER=n8n
POSTGRES_PASSWORD=your_strong_password_here # 강력한 비밀번호로 변경

# n8n 설정
SUBDOMAIN=n8n
DOMAIN_NAME=your-domain.com
GENERIC_TIMEZONE=Asia/Seoul # 거주 지역의 타임존으로 설정
N8N_ENCRYPTION_KEY=your_super_secret_encryption_key # 32자리 이상의 랜덤 문자열로 변경

실무 팁:

• N8N_ENCRYPTION_KEY: 이 키는 워크플로우에 저장된 API 키나 비밀번호 같은 자격증명을 암호화하는 데 사용됩니다. 한번 설정 후 절대 변경하면 안 되며, 분실 시 복구가 불가능합니다. 터미널에서 openssl rand -hex 32 명령어로 안전한 키를 생성하여 사용하세요.
• 워크플로우 실행 기록 관리: .env 파일에 EXECUTIONS_DATA_SAVE_ON_SUCCESS=none와 EXECUTIONS_DATA_SAVE_ON_ERROR=all를 추가하는 것을 권장합니다. 이렇게 하면 성공한 워크플로우의 데이터는 저장하지 않아 용량을 절약하고, 실패한 워크플로우의 데이터만 저장하여 디버깅에 활용할 수 있습니다.

2.3. PostgreSQL로 프로덕션 데이터베이스 구성하기

n8n의 기본 데이터베이스는 SQLite이지만, 여러 워크플로우가 동시에 실행되는 프로덕션 환경에서는 안정성과 확장성이 뛰어난 PostgreSQL 사용을 강력히 추천합니다. 위에서 작성한 설정은 이미 PostgreSQL을 사용하도록 되어 있습니다.

이제 모든 준비가 끝났습니다. .env와 docker-compose.yml 파일이 있는 디렉토리에서 아래 명령어를 실행하여 컨테이너들을 시작하세요.

docker compose up -d

잠시 후, docker compose logs -f n8n 명령어로 로그를 확인하여 “n8n ready”와 같은 메시지가 보이면 성공적으로 시작된 것입니다.

데이터베이스 백업:
데이터는 매우 중요합니다. pg_dump 명령어를 사용하여 정기적으로 PostgreSQL 데이터베이스를 백업하는 스크립트를 작성하고 cron에 등록하세요. 아래는 백업 명령어 예시입니다.

docker compose exec -T postgres pg_dump -U n8n -d n8n > backup_$(date +%F).sql

3부: n8n 보안 설정 및 권한 관리 실전 가이드

이제 n8n이 실행되고 있지만, 외부에서 안전하게 접속하려면 보안 설정이 필수입니다. 이 단계에서는 Nginx 리버스 프록시와 SSL 인증서를 적용하여 모든 통신을 암호화하고 접근 제어를 설정합니다.

3.1. Nginx 리버스 프록시와 Let’s Encrypt로 HTTPS 설정

HTTPS가 적용되지 않은 HTTP 통신은 중간에서 데이터를 탈취당할 위험이 있습니다. 로그인 정보, API 키 등이 암호화되지 않은 평문으로 노출될 수 있으므로, 프로덕션 환경에서는 반드시 HTTPS를 적용해야 합니다.

먼저 Nginx와 SSL 인증서 발급을 위한 Certbot을 설치합니다.

sudo apt-get install nginx certbot python3-certbot-nginx -y

다음으로, /etc/nginx/sites-available/n8n 경로에 새 설정 파일을 생성하고 아래 내용을 입력합니다.

server {
    server_name n8n.your-domain.com; # .env 파일과 동일한 도메인

    location / {
        proxy_pass http://localhost:5678;
        proxy_set_header Connection '';
        proxy_http_version 1.1;
        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 https;
        proxy_buffering off;
    }

    listen 80;
}

이제 Nginx 설정을 활성화하고 Certbot을 실행하여 SSL 인증서를 발급받습니다.

# Nginx 설정 활성화
sudo ln -s /etc/nginx/sites-available/n8n /etc/nginx/sites-enabled/

# Certbot 실행
sudo certbot --nginx -d n8n.your-domain.com

Certbot의 안내에 따라 이메일 주소를 입력하고 약관에 동의하면, 자동으로 SSL 인증서가 발급되고 Nginx 설정이 업데이트되어 HTTPS 접속(443 포트)이 가능해집니다.

3.2. 사용자 인증 및 접근 제어

외부에 노출된 n8n 인스턴스는 최소 2중의 방어막을 갖추는 것이 안전합니다. Nginx의 기본 인증(Basic Auth)으로 1차 방어, n8n 자체 로그인으로 2차 방어를 설정할 수 있습니다.

Nginx 기본 인증 추가:
먼저 사용자 이름과 비밀번호를 저장할 파일을 생성합니다.

sudo htpasswd -c /etc/nginx/.htpasswd your_username

명령어를 실행하면 비밀번호를 입력하라는 메시지가 나타납니다. 이제 Nginx 설정 파일(/etc/nginx/sites-available/n8n)의 location 블록 안에 다음 두 줄을 추가합니다.

auth_basic "Restricted Access";
auth_basic_user_file /etc/nginx/.htpasswd;

Nginx를 재시작(sudo systemctl restart nginx)하면 n8n 도메인에 접속 시 아이디와 비밀번호를 묻는 팝업창이 나타납니다.

n8n 자체 사용자 관리:
Nginx 기본 인증을 통과한 후, n8n에 처음 접속하면 관리자 계정을 생성하는 화면이 나타납니다. 이 계정 정보를 안전하게 보관하세요. 팀 단위로 사용한다면 n8n의 유료 플랜을 통해 여러 사용자를 생성하고 워크플로우별 권한을 세부적으로 관리할 수 있습니다.

3.3. 기타 보안 강화 조치

• 방화벽 설정 (UFW): 서버 방화벽을 활성화하여 허용된 포트(SSH, HTTP, HTTPS) 외의 모든 접근을 차단합니다. 이는 서버 보안의 가장 기본적인 조치입니다.

      sudo ufw allow ssh
      sudo ufw allow 'Nginx Full'
      sudo ufw enable

• Secrets 관리:
  • .env 파일은 Git과 같은 버전 관리 시스템에 절대 포함시키지 마세요. .gitignore 파일에 .env를 추가하여 실수를 방지해야 합니다.
  • 서버 내에서도 .env 파일의 권한을 chmod 600 .env로 설정하여 소유자만 읽고 쓸 수 있도록 제한하는 것이 안전합니다.
• 최소 권한 원칙: n8n에서 데이터베이스나 다른 서비스에 연결할 때는, 해당 워크플로우에 필요한 최소한의 권한만 가진 전용 계정을 생성하여 사용하는 것이 안전합니다. 전체 권한을 가진 마스터 계정 사용은 피해야 합니다.

4부: 문제 해결 (Troubleshooting)

셀프호스팅 과정에서 마주칠 수 있는 몇 가지 흔한 문제들과 해결 방법을 정리했습니다. 문제가 발생하면 당황하지 말고 아래 내용을 확인해보세요.

4.1. 컨테이너는 실행되는데 접속이 안 되는 경우

• 증상: docker compose ps로는 n8n 컨테이너가 ‘running’ 상태이지만, 브라우저에서 도메인으로 접속이 안 됩니다.
• 진단 및 해결:
  • 방화벽 확인: 서버의 방화벽(UFW)이 80, 443 포트를 허용하고 있는지 확인하세요. sudo ufw status 명령어로 상태를 볼 수 있습니다.
  • Nginx 로그 확인: Nginx 에러 로그(cat /var/log/nginx/error.log)를 확인하여 설정 오류가 없는지 점검하세요. 도메인 이름 오타 등이 원인일 수 있습니다.
  • Docker 포트 포워딩: docker-compose.yml 파일의 ports 설정이 "127.0.0.1:5678:5678"로 되어 있는지 확인하세요. 이는 Nginx를 통해서만 접속되도록 제한한 것이므로, 서버 IP로 직접 접속하는 것은 차단됩니다.

4.2. Webhook이 동작하지 않는 경우

• 증상: 워크플로우의 Webhook URL로 요청을 보내도 n8n이 반응하지 않습니다.
• 진단 및 해결:
  • .env 파일의 WEBHOOK_URL 또는 N8N_HOST, N8N_PROTOCOL 설정이 실제 접속하는 도메인 및 프로토콜(https)과 정확히 일치하는지 다시 한번 확인하세요. http가 아닌 https로 설정되었는지, 도메인 주소가 올바른지가 가장 흔한 실수입니다.

4.3. Docker 재시작 시 데이터가 초기화되는 문제

• 증상: docker compose down 후 up을 하면 워크플로우와 설정이 모두 사라집니다.
• 진단 및 해결:
  • docker-compose.yml 파일에 volumes 설정이 올바르게 되어 있는지 확인하세요. n8n_data:/home/node/.n8n과 같이 명명된 볼륨(named volume)을 사용하여 데이터를 컨테이너 외부의 영속적인 공간에 저장해야 합니다. 이 설정이 누락되면 컨테이너가 삭제될 때 데이터도 함께 사라집니다.

결론: 당신만의 자동화 엔진, 이제 시작입니다

축하합니다! 이 가이드를 통해 Docker와 Nginx를 활용한 안정적이고 안전한 n8n 셀프호스팅 방법을 성공적으로 마쳤습니다. 이제 당신은 데이터와 비용을 완벽하게 통제하며 무한한 자동화의 가능성을 탐색할 준비가 되었습니다.

다음 단계 제안:

• 첫 번째 워크플로우 만들기: 간단한 Webhook과 Discord/Slack 알림을 연동하는 워크플로우를 만들어보며 n8n과 친해져 보세요.
• 커뮤니티 노드 탐색: n8n의 강력함은 커뮤니티에 있습니다. 필요한 기능이 있다면 먼저 n8n.io의 커뮤니티 노드 페이지에서 유용한 노드가 있는지 찾아보세요.
• 정기적인 백업 및 업데이트: 구축한 시스템을 안정적으로 유지하기 위해 정기적인 데이터베이스 백업과 n8n 버전 업데이트(docker compose pull n8n 후 docker compose up -d)를 잊지 마세요.

n8n 셀프호스팅은 단순한 도구 설치를 넘어, 당신의 아이디어를 현실로 만드는 강력한 엔진을 갖게 되는 것입니다. 이제 마음껏 자동화의 세계를 경험해보세요.

자주 묻는 질문 (FAQ)

Q1: n8n 셀프호스팅을 위해 어떤 서버 사양이 필요한가요?

A: 테스트 목적이라면 최소 1 vCPU, 2GB RAM, 20GB SSD로도 충분하지만, 실제 운영(프로덕션) 환경에서는 안정적인 성능을 위해 2 vCPU, 4GB RAM, 40GB SSD 이상을 권장합니다. 워크플로우의 복잡성과 실행 빈도에 따라 사양은 더 높아질 수 있습니다.

Q2: 기본 데이터베이스인 SQLite 대신 PostgreSQL을 사용하는 이유는 무엇인가요?

A: SQLite는 간단한 테스트나 개인용으로 사용하기에는 편리하지만, 여러 워크플로우가 동시에 실행되고 데이터 처리량이 많은 프로덕션 환경에서는 성능 저하 및 데이터 충돌의 위험이 있습니다. PostgreSQL은 동시성 처리 능력이 뛰어나고 안정성과 확장성이 높아, 안정적인 운영 환경에 필수적입니다.

Q3: Nginx 리버스 프록시는 왜 필요한가요?

A: Nginx 리버스 프록시는 여러 중요한 역할을 합니다. 첫째, Let’s Encrypt를 통해 무료로 SSL 인증서(HTTPS)를 적용하여 모든 통신을 암호화합니다. 둘째, n8n 애플리케이션으로 직접적인 외부 접근을 막고 Nginx를 통해 트래픽을 전달하여 보안을 강화합니다. 셋째, 기본 인증(Basic Auth)과 같은 추가적인 접근 제어 기능을 쉽게 구현할 수 있습니다.

Q4: 워크플로우 데이터가 사라지지 않게 하려면 어떻게 해야 하나요?

A: Docker 컨테이너는 일시적인 환경이므로, 데이터를 영구적으로 보존하려면 Docker 볼륨(Volume)을 사용해야 합니다. docker-compose.yml 파일에 volumes 섹션을 정의하여(예: n8n_data:/home/node/.n8n), 컨테이너 내부의 데이터를 호스트 서버의 특정 경로에 저장해야 합니다. 이렇게 하면 컨테이너를 재시작하거나 업데이트해도 데이터가 안전하게 유지됩니다.

이 글이 마음에 드세요?

RSS 피드를 구독하세요!