Docker 설치

n8n은 대부분의 셀프 호스팅(self-hosting) 시나리오에서 Docker 사용을 권장합니다. Docker는 깔끔하고 격리된 환경을 제공하여 운영체제 및 도구 체인의 호환성 문제를 방지하고, 데이터베이스 및 환경 관리를 더욱 간편하게 만들어 줍니다.

또한 Docker Compose를 사용해 Docker 내에서 n8n을 실행할 수도 있습니다. 다양한 아키텍처에 맞는 Docker Compose 설정 파일은 n8n-hosting GitHub 리포지토리에서 확인할 수 있습니다.

셀프 호스팅 전 알아둘 사항

n8n을 셀프 호스팅하려면 다음 분야에 대한 기술적 지식이 필요합니다:

• 서버 및 컨테이너 구성
• 애플리케이션 자원 관리 및 확장성 확보
• 서버와 애플리케이션 보안 강화
• n8n 설정 관리

n8n은 숙련된 사용자에게만 셀프 호스팅을 권장합니다. 잘못된 조작은 데이터 손실, 보안 취약점, 서비스 중단 등의 문제가 발생할 수 있습니다. 서버 관리 경험이 없다면 n8n Cloud 사용을 추천합니다.

아래의 동영상 가이드도 참고하실 수 있습니다:

전제 조건

시작하기 전에 먼저 Docker를 설치하세요:

• Mac, Windows, Linux용 Docker Desktop. Docker Desktop에는 Docker Engine과 Docker Compose가 포함되어 있습니다.
• Linux에서는 그래픽 인터페이스가 없는 서버나 Docker Desktop UI를 사용하지 않으려는 경우, Docker Engine과 Docker Compose를 개별 패키지로 설치할 수도 있습니다.

안정(stable) 버전과 베타(beta) 버전

n8n은 거의 매주 새로운 마이너(minor) 버전을 출시합니다. stable 버전은 프로덕션 환경에 적합하며, beta는 최신 릴리스로 아직 충분히 안정적이지 않을 수 있습니다. 문제를 보고하려면 커뮤니티 포럼을 이용해 주세요.

현재 stable 버전: 2.10.2
현재 beta 버전: 2.11.1

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 \
 docker.n8n.io/n8nio/n8n

이 명령어는 영구 데이터를 저장하기 위한 볼륨을 생성하고, 필요한 n8n 이미지를 다운로드한 후 다음과 같은 설정으로 컨테이너를 시작합니다:

• 컨테이너의 5678 포트를 호스트 머신에 매핑 및 노출합니다.
• 컨테이너의 시간대를 설정합니다:
  • TZ 환경 변수는 시스템 시간대를 설정하여 date 같은 스크립트 및 명령어의 출력을 제어합니다.
  • GENERIC_TIMEZONE 환경 변수는 Schedule Trigger 노드 등 스케줄 기반 노드에 올바른 시간대를 적용합니다.
• n8n 설정 파일에 보안적인 파일 권한을 강제 적용합니다.
• 런너(Runners)를 활성화합니다. 이는 n8n에서 작업을 실행하는 권장 방식입니다.
• n8n_data 볼륨을 /home/node/.n8n 디렉터리에 마운트하여 컨테이너 재시작 시에도 데이터를 유지합니다.

시작 후 브라우저에서 http://localhost:5678 에 접속하면 n8n을 사용할 수 있습니다.

PostgreSQL 사용하기

기본적으로 n8n은 자격 증명, 실행 기록, 워크플로 등을 SQLite에 저장합니다. 그러나 PostgreSQL도 지원하며, 환경 변수를 통해 다음과 같이 설정할 수 있습니다.

.n8n 디렉터리의 영구 저장 권장

PostgreSQL을 사용할 경우, n8n은 더 이상 .n8n 디렉터리에 SQLite 데이터베이스 파일을 저장하지 않습니다. 하지만 이 디렉터리는 여전히 암호화 키, 인스턴스 로그, 소스 코드 제어 기능 관련 자산 등 중요한 데이터를 포함하고 있습니다. 일부 요구사항은 우회할 수 있긴 합니다(예: N8N_ENCRYPTION_KEY 환경 변수 설정). 그러나 잠재적 문제를 방지하려면 이 디렉터리에 영구 볼륨을 계속 마운트하는 것이 좋습니다.

PostgreSQL과 함께 n8n을 사용하려면 다음 명령어를 실행하세요. <데이터베이스명>과 같은 꺾쇠괄호 안의 자리 표시자는 실제 값으로 바꿔주세요:

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=<데이터베이스명> \
 -e DB_POSTGRESDB_HOST=<호스트주소> \
 -e DB_POSTGRESDB_PORT=<포트번호> \
 -e DB_POSTGRESDB_USER=<사용자명> \
 -e DB_POSTGRESDB_SCHEMA=<스키마명> \
 -e DB_POSTGRESDB_PASSWORD=<비밀번호> \
 -v n8n_data:/home/node/.n8n \
 docker.n8n.io/n8nio/n8n

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

업데이트

n8n을 업데이트하려면 Docker Desktop에서 Images 탭으로 이동한 후, 상황에 맞는 메뉴에서 Pull을 선택하여 최신 n8n 이미지를 다운로드하세요:

또는 명령줄을 사용해 최신 버전이나 특정 버전을 가져올 수도 있습니다:

# 최신(stable) 버전 가져오기
docker pull docker.n8n.io/n8nio/n8n

# 특정 버전 가져오기
docker pull docker.n8n.io/n8nio/n8n:1.81.0

# next(불안정) 버전 가져오기
docker pull docker.n8n.io/n8nio/n8n:next

업데이트된 이미지를 가져온 후, 기존 n8n 컨테이너를 중지하고 다시 시작하세요. 명령줄에서도 가능합니다. 다음 명령어에서 <컨테이너ID>는 첫 번째 명령어로 확인한 실제 컨테이너 ID로 대체하세요:

# 컨테이너 ID 확인
docker ps -a

# <컨테이너ID> 컨테이너 중지
docker stop <컨테이너ID>

# <컨테이너ID> 컨테이너 제거
docker rm <컨테이너ID>

# 컨테이너 재시작
docker run --name=<컨테이너명> [옵션] -d docker.n8n.io/n8nio/n8n

Docker Compose로 업데이트하기

Docker Compose 파일을 사용해 n8n을 실행 중이라면, 다음 단계에 따라 업데이트하세요:

# docker compose 파일이 있는 디렉터리로 이동
cd <당신의_디렉터리>

# 최신 버전 가져오기
docker compose pull

# 기존 컨테이너 중지 및 제거
docker compose down

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

터널(Tunnel) 기능을 사용한 n8n

⚠️ 주의

이 기능은 로컬 개발 및 테스트 용도로만 사용해야 하며, 프로덕션 환경에는 적합하지 않습니다.

개발 도구

터널 기능은 로컬 개발을 위한 편의 도구이며, n8n 버전 업데이트에 따라 내부 구현이 변경될 수 있습니다.

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

⚠️ 다음 명령어는 n8n 소스 코드를 직접 실행할 때만 사용됩니다. Docker로 실행 중이라면 이 섹션을 건너뛰세요.

n8n 실행 방식에 따라 두 가지 터널 사용 방법이 있습니다:

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. cloudflared를 시작하여 host.docker.internal:5678(로컬 n8n)을 가리킵니다.
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

다음 단계

• Docker 이미지의 README 파일에서 Docker 설정에 대해 더 알아보세요.
• n8n을 어떻게 설정하고 확장할 수 있는지 확인하세요.
• 또는 n8n 사용법을 배워보세요: 빠른 시작 가이드를 시도해 보세요.