Docker로 n8n 설치

Docker로 n8n 설치 (Install with Docker)

n8n을 셀프호스팅할 때 대부분의 요구에 가장 권장되는 방법이 Docker예요. 깨끗하고 격리된 환경을 제공하고, 운영체제나 도구 호환성 문제를 피할 수 있으며, 데이터베이스와 환경 관리가 훨씬 단순해집니다.

출처: 공식문서 - Install with Docker

⚠️ 주의: 이 문서의 내용은 다소 오래되었습니다. 지금은 Docker Compose로 설치를 권장 가이드로 참고하세요.

셀프호스팅을 시작하기 전에

n8n을 셀프호스팅하려면 다음 기술 지식이 필요합니다.

  • 서버와 컨테이너 설정 및 구성
  • 애플리케이션 리소스 관리와 스케일링
  • 서버와 애플리케이션 보안
  • n8n 설정

n8n은 셀프호스팅을 전문가 사용자에게 권장해요. 잘못 설정하면 데이터 손실, 보안 문제, 다운타임이 발생할 수 있습니다. 서버 관리를 경험해 본 적이 없다면 n8n Cloud를 이용하는 편이 안전합니다.

n8n 또한 Docker Compose와 함께 사용할 수 있고, 다양한 아키텍처용 Docker Compose 구성은 n8n-hosting 저장소에서 찾을 수 있어요.

사전 요구사항

시작 전에 Docker를 설치하세요.

  • Docker Desktop — Mac, Windows, Linux에서 사용 가능. Docker Engine과 Docker Compose를 포함합니다.
  • Docker Engine과 Docker Compose — Linux용 별도 패키지로도 제공됩니다. 그래픽 환경이 없는 Linux 머신이나 Docker Desktop UI를 원하지 않을 때 사용하세요.

Stable과 Beta 버전

n8n은 대부분의 주에 새로운 마이너 버전을 릴리스합니다. stable 버전은 프로덕션용입니다. beta는 가장 최근 릴리스로 불안정할 수 있습니다. 문제를 보고하려면 포럼을 이용하세요.

현재 stable: 2.38.7 / 현재 beta: 2.39.4

n8n 시작하기

터미널에서 아래 명령을 실행하되, <YOUR_TIMEZONE> 자리 표시자는 당신의 타임존으로 바꾸세요.

docker volume create n8n_data

docker run -it --rm \
 --name n8n \
 -p 5678:5678 \
 -e GENERIC_TIMEZONE="<YOUR_TIMEZONE>" \
 -e TZ="<YOUR_TIMEZONE>" \
 -e N8N_ENFORCE_SETTINGS_FILE_PERMISSIONS=true \
 -e N8N_RUNNERS_ENABLED=true \
 -v n8n_data:/home/node/.n8n \
 n8nio/n8n

이 명령은 영속 데이터를 저장할 볼륨을 만들고 필요한 n8n 이미지를 받아온 뒤, 다음 설정으로 컨테이너를 시작합니다.

  • 호스트의 포트 5678을 매핑해 노출합니다.
  • 컨테이너의 타임존을 설정합니다.
  • n8n 설정 파일의 보안 권한을 강제합니다.
  • n8n에서 작업을 실행하는 권장 방식인 task runners를 활성화합니다.
  • n8n_data 볼륨을 /home/node/.n8n 디렉터리에 마운트해 컨테이너를 재시작해도 데이터가 유지되게 합니다.

⚠️ 기능 가용성: N8N_RUNNERS_ENABLED는 n8n 2.0부터 더 이상 사용되지 않습니다(Deprecated). 더 이상 설정할 필요가 없으며, n8n 1.x에서는 task runners를 활성화하려면 true로 설정해야 했습니다.

실행되면 브라우저에서 http://localhost:5678 을 열어 n8n에 접속합니다.

PostgreSQL과 함께 사용하기

기본적으로 n8n은 SQLite를 사용해 자격 증명[^1], 과거 실행 기록, 워크플로를 저장합니다. n8n은 PostgreSQL도 지원하며 아래 환경 변수로 설정할 수 있어요.

💡 .n8n 디렉터리 영속화는 여전히 권장: PostgreSQL을 쓸 때 n8n이 SQLite 데이터베이스 파일을 위해 .n8n 디렉터리를 쓸 필요는 없지만, 이 디렉터리에는 암호화 키, 인스턴스 로그, 소스 컨트롤 기능 에셋 같은 중요한 데이터가 여전히 들어 있어요. 일부 요구사항은 우회할 수 있지만(예: N8N_ENCRYPTION_KEY 설정), 문제를 피하려면 이 디렉터리에 영속 볼륨을 계속 매핑하는 것이 좋습니다.

PostgreSQL과 함께 n8n을 사용하려면 아래 명령을 실행하되, 꺾쇠 안의 자리 표시자(예: <POSTGRES_USER>)를 실제 값으로 바꾸세요.

docker volume create n8n_data

docker run -it --rm \
 --name n8n \
 -p 5678:5678 \
 -e GENERIC_TIMEZONE="<YOUR_TIMEZONE>" \
 -e TZ="<YOUR_TIMEZONE>" \
 -e N8N_ENFORCE_SETTINGS_FILE_PERMISSIONS=true \
 -e N8N_RUNNERS_ENABLED=true \
 -e DB_TYPE=postgresdb \
 -e DB_POSTGRESDB_DATABASE=<POSTGRES_DATABASE> \
 -e DB_POSTGRESDB_HOST=<POSTGRES_HOST> \
 -e DB_POSTGRESDB_PORT=<POSTGRES_PORT> \
 -e DB_POSTGRESDB_USER=<POSTGRES_USER> \
 -e DB_POSTGRESDB_SCHEMA=<POSTGRES_SCHEMA> \
 -e DB_POSTGRESDB_PASSWORD=<POSTGRES_PASSWORD> \
 -v n8n_data:/home/node/.n8n \
 n8nio/n8n

PostgreSQL용 완전한 docker-compose 파일은 n8n hosting 저장소에서 찾을 수 있어요.

업데이트하기

n8n을 업데이트하려면 Docker Desktop의 Images 탭에서 컨텍스트 메뉴의 Pull을 선택해 최신 n8n 이미지를 받아오면 됩니다. 명령줄로도 최신 또는 특정 버전을 받아올 수 있어요.

# 최신(안정) 버전 받아오기
docker pull n8nio/n8n

# 특정 버전 받아오기
docker pull n8nio/n8n:1.81.0

# next(불안정) 버전 받아오기
docker pull n8nio/n8n:next

업데이트된 이미지를 받은 뒤에는 n8n 컨테이너를 멈추고 다시 시작하세요. 명령줄로도 가능합니다. 아래 명령의 <container_id>는 첫 명령에서 찾은 컨테이너 ID로 바꾸세요.

# 컨테이너 ID 찾기
docker ps -a

# <container_id> 컨테이너 멈추기
docker stop <container_id>

# <container_id> 컨테이너 제거하기
docker rm <container_id>

# 컨테이너 시작하기
docker run --name=<container_name> [options] -d n8nio/n8n

Docker Compose 업데이트

Docker Compose 파일로 n8n을 실행 중이라면 다음 단계로 업데이트합니다.

# compose 파일이 있는 디렉터리로 이동
cd </path/to/your/compose/file/directory>

# 최신 버전 받아오기
docker compose pull

# 이전 버전 멈추고 제거
docker compose down

# 컨테이너 시작
docker compose up -d

웹훅용 터널 사용하기

⚠️ 주의: 이 기능은 로컬 개발·테스트용입니다. 프로덕션에서 사용하기에는 안전하지 않습니다.

⚠️ 개발 도구 참고: 터널 기능은 로컬 개발을 위한 편의 도구로, 내부 구현이 n8n 버전에 따라 바뀔 수 있습니다.

GitHub 같은 외부 서비스의 트리거 노드에 웹훅을 사용하려면 n8n이 웹에서 접근 가능해야 해요. n8n은 cloudflared를 사용하는 터널 서비스를 제공해 웹의 요청을 로컬 n8n 인스턴스로 리다이렉트합니다. 터널이 작동하려면 Docker가 설치되어 있어야 합니다.

전체 스택 (Full stack)

n8n과 cloudflared를 컨테이너에서 함께 실행합니다. 터널 URL이 시작 시 출력되고 모든 것이 자동으로 연결됩니다.

pnpm stack --tunnel

서비스만 (Services only)

pnpm dev나 pnpm start로 n8n을 로컬에서 실행하는 편이라면, cloudflared를 독립 서비스로 시작할 수 있어요.

# 터미널 1: cloudflared 터널 서비스 시작
pnpm --filter n8n-containers services --services cloudflared

# 터미널 2: n8n 로컬 실행
pnpm dev

services 명령은:

  1. host.docker.internal:5678(당신의 로컬 n8n)을 가리키는 cloudflared를 시작합니다.
  2. cloudflared의 메트릭 엔드포인트에서 공개 터널 URL을 가져옵니다.
  3. WEBHOOK_URL과 N8N_PROXY_HOPS=1을 담은 .env 파일을 packages/cli/bin/.env에 씁니다.
  4. pnpm dev와 pnpm start는 dotenv를 사용해 그 .env를 자동으로 읽어들입니다.

작업이 끝나면 정리하세요.

pnpm --filter n8n-containers services:clean

다음 단계

[^1]: n8n에서 크레덴셜(자격 증명)은 특정 앱과 서비스에 연결하기 위한 인증 정보를 저장합니다. (사용자 이름과 비밀번호, API 키, OAuth 시크릿 등) 크레덴셜을 만들고 나면 연결된 앱 노드를 사용해 그 서비스와 상호작용할 수 있습니다.

더 알아보기 (Learn more)