n8n 설치 및 실행 방법

이 장에서는 Docker Compose를 활용하여 n8n을 설치하고 실행하는 방법을 단계별로 안내합니다. 이 방법은 자체 호스팅 환경에서 n8n을 안정적이고 유연하게 운영할 수 있도록 도와줍니다.(n8n 공식 기술 문서)

✅ 사전 준비 사항

  • Docker 및 Docker Compose가 설치되어 있어야 합니다. 설치 방법은 Docker 공식 문서를 참고하세요.

  • 도메인 이름: 외부에서 접근 가능한 도메인을 보유하고 있거나 CloudFlare 또는 Ngrok서비스를 통한 터널링이 필요합니다.

  • 서버 환경: Ubuntu 20.04 이상, 최소 2 vCPU 및 4GB RAM을 권장합니다.

📁 디렉토리 및 파일 구성

  1. 작업 디렉토리 생성:
mkdir n8n-docker && cd n8n-docker
  1. .env 파일 생성:
touch .env
  1. docker-compose.yml 파일 생성:
touch docker-compose.yml

🔐 환경 변수 설정 (.env 파일)

.env 파일에 다음과 같이 환경 변수를 설정합니다:

SSL_EMAIL=SSL인증용email
SUBDOMAIN=subdomain
DOMAIN_NAME=yourdomain.com
GENERIC_TIMEZONE=Asia/Seoul

yourdomain.com은 자신의 도메인 정보를 입력합니다. subdomain 서브도메인 정보를 입력합니다. n8n.test.com 주소를 사용하는 경우 n8n을 서브도메인으로 입력하고 test.com을 도메인 정보로 사용합니다.

🛠️ Docker Compose 설정 (docker-compose.yml 파일)

docker-compose.yml 파일에 다음 내용을 추가합니다:

services:
  traefik:
    image: "traefik"
    restart: always
    command:
      - "--api=true"
      - "--api.insecure=true"
      - "--providers.docker=true"
      - "--providers.docker.exposedbydefault=false"
      - "--entrypoints.web.address=:80"
      - "--entrypoints.web.http.redirections.entryPoint.to=websecure"
      - "--entrypoints.web.http.redirections.entrypoint.scheme=https"
      - "--entrypoints.websecure.address=:443"
      - "--certificatesresolvers.mytlschallenge.acme.tlschallenge=true"
      - "--certificatesresolvers.mytlschallenge.acme.email=${SSL_EMAIL}"
      - "--certificatesresolvers.mytlschallenge.acme.storage=/letsencrypt/acme.json"
    ports:
      - "80:80"
      - "443:443"
    volumes:
      - traefik_data:/letsencrypt
      - /var/run/docker.sock:/var/run/docker.sock:ro

  n8n:
    image: docker.n8n.io/n8nio/n8n
    restart: always
    ports:
      - "127.0.0.1:5678:5678"
    labels:
      - traefik.enable=true
      - traefik.http.routers.n8n.rule=Host(`${SUBDOMAIN}.${DOMAIN_NAME}`)
      - traefik.http.routers.n8n.tls=true
      - traefik.http.routers.n8n.entrypoints=web,websecure
      - traefik.http.routers.n8n.tls.certresolver=mytlschallenge
      - traefik.http.middlewares.n8n.headers.SSLRedirect=true
      - traefik.http.middlewares.n8n.headers.STSSeconds=315360000
      - traefik.http.middlewares.n8n.headers.browserXSSFilter=true
      - traefik.http.middlewares.n8n.headers.contentTypeNosniff=true
      - traefik.http.middlewares.n8n.headers.forceSTSHeader=true
      - traefik.http.middlewares.n8n.headers.SSLHost=${DOMAIN_NAME}
      - traefik.http.middlewares.n8n.headers.STSIncludeSubdomains=true
      - traefik.http.middlewares.n8n.headers.STSPreload=true
      - traefik.http.routers.n8n.middlewares=n8n@docker
    environment:
      - N8N_HOST=${SUBDOMAIN}.${DOMAIN_NAME}
      - N8N_PORT=5678
      - N8N_PROTOCOL=https
      - NODE_ENV=production
      - WEBHOOK_URL=https://${SUBDOMAIN}.${DOMAIN_NAME}/
      - GENERIC_TIMEZONE=${GENERIC_TIMEZONE}
    volumes:
      - n8n_data:/home/node/.n8n
      - ./local-files:/files

volumes:
  n8n_data:
  traefik_data:

데이터 폴더 만들기

docker-compose에서 사용하는 도커 볼륨을 생성합니다. 코드에서는 아래와 같이 n8n_data와 traefik_data 볼륨을 사용합니다.

volumes:
  n8n_data:
  traefik_data:

n8n은 n8n_data 볼륨에 데이터베이스 파일과 암호화 키를 저장합니다. 주기적으로 백업하여 관리하는 것이 좋습니다. traefic_data는 SSL 인증서와 관련 데이터를 지속적으로 저장하기 위해 사용됩니다. 이러한 데이터를 acme.json 파일에 저장함으로써, Traefik은 컨테이너 재시작이나 시스템 재부팅 후에도 인증서를 유지할 수 있습니다.

sudo docker volume create n8n_data
sudo docker volume create traefik_data

위의 명령을 사용해서 volume을 생성합니다.

🛡️ 보안 및 운영 팁

  • 운영 환경에서는 Nginx와 같은 리버스 프록시를 사용하여 SSL 인증서를 적용이 필요합니다.

  • 데이터 백업: 정기적으로 n8n_data 및 n8n_postgres_data 볼륨을 백업하여 데이터 손실에 대비해야 합니다.

  • 업데이트 관리: n8n의 최신 버전을 유지하려면 주기적으로 이미지를 업데이트가 필요합니다.

docker-compose.yml 파일에서는 Traefik 서비스를 통해 https 인증을 진행합니다. 필요한 정보는 traefik_data라는 이름의 Docker 볼륨을 생성하고 /letsencrypt 경로에 마운트하도록 설정되어 있습니다:

volumes:
  - traefik_data:/letsencrypt

이러한 설정은 Traefik이 SSL 인증서 정보를 저장하는 acme.json 파일을 컨테이너 내부의 /letsencrypt/acme.json 경로에 위치시키며, 해당 파일은 traefik_data 볼륨을 통해 호스트 시스템에 저장됩니다.

Docker 볼륨은 일반적으로 호스트 시스템의 /var/lib/docker/volumes/ 디렉토리 아래에 저장됩니다. 따라서 traefik_data 볼륨의 실제 경로는 다음과 같습니다.

/var/lib/docker/volumes/traefik_data/_data/acme.json

이 경로에서 acme.json 파일을 확인하거나 백업할 수 있습니다. 단, Docker 볼륨의 경로는 시스템에 따라 다를 수 있으므로, 정확한 경로를 확인하려면 다음 명령어를 사용할 수 있습니다.

docker volume inspect traefik_data

[
    {
        ...
        "Mountpoint": "/var/lib/docker/volumes/traefik_data/_data",
        "Name": "traefik_data",
        ...        
    }
]

▶️ n8n 실행

Docker Compose를 사용하여 n8n을 백그라운드에서 실행합니다:

docker compose up -d

정상적으로 실행되면 브라우저에서 https://n8n.yourdomain.com에 접속하여 n8n에 로그인할 수 있습니다.

🧹 n8n 중지 및 정리

n8n 서비스를 중지하고 관련 리소스를 정리하려면 다음 명령어를 사용합니다:

docker compose down

데이터 볼륨까지 삭제하려면:

docker compose down -v

📚 참고 자료