n8n 도커 설치 가이드｜5단계로 배우는 첫 워크플로우까지 세팅하는 방법

LINK&TEM GUIDE

n8n 도커 설치 5단계 가이드

도커 컴포즈로 설치하고, 웹훅으로 첫 워크플로우까지 완성합니다

📌 핵심 요약

n8n 도커 설치는 docker-compose.yml 파일 하나로 끝나는 작업입니다
데이터 볼륨을 미리 지정해야 컨테이너를 지워도 워크플로우가 사라지지 않습니다
타임존과 기본 인증 환경변수는 설치 직후 꼭 확인해야 합니다
설치가 끝나면 웹훅 트리거로 5분 안에 첫 워크플로우를 만들 수 있습니다
테스트는 SQLite로 시작해도 되지만, 운영 서버는 PostgreSQL 전환을 권장합니다

n8n 도커 설치가 필요한 이유
사전 준비: 도커와 도커 컴포즈 확인하기
docker-compose.yml로 n8n 도커 설치 진행하기
초기 설정: 관리자 계정과 기본 옵션
첫 워크플로우 만들기: 웹훅부터 알림까지
n8n 도커 설치 후 자주 하는 실수와 해결법

자동화 도구를 알아보다가 n8n 도커 설치까지 왔는데, 막상 명령어를 어디서부터 입력해야 할지 막막하셨을 겁니다.

이 글에서는 도커와 도커 컴포즈가 설치돼 있는지 확인하는 것부터, docker-compose.yml 작성, 컨테이너 실행, 초기 계정 설정, 그리고 웹훅으로 첫 워크플로우를 완성하는 과정까지 순서대로 다룹니다.

리눅스 서버든 맥이든 윈도우든 도커만 설치돼 있으면 이어지는 절차는 거의 동일합니다. 그럼 n8n 도커 설치부터 차근차근 시작해보겠습니다.

n8n 도커 설치가 필요한 이유

n8n은 400개가 넘는 서비스와 연동할 수 있는 오픈소스 워크플로우 자동화 도구입니다. Zapier나 Make처럼 노드를 드래그해서 연결하는 방식이지만, 셀프 호스팅이 가능해서 실행 횟수 제한 없이 무료로 쓸 수 있다는 점이 가장 큰 차이입니다.

설치 방법은 크게 두 가지입니다. npm으로 직접 설치하거나, 도커 컨테이너로 실행하는 방식입니다. npm 설치는 Node.js 버전 관리를 직접 해야 해서 의존성 충돌이 잦은 반면, n8n 도커 설치는 운영체제와 무관하게 격리된 환경에서 동일하게 동작합니다.

항목	npm 설치	도커 설치
사전 준비	Node.js 18 이상	도커만 있으면 됨
업데이트	npm update 및 의존성 재설치	이미지 태그만 교체
환경 격리	호스트 환경에 직접 영향	컨테이너 안에서 완전 분리
추천 대상	Node.js에 익숙한 개발자	서버 운영이 처음인 사용자

n8n은 거의 매주 마이너 버전을 새로 내놓을 만큼 업데이트가 잦은 프로젝트입니다. 도커로 설치해두면 이미지 태그 하나만 바꿔서 최신 버전으로 옮겨갈 수 있어서, 장기적으로는 도커 쪽이 관리 부담이 훨씬 적습니다.

🔍 Link&Tem Insight

n8n 공식 문서도 대부분의 셀프 호스팅 상황에서 도커 사용을 권장합니다. 운영체제 차이로 생기는 호환성 문제를 피할 수 있고, 데이터베이스나 환경변수 관리도 컨테이너 안에서 한 번에 처리되기 때문입니다. n8n 도커 설치를 선택하면 나중에 서버를 옮기거나 백업할 때도 볼륨 폴더 하나만 복사하면 되는 것도 장점입니다.

사전 준비: 도커와 도커 컴포즈 확인하기

n8n 도커 설치를 시작하기 전에 도커 엔진과 도커 컴포즈가 이미 설치돼 있는지부터 확인합니다. 터미널에 아래 명령어를 입력해보세요.

docker --version
docker compose version

두 명령어 모두 버전 정보가 출력되면 준비가 끝난 겁니다. 오류가 뜬다면 배포판에 맞는 설치 절차를 먼저 진행해야 합니다. 우분투 기준으로는 공식 저장소를 등록하고 apt install docker-ce docker-compose-plugin으로 설치하는 방식이 가장 안정적입니다.

💡 TIP

설치 직후에는 도커 명령어 앞에 매번 sudo를 붙여야 할 수 있습니다. 현재 계정을 docker 그룹에 추가하면(sudo usermod -aG docker $USER) 로그아웃 후 재접속할 때부터 sudo 없이 바로 사용할 수 있습니다.

📘 Docker 공식 설치 문서 보기

맥이나 윈도우라면 Docker Desktop 하나만 설치하면 엔진과 컴포즈가 함께 딸려옵니다. 리눅스 서버는 엔진과 컴포즈 플러그인을 따로 설치해야 하는 배포판도 있으니, 위 공식 문서에서 자기 환경에 맞는 절차를 확인하는 게 안전합니다.

⚠️ 주의할 점

메모리가 1GB 이하인 저사양 서버에서는 n8n 도커 설치 후 컨테이너가 자꾸 재시작되는 경우가 있습니다. n8n은 최소 2GB RAM을 권장하므로, 그 이하 서버라면 스왑 메모리를 추가하거나 인스턴스 사양을 올리는 걸 먼저 고려하세요.

docker-compose.yml로 n8n 도커 설치 진행하기

준비가 끝났다면 이제 실제로 n8n 도커 설치를 진행할 차례입니다. 작업 폴더를 하나 만들고 그 안에 docker-compose.yml 파일을 작성합니다.

mkdir n8n-docker && cd n8n-docker

아래 내용을 docker-compose.yml에 저장합니다. 핵심은 데이터가 저장될 볼륨을 /home/node/.n8n 경로에 연결하는 부분입니다. 이 경로가 n8n이 워크플로우와 인증 정보를 실제로 저장하는 곳이라, 여기를 호스트 폴더와 연결해두지 않으면 컨테이너를 삭제할 때 작업물이 통째로 사라집니다.

환경변수	역할
GENERIC_TIMEZONE	스케줄 노드 기준 시간대 (예: Asia/Seoul)
N8N_BASIC_AUTH_ACTIVE	에디터 접속 시 로그인 창 활성화 여부
N8N_ENCRYPTION_KEY	저장된 인증 정보를 암호화하는 키
WEBHOOK_URL	외부에서 웹훅을 호출할 실제 도메인 주소

파일 작성이 끝나면 아래 명령어로 컨테이너를 백그라운드에서 실행합니다.

docker compose up -d

정상적으로 실행되면 docker ps 명령어에서 n8n 컨테이너가 Up 상태로 표시됩니다. 로컬 환경이라면 브라우저에서 http://localhost:5678로, 원격 서버라면 서버 IP나 도메인의 5678 포트로 접속하면 초기 설정 화면이 나타납니다.

📘 n8n 공식 도커 설치 문서 보기

💡 TIP

N8N_ENCRYPTION_KEY는 openssl rand -hex 16 명령어로 랜덤 값을 만들어 넣는 걸 추천합니다. 이 키를 잃어버리거나 나중에 바꾸면 저장해둔 인증 정보를 전부 다시 입력해야 하니, 별도 메모장에 안전하게 백업해두세요.

초기 설정: 관리자 계정과 기본 옵션

브라우저로 처음 접속하면 관리자 계정을 만드는 화면이 뜹니다. 이메일, 이름, 비밀번호를 입력하면 되는데, 이 계정이 n8n 인스턴스 전체를 관리하는 유일한 관리자 계정이 됩니다.

계정을 만들고 나면 대시보드로 이동합니다. 여기서 먼저 확인할 게 세 가지 있습니다.

1. 타임존이 제대로 반영됐는지

docker-compose.yml에 GENERIC_TIMEZONE을 Asia/Seoul로 넣었다면, 오른쪽 위 설정 메뉴에서 시간이 한국 시간 기준으로 표시되는지 확인합니다. 스케줄 트리거를 쓸 예정이라면 이 값이 틀리면 새벽에 실행될 워크플로우가 낮에 실행되는 일이 생깁니다.

2. 커뮤니티 노드 설치 여부

설정 메뉴의 Community Nodes에서 필요한 서드파티 노드를 추가로 설치할 수 있습니다. 다만 셀프 호스팅 환경에서만 지원되는 기능이라, n8n 도커 설치로 셀프 호스팅한 경우에만 이 메뉴가 보입니다.

3. 데이터베이스 종류

환경변수를 따로 지정하지 않았다면 기본값은 SQLite입니다. 혼자 테스트하는 수준이라면 SQLite로도 충분하지만, 여러 명이 함께 쓰거나 워크플로우 실행 이력이 많아지면 PostgreSQL로 전환하는 걸 권장합니다.

📘 n8n 도커 컴포즈 운영 가이드 보기

첫 워크플로우 만들기: 웹훅부터 알림까지

n8n 도커 설치가 끝났으니 이제 실제로 워크플로우를 하나 만들어봅니다. 가장 빠르게 결과를 확인할 수 있는 조합은 Webhook 노드로 시작해서 알림을 보내는 흐름입니다.

1-1. Webhook 트리거 추가

새 워크플로우를 만들고 첫 노드로 Webhook을 선택합니다. HTTP Method는 POST로, Path는 원하는 문자열(예: order-created)로 지정합니다. n8n은 노드 하나당 Test URL과 Production URL 두 가지를 자동으로 생성합니다.

1-2. 테스트 데이터 확인

편집 화면에서 Listen for test event를 누르고, 터미널에서 curl로 Test URL에 요청을 보내봅니다. 테스트 웹훅은 등록 후 약 120초 동안만 열려 있으니, 요청은 그 안에 보내야 합니다.

curl -X POST [Test URL] -H "Content-Type: application/json" -d '{"name":"link&tem"}'

요청이 들어오면 편집 화면에 JSON 데이터가 그대로 표시됩니다. 이 구조를 확인해야 다음 노드에서 {{ $json.body.name }} 같은 표현식으로 값을 꺼내 쓸 수 있습니다.

1-3. 알림 노드 연결

Webhook 노드 뒤에 Slack이나 이메일 노드를 연결하고, 방금 확인한 필드값을 메시지 내용에 넣어줍니다. 저장 후 워크플로우 우측 상단의 Active 토글을 켜면, 이제부터는 Production URL로 들어오는 요청마다 자동으로 알림이 발송됩니다.

구분	Test URL	Production URL
용도	개발·디버깅	실제 서비스 연동
유효 시간	등록 후 약 120초	워크플로우 활성화 상태면 계속
조건	Listen for test event 클릭	워크플로우 저장 및 Active 켜짐

🔍 Link&Tem Insight

로컬 PC에 n8n 도커 설치를 한 경우, 외부 서비스는 localhost 주소로 접근할 수 없습니다. GitHub나 Shopify처럼 외부에서 웹훅을 호출해야 하는 서비스와 연동하려면 n8n의 터널 기능을 쓰거나, 고정 도메인이 있는 서버에 올려서 WEBHOOK_URL을 실제 도메인으로 지정해야 합니다.

n8n 도커 설치 후 자주 하는 실수와 해결법

n8n 도커 설치 과정에서 반복적으로 나오는 문제 몇 가지를 정리했습니다.

증상	원인	해결
재시작 후 워크플로우 사라짐	볼륨 미지정	/home/node/.n8n 경로 볼륨 연결
웹훅 응답이 계속 안 옴	Test URL 유효시간 초과	Listen for test event 다시 클릭
외부 서비스가 웹훅 못 찾음	WEBHOOK_URL 미설정	실제 도메인으로 환경변수 지정
인증 정보 복호화 오류	암호화 키 변경	N8N_ENCRYPTION_KEY 백업본 사용

⚠️ 주의할 점

docker-compose.yml에 볼륨 경로를 잘못 지정한 채로 며칠 운영하다가, 뒤늦게 고치겠다고 컨테이너를 재생성하면 그동안 쌓인 워크플로우가 전부 날아갑니다. n8n 도커 설치 직후에는 반드시 컨테이너를 껐다 켜보면서 데이터가 유지되는지부터 확인하는 습관을 들이세요.

📘 Docker Hub n8n 공식 이미지 보기