n8n 설치와 환경 구축 — Docker로 5분 만에 시작하기

Docker만 있으면 5분이면 n8n을 띄울 수 있다. 복잡한 의존성 설치도, 언어 런타임도 필요 없다. docker compose up -d 한 줄이면 끝이다.

설치 방법 선택하기

n8n을 실행하는 방법은 크게 세 가지다.

방법	난이도	비용	적합한 대상
n8n Cloud	⭐	월 $24~	서버 관리 없이 바로 쓰고 싶은 사람
Docker (셀프호스팅)	⭐⭐	서버 비용만	데이터 통제 + 무제한 실행이 필요한 사람
npm 직접 설치	⭐⭐⭐	서버 비용만	Node.js 환경이 이미 있는 개발자

이 시리즈에서는 Docker 방식을 기준으로 진행한다. 가장 깔끔하고 재현 가능하며, 프로덕션 환경에서도 그대로 쓸 수 있기 때문이다.

💡 n8n Cloud를 쓰려면? n8n.io에서 가입하면 바로 사용할 수 있다. 설치 과정이 필요 없으므로 이 글의 "첫 접속" 섹션부터 읽으면 된다.

사전 준비: Docker 설치

Docker가 이미 설치되어 있다면 이 섹션을 건너뛰자.

macOS

Docker Desktop for Mac 다운로드
.dmg 파일 실행 → Applications 폴더로 드래그
Docker Desktop 실행 → 상태바에 🐳 아이콘 확인

Windows

Docker Desktop for Windows 다운로드
설치 마법사 실행 (WSL 2 백엔드 권장)
재부팅 후 Docker Desktop 실행

Linux (Ubuntu/Debian)

# Docker 공식 설치 스크립트
curl -fsSL https://get.docker.com -o get-docker.sh
sudo sh get-docker.sh

# 현재 사용자를 docker 그룹에 추가 (sudo 없이 docker 사용)
sudo usermod -aG docker $USER

# 로그아웃 후 재로그인 필요

설치 확인

docker --version
# Docker version 27.x.x, build xxxxx

docker compose version
# Docker Compose version v2.x.x

두 명령어 모두 버전이 출력되면 준비 완료다.

Docker Compose로 n8n 설치하기

1단계: 프로젝트 폴더 생성

mkdir ~/n8n && cd ~/n8n

2단계: docker-compose.yml 작성

아래 내용을 docker-compose.yml 파일로 저장한다.

version: "3.8"

services:
  n8n:
    image: n8nio/n8n:latest
    container_name: n8n
    restart: unless-stopped
    ports:
      - "5678:5678"
    environment:
      # 기본 설정
      - N8N_HOST=localhost
      - N8N_PORT=5678
      - N8N_PROTOCOL=http
      - WEBHOOK_URL=http://localhost:5678/
      # 타임존 (한국)
      - GENERIC_TIMEZONE=Asia/Seoul
      - TZ=Asia/Seoul
      # 보안: 기본 인증 활성화
      - N8N_BASIC_AUTH_ACTIVE=true
      - N8N_BASIC_AUTH_USER=admin
      - N8N_BASIC_AUTH_PASSWORD=change-me-please
      # 데이터 암호화 키 (반드시 변경!)
      - N8N_ENCRYPTION_KEY=your-random-encryption-key-here
    volumes:
      - n8n_data:/home/node/.n8n

volumes:
  n8n_data:
    driver: local

각 설정의 의미를 표로 정리한다.

환경 변수	설명	기본값
`N8N_HOST`	n8n이 바인딩할 호스트	`localhost`
`N8N_PORT`	웹 UI 포트	`5678`
`WEBHOOK_URL`	외부에서 Webhook 접근 시 사용할 URL	자동 감지
`GENERIC_TIMEZONE`	워크플로우 실행 시간 기준	`America/New_York`
`N8N_BASIC_AUTH_ACTIVE`	기본 인증(아이디/비밀번호) 활성화	`false`
`N8N_ENCRYPTION_KEY`	Credential 암호화 키	자동 생성

🔒 보안 주의: N8N_BASIC_AUTH_PASSWORD와 N8N_ENCRYPTION_KEY는 반드시 안전한 값으로 변경해야 한다. 특히 N8N_ENCRYPTION_KEY는 한 번 설정하면 변경하기 어려우므로 신중하게 생성하자.

안전한 키 생성 방법:

# OpenSSL로 랜덤 문자열 생성
openssl rand -hex 32
# 출력 예: 4a7d1ed414474e4033ac29ccb8653d9b...

3단계: n8n 실행

docker compose up -d

출력:

[+] Running 2/2
 ✔ Volume "n8n_n8n_data"  Created
 ✔ Container n8n          Started

4단계: 실행 확인

# 컨테이너 상태 확인
docker compose ps

NAME   IMAGE              STATUS          PORTS
n8n    n8nio/n8n:latest   Up 10 seconds   0.0.0.0:5678->5678/tcp

STATUS가 Up이면 성공이다. 🎉

첫 접속 — 계정 생성

브라우저에서 http://localhost:5678 을 열자.

첫 접속 시 계정 생성 화면이 나타난다.

이메일: 관리자 이메일 입력
이름: 표시 이름
비밀번호: 8자 이상 권장

계정을 생성하면 바로 n8n 대시보드로 이동한다.

💡 n8n Cloud 사용자: 가입 후 로그인하면 동일한 대시보드가 나타난다.

n8n 대시보드 살펴보기

로그인하면 워크플로우 목록 화면이 나타난다.

아직 워크플로우가 없어서 빈 화면이지만, 주요 메뉴를 미리 파악해두자.

메뉴	위치	설명
Workflows	좌측 상단	모든 워크플로우 목록
Credentials	좌측 메뉴	외부 서비스 인증 정보 관리
Executions	좌측 메뉴	워크플로우 실행 기록
Variables	좌측 메뉴	전역 변수 (환경 변수)
+ Add Workflow	우측 상단	새 워크플로우 생성

자주 쓰는 Docker 명령어

n8n을 Docker로 운영할 때 필요한 명령어를 정리한다.

# n8n 시작
docker compose up -d

# n8n 중지
docker compose down

# n8n 로그 확인 (실시간)
docker compose logs -f n8n

# n8n 재시작
docker compose restart n8n

# n8n 업데이트 (최신 버전으로)
docker compose pull
docker compose up -d

# n8n 버전 확인
docker exec n8n n8n --version

데이터 백업

n8n의 모든 데이터(워크플로우 정의, Credential, 실행 로그)는 Docker 볼륨 n8n_data에 저장된다.

# 볼륨 위치 확인
docker volume inspect n8n_n8n_data

# 수동 백업 (워크플로우 JSON 내보내기)
docker exec n8n n8n export:workflow --all --output /home/node/.n8n/backups/
docker cp n8n:/home/node/.n8n/backups/ ./n8n-backup-$(date +%Y%m%d)/

💡 프로덕션 팁: SQLite 대신 PostgreSQL을 사용하면 백업과 성능 모두 좋아진다. 이 내용은 28편(성능 최적화)에서 다룬다.

npm으로 직접 설치 (대안)

Docker 없이 Node.js 환경에서 직접 설치할 수도 있다. 간단한 테스트 용도로 유용하다.

요구사항

Node.js 18.x 이상

설치 및 실행

# 전역 설치
npm install -g n8n

# 실행
n8n start

# 또는 npx로 설치 없이 바로 실행
npx n8n

브라우저에서 http://localhost:5678을 열면 Docker 방식과 동일한 화면이 나타난다.

⚠️ 주의: npm 직접 설치는 테스트·학습 용도로는 좋지만, 프로덕션에서는 Docker 방식을 강력히 권장한다. 업데이트, 격리, 재현성 모든 면에서 Docker가 우수하다.

프로덕션 환경을 위한 고급 docker-compose.yml

실제 서비스 환경에서는 PostgreSQL을 함께 띄우는 것이 좋다. 참고용으로 제공한다.

version: "3.8"

services:
  n8n:
    image: n8nio/n8n:latest
    container_name: n8n
    restart: unless-stopped
    ports:
      - "5678:5678"
    environment:
      - N8N_HOST=0.0.0.0
      - N8N_PORT=5678
      - N8N_PROTOCOL=https
      - WEBHOOK_URL=https://n8n.yourdomain.com/
      - GENERIC_TIMEZONE=Asia/Seoul
      - TZ=Asia/Seoul
      - N8N_ENCRYPTION_KEY=${N8N_ENCRYPTION_KEY}
      # PostgreSQL 연결
      - DB_TYPE=postgresdb
      - DB_POSTGRESDB_HOST=postgres
      - DB_POSTGRESDB_PORT=5432
      - DB_POSTGRESDB_DATABASE=n8n
      - DB_POSTGRESDB_USER=n8n
      - DB_POSTGRESDB_PASSWORD=${DB_PASSWORD}
      # 실행 데이터 정리 (30일)
      - EXECUTIONS_DATA_PRUNE=true
      - EXECUTIONS_DATA_MAX_AGE=720
    volumes:
      - n8n_data:/home/node/.n8n
    depends_on:
      postgres:
        condition: service_healthy

  postgres:
    image: postgres:16-alpine
    container_name: n8n-postgres
    restart: unless-stopped
    environment:
      - POSTGRES_DB=n8n
      - POSTGRES_USER=n8n
      - POSTGRES_PASSWORD=${DB_PASSWORD}
    volumes:
      - postgres_data:/var/lib/postgresql/data
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U n8n"]
      interval: 10s
      timeout: 5s
      retries: 5

volumes:
  n8n_data:
  postgres_data:

.env 파일을 별도로 만들어 민감한 값을 관리한다:

# .env
N8N_ENCRYPTION_KEY=your-random-encryption-key-here
DB_PASSWORD=your-strong-db-password

이 구성에 대한 자세한 설명은 27편(Credential 관리와 보안)과 28편(성능 최적화)에서 다룬다.

📝 정리

[x] 설치 방법 3가지: n8n Cloud, Docker(권장), npm 직접 설치
[x] Docker 설치: docker-compose.yml 한 파일 + docker compose up -d 한 줄
[x] 필수 설정: 타임존(Asia/Seoul), 암호화 키, 인증 설정
[x] 접속: http://localhost:5678에서 계정 생성 후 바로 사용
[x] 운영 명령어: 시작, 중지, 로그, 업데이트, 백업

다음 편 예고

3편: n8n UI 완전 정복 — 캔버스, 실행 로그, 데이터 뷰

n8n의 시각적 에디터를 구석구석 탐험한다. 노드 추가·연결·삭제, 데이터를 3가지 뷰(JSON/Table/Schema)로 확인하는 법, 그리고 알아두면 빨라지는 단축키까지.