n8n Docker 설치 방법: Compose·업데이트·백업까지

n8n Docker 설치 방법을 찾는 사람을 위해 Docker Compose 예제, 환경 변수, 업데이트, 백업, 자주 나는 오류까지 한 번에 정리했습니다. 처음 설치부터 운영까지 바로 이어지게 설명합니다.

n8n Docker 설치 방법을 찾는 사람은 보통 두 가지를 같이 원합니다.
“지금 바로 띄우는 방법”과 “나중에 안 터지게 운영하는 방법”입니다.

결론부터 말하면, 테스트만 할 거면 docker run 도 괜찮지만 실제로 쓸 생각이면 처음부터 docker compose 로 설치하는 편이 훨씬 낫습니다. 이 글은 n8n Docker 설치를 처음 할 때 많이 쓰는 Compose 예제, 환경 변수, 데이터 저장 위치, 업데이트와 백업까지 한 번에 정리합니다. 설치는 쉬워 보여도 데이터 볼륨과 재시작 정책을 빼먹으면 나중에 더 크게 막히기 때문입니다.

Table of Contents

이 글의 역할: 운영형 배포 보조 가이드

이 글은 바이브코딩 배포 대표 글 다음에 붙는 운영형 보조 가이드입니다.
처음 읽는 순서는 아래처럼 잡는 편이 좋습니다.

즉, 이 글은 입문용 대표 글이 아니라 배포 이후 실제 운영과 자동화 환경을 더 깊게 다루는 글로 보면 됩니다.

먼저 핵심 요약

테스트만 빨리 하고 싶다면 docker run 으로도 시작할 수 있습니다.
실제로 계속 쓸 생각이라면 처음부터 docker compose 파일로 관리하는 편이 낫습니다.
-v 또는 named volume 없이 띄우면 재시작이나 재배포 뒤에 데이터가 꼬일 수 있습니다.
업데이트 전에 백업과 버전 태그를 먼저 확인해야 합니다.

왜 n8n을 Docker로 설치하나

n8n은 워크플로우 자동화 도구입니다. 웹훅, 스케줄, API 호출, 데이터 변환 같은 반복 작업을 시각적으로 연결해 자동화할 수 있습니다. Docker로 설치하면 서버 환경을 깔끔하게 분리할 수 있고, 업데이트나 재시작도 비교적 단순하게 관리할 수 있습니다.

특히 초보자는 설치 방법 자체보다 운영 환경을 어떻게 유지할지에서 더 자주 막힙니다. 그래서 처음부터 아래 네 가지를 같이 보는 편이 좋습니다.

어떤 포트로 열 것인가
데이터는 어디에 저장할 것인가
환경 변수는 어떻게 분리할 것인가
나중에 업데이트할 때 무엇을 백업할 것인가

설치 전에 준비할 것

최소한 아래 항목은 먼저 확인하는 편이 좋습니다.

Docker 또는 Docker Desktop이 이미 설치되어 있는지
서버나 로컬 PC에서 5678 포트를 써도 되는지
데이터를 저장할 폴더 또는 Docker volume을 어디에 둘지
외부에서 접속할 계획이라면 도메인과 리버스 프록시를 나중에 붙일지

리눅스 서버라면 아래처럼 Docker와 Compose 플러그인이 동작하는지 먼저 확인할 수 있습니다.

docker --version
docker compose version

가장 추천하는 설치 방법: Docker Compose

처음부터 가장 관리하기 쉬운 방법은 docker compose.yml 파일을 두고 실행하는 방식입니다.

services:
  n8n:
    image: n8nio/n8n:latest
    container_name: n8n
    restart: unless-stopped
    ports:
      - "5678:5678"
    environment:
      - TZ=Asia/Seoul
      - GENERIC_TIMEZONE=Asia/Seoul
      - N8N_HOST=localhost
      - N8N_PORT=5678
      - N8N_PROTOCOL=http
    volumes:
      - ./n8n_data:/home/node/.n8n

같은 폴더에서 아래 명령으로 실행합니다.

docker compose up -d

이 방식이 좋은 이유는 설정을 파일로 남길 수 있기 때문입니다. 포트, 환경 변수, 데이터 위치를 나중에 다시 확인할 수 있고, 서버 이전이나 재설치 때도 훨씬 덜 헷갈립니다.

빠른 테스트용 `docker run` 예제

정말 빠르게 화면만 확인하고 싶다면 아래처럼 띄울 수 있습니다.

docker run -d 
  --name n8n 
  -p 5678:5678 
  -v $HOME/n8n_data:/home/node/.n8n 
  --restart unless-stopped 
  n8nio/n8n:latest

다만 장기적으로는 Compose 쪽이 낫습니다. 나중에 환경 변수를 하나 더 추가하거나 버전을 고정할 때 docker run 기록만으로는 관리가 빠르게 불편해집니다.

데이터 저장 경로를 반드시 잡아야 하는 이유

가장 흔한 실수는 컨테이너만 띄우고 데이터 저장 위치를 분리하지 않는 것입니다. n8n은 워크플로우, 자격 증명, 실행 관련 데이터를 내부 디렉터리에 저장합니다. 그래서 볼륨 없이 시작하면 컨테이너를 다시 만들 때 문제가 생길 수 있습니다.

실무에서는 아래 둘 중 하나를 많이 씁니다.

프로젝트 폴더 안에 ./n8n_data 같은 디렉터리를 두고 bind mount
Docker named volume 사용

예를 들어 named volume 방식은 이렇게 바꿀 수 있습니다.

services:
  n8n:
    image: n8nio/n8n:latest
    restart: unless-stopped
    ports:
      - "5678:5678"
    volumes:
      - n8n_data:/home/node/.n8n

volumes:
  n8n_data:

환경 변수는 어디까지 넣어야 하나

처음에는 TZ, GENERIC_TIMEZONE 정도만 있어도 됩니다. 하지만 외부 도메인과 프록시를 붙일 계획이라면 아래 값도 함께 점검하는 편이 좋습니다.

N8N_HOST
N8N_PORT
N8N_PROTOCOL
WEBHOOK_URL

예를 들어 도메인을 붙이고 HTTPS 뒤에서 운영할 때는 WEBHOOK_URL 이 맞지 않으면 웹훅 동작이 꼬일 수 있습니다. 설치는 됐는데 실제 자동화가 안 도는 이유가 여기서 많이 나옵니다.

실행 후 첫 확인 순서

컨테이너를 띄운 뒤에는 아래 순서로 확인하면 됩니다.

docker ps 로 컨테이너가 떠 있는지 확인
docker logs n8n --tail 100 으로 에러가 없는지 확인
브라우저에서 http://localhost:5678 또는 서버 주소로 접속
첫 설정 화면 또는 로그인 흐름이 정상인지 확인

외부 서버에 올렸다면 브라우저 접속만 보지 말고, 실제 웹훅이나 저장까지 확인해야 합니다. 화면이 열린다고 운영 준비가 끝난 것은 아닙니다.

업데이트는 이렇게 하는 편이 안전하다

가장 안전한 흐름은 단순합니다.

현재 docker compose.yml 과 데이터 폴더를 백업
사용 중인 이미지 태그를 확인
새 이미지 pull
컨테이너 재생성
접속과 주요 워크플로우 테스트

Compose 기준 예시는 아래처럼 잡을 수 있습니다.

docker compose pull
docker compose up -d

버전 변화를 조심하고 싶다면 latest 대신 명시적인 버전 태그를 쓰는 편이 더 안정적입니다.

백업은 무엇을 남겨야 하나

최소 백업 대상은 아래 두 가지입니다.

docker compose.yml
n8n 데이터가 들어 있는 볼륨 또는 폴더

로컬 폴더를 쓴다면 압축으로 백업할 수 있습니다.

tar -czf n8n-backup-$(date +%F).tar.gz docker-compose.yml n8n_data

중요한 건 “언젠가 해야지”가 아니라 업데이트 전에 먼저 백업하는 습관입니다.

자주 나는 오류

1. 포트 5678이 이미 사용 중이다

이 경우 다른 프로세스가 포트를 잡고 있을 수 있습니다. 포트를 바꾸거나, 기존 프로세스를 정리해야 합니다.

2. 재시작 후 데이터가 안 보인다

볼륨이나 bind mount 경로가 제대로 연결되지 않았을 가능성이 큽니다. 컨테이너만 다시 띄우고 데이터 경로를 빼먹은 경우가 많습니다.

3. 도메인을 붙였는데 웹훅이 이상하다

N8N_HOST, N8N_PROTOCOL, WEBHOOK_URL 조합이 실제 접속 주소와 다를 가능성이 큽니다. 리버스 프록시와 HTTPS 환경이면 이 부분을 먼저 확인해야 합니다.

FAQ

n8n Docker 설치는 `docker run` 과 Compose 중 무엇이 더 낫나

잠깐 테스트만 할 거라면 docker run 도 가능합니다. 하지만 실제로 계속 쓸 생각이라면 Compose가 훨씬 관리하기 쉽습니다.

n8n 업데이트 전에 꼭 백업해야 하나

네. 설정 파일과 데이터 저장 위치를 같이 백업하는 편이 좋습니다. 문제가 생기면 되돌아갈 수 있는 기준점이 있어야 하기 때문입니다.

n8n을 외부 도메인으로 운영할 때 가장 많이 놓치는 것은 무엇인가

WEBHOOK_URL 과 프록시 뒤의 실제 접속 주소 설정입니다. 설치 자체보다 URL 기준이 어긋나는 쪽에서 더 자주 문제가 납니다.

같이 보면 좋은 공식 문서

함께 읽으면 좋은 글

설치만 끝내고 멈추기보다, 데이터 저장과 업데이트 기준까지 같이 잡아두면 나중에 훨씬 덜 흔들립니다.