n8n:: docker로 n8n 설치하기

5월 30, 2026


n8n은 워크플로우 자동화 도구로, 다양한 API와 서비스를 연결해 반복 작업을 자동화할 수 있는 플랫폼입니다. Docker를 사용하면 로컬 PC나 서버에 비교적 간단하게 n8n을 설치하고 실행할 수 있습니다.

이 글에서는 Docker를 이용해 n8n을 실행하는 기본 방법과 Docker 볼륨을 사용해 데이터를 영구 저장하는 방법을 정리합니다.

1. 사전 준비

먼저 Docker가 설치되어 있어야 합니다.

Windows와 macOS에서는 Docker Desktop을 설치하면 되고, Linux 서버에서는 Docker Engine과 Docker Compose를 별도로 설치할 수 있습니다.

설치 여부는 다음 명령어로 확인할 수 있습니다.

docker --version

Docker Compose를 사용할 경우에는 다음 명령어도 확인합니다.

docker compose version
윈도우에서는 docker --version 명령어가 일반적으로 동작하지 않습니다.

[docker desktop]앱을 설치하면 wsl2에서 'docker --version'이 실행됩니다.



2. n8n 데이터 저장용 Docker 볼륨 생성

n8n은 워크플로우, 실행 기록, 자격 증명, 암호화 키 등 중요한 데이터를 저장합니다. 컨테이너는 삭제되거나 재생성될 수 있으므로, 데이터를 컨테이너 내부에만 저장하면 안 됩니다.

먼저 n8n_data라는 Docker 볼륨을 생성합니다.

docker volume create n8n_data

이 볼륨은 n8n의 데이터 디렉터리인 /home/node/.n8n에 연결됩니다.

3. Docker로 n8n 실행

다음 명령어로 n8n 컨테이너를 실행합니다.

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

실행 후 브라우저에서 다음 주소로 접속합니다.

http://localhost:5678

정상적으로 실행되면 n8n 초기 설정 화면이 표시됩니다.

4. 명령어 옵션 설명

위 Docker 실행 명령어의 주요 옵션은 다음과 같습니다.

옵션 설명
docker run 새 컨테이너를 실행합니다.
-it 터미널에서 상호작용 가능한 모드로 실행합니다.
--rm 컨테이너가 종료되면 자동으로 삭제합니다.
--name n8n 컨테이너 이름을 n8n으로 지정합니다.
-p 5678:5678 호스트의 5678 포트를 컨테이너의 5678 포트에 연결합니다.
-e GENERIC_TIMEZONE="Asia/Seoul" n8n의 스케줄 기반 노드에서 사용할 시간대를 설정합니다.
-e TZ="Asia/Seoul" 컨테이너 시스템 시간대를 설정합니다.
-e N8N_ENFORCE_SETTINGS_FILE_PERMISSIONS=true n8n 설정 파일 권한을 안전하게 강제합니다.
-e N8N_RUNNERS_ENABLED=true n8n의 Task Runner 실행 방식을 활성화합니다.
-v n8n_data:/home/node/.n8n Docker 볼륨을 n8n 데이터 디렉터리에 연결합니다.
docker.n8n.io/n8nio/n8n n8n 공식 Docker 이미지입니다.

5. --rm 옵션 사용 시 주의점

위 명령어에는 --rm 옵션이 포함되어 있습니다.

--rm

이 옵션은 컨테이너가 종료될 때 컨테이너 자체를 자동으로 삭제합니다. 하지만 n8n_data 볼륨은 별도로 유지되므로, 워크플로우와 설정 데이터는 삭제되지 않습니다.

다만 운영 환경에서는 컨테이너가 종료되어도 자동으로 다시 시작되도록 --restart unless-stopped 옵션을 사용하는 편이 더 적합합니다.

예를 들어 장기 실행용으로는 다음과 같이 실행할 수 있습니다.

docker run -d \
  --name n8n \
  --restart unless-stopped \
  -p 5678:5678 \
  -e GENERIC_TIMEZONE="Asia/Seoul" \
  -e TZ="Asia/Seoul" \
  -e N8N_ENFORCE_SETTINGS_FILE_PERMISSIONS=true \
  -e N8N_RUNNERS_ENABLED=true \
  -v n8n_data:/home/node/.n8n \
  docker.n8n.io/n8nio/n8n

여기서 -d는 컨테이너를 백그라운드에서 실행한다는 뜻입니다.

6. 컨테이너 중지 및 재시작

실행 중인 n8n 컨테이너를 확인합니다.

docker ps

컨테이너를 중지합니다.

docker stop n8n

--rm 옵션으로 실행했다면 중지 시 컨테이너가 삭제됩니다. 다시 실행하려면 동일한 docker run 명령어를 사용하면 됩니다.

볼륨은 그대로 유지되므로 기존 워크플로우와 설정은 보존됩니다.

7. n8n 데이터 백업

n8n_data 볼륨을 백업하려면 임시 컨테이너를 사용해 볼륨 내용을 로컬 디렉터리로 복사할 수 있습니다.

현재 디렉터리에 n8n_backup 폴더를 만들고 백업하려면 다음 명령어를 실행합니다.

mkdir -p n8n_backup

docker run --rm \
  -v n8n_data:/source \
  -v $(pwd)/n8n_backup:/backup \
  ubuntu \
  cp -r /source/. /backup/

백업된 파일은 현재 디렉터리의 n8n_backup 폴더에 저장됩니다.

Windows PowerShell에서는 $(pwd) 대신 ${PWD}를 사용할 수 있습니다.

docker run --rm `
  -v n8n_data:/source `
  -v ${PWD}/n8n_backup:/backup `
  ubuntu `
  cp -r /source/. /backup/

8. Docker 볼륨 공유 시 주의사항

Docker 볼륨은 여러 컨테이너에서 연결할 수 있습니다. 예를 들어 백업 전용 컨테이너가 n8n_data 볼륨을 읽어서 데이터를 복사하는 방식은 유용합니다.

하지만 n8n의 실제 데이터 볼륨을 다른 애플리케이션의 데이터 디렉터리처럼 사용하는 것은 권장되지 않습니다.

예를 들어 다음과 같은 방식은 피하는 것이 좋습니다.

docker run -v n8n_data:/data postgres:13

이 명령어는 PostgreSQL 컨테이너에 n8n 데이터 볼륨을 연결하는 형태입니다. 하지만 n8n 데이터와 PostgreSQL 데이터 구조는 서로 다르기 때문에 실제 마이그레이션 방법으로 적절하지 않습니다.

볼륨 공유는 다음과 같은 목적에 사용하는 것이 안전합니다.

  • n8n 데이터 백업
  • 임시 복사 작업
  • 마이그레이션 전 데이터 추출
  • 읽기 전용 분석 작업

특히 여러 컨테이너가 같은 볼륨에 동시에 쓰기 작업을 하면 데이터 충돌이나 손상이 발생할 수 있습니다.

9. 운영 환경에서는 Docker Compose 권장

간단한 로컬 테스트는 docker run만으로 충분합니다. 하지만 서버에서 장기 운영할 경우에는 Docker Compose를 사용하는 것이 관리하기 쉽습니다.

예를 들어 다음과 같이 compose.yaml 파일을 작성할 수 있습니다.

services:
  n8n:
    image: docker.n8n.io/n8nio/n8n
    container_name: n8n
    restart: unless-stopped
    ports:
      - "5678:5678"
    environment:
      - GENERIC_TIMEZONE=Asia/Seoul
      - TZ=Asia/Seoul
      - N8N_ENFORCE_SETTINGS_FILE_PERMISSIONS=true
      - N8N_RUNNERS_ENABLED=true
    volumes:
      - n8n_data:/home/node/.n8n

volumes:
  n8n_data:

실행은 다음 명령어를 사용합니다.

docker compose up -d

중지는 다음과 같이 할 수 있습니다.

docker compose stop

완전히 내리려면 다음 명령어를 사용합니다.

docker compose down

단, docker compose down -v를 실행하면 볼륨까지 삭제될 수 있으므로 주의해야 합니다.

10. 정리

Docker로 n8n을 설치할 때 핵심은 다음과 같습니다.

  1. n8n_data Docker 볼륨을 생성한다.
  2. 해당 볼륨을 /home/node/.n8n에 마운트한다.
  3. 시간대는 GENERIC_TIMEZONE과 TZ로 설정한다.
  4. 운영 환경에서는 --rm보다 --restart unless-stopped 또는 Docker Compose를 사용하는 것이 좋다.
  5. n8n_data 볼륨에는 워크플로우, 설정, 자격 증명, 암호화 키 등 중요한 데이터가 포함되므로 반드시 백업한다.

간단한 테스트 목적이라면 docker run 방식으로 충분하지만, 실제 운영 환경에서는 Docker Compose, HTTPS 설정, 백업 정책, 데이터베이스 구성까지 함께 고려하는 것이 좋습니다.

댓글 쓰기 · 수정

0 댓글