n8n 설치 방법 도커부터 오류 해결까지 완벽 가이드

목차

• n8n 설치 전 필수 준비사항

   

• 가장 안정적인 운영 환경 구축: n8n Docker 설치

   

• 개발 및 테스트용: n8n 로컬 설치 (npm)

   

• 설치 그 이상: n8n 초기 설정 및 운영 팁

   

• 결론

   

• 자주 묻는 질문 (FAQ)

   

매일 반복되는 업무, 이제는 AI 기반 자동화에 맡겨보는 건 어떨까요? Zapier와 같은 유료 툴의 월 수십만 원 비용이 부담스러웠다면, 오픈소스 자동화 툴 n8n으로 나만의 자동화 워크플로우를 구축하여 생산성을 극대화해 보세요.

n8n은 코딩 지식이 거의 없어도 수백 개의 다양한 웹 서비스와 API를 연결하여 원하는 작업을 자동으로 처리하게 만들 수 있는 강력한 워크플로우 자동화 도구입니다. 다른 자동화 툴과 비교했을 때 n8n이 가진 가장 큰 장점은 바로 오픈소스라는 점입니다. 이를 통해 개인 서버나 클라우드에 직접 설치(셀프 호스팅)하여 월별 비용 부담 없이 사용할 수 있으며, 모든 데이터를 외부 서비스에 맡기지 않고 완벽하게 통제할 수 있는 데이터 주권을 확보할 수 있습니다. 또한, 소스 코드가 공개되어 있어 원하는 기능을 직접 추가하거나 수정할 수 있는 높은 커스터마이징 자유도를 제공합니다.

이 글에서는 가장 안정적이고 권장되는 n8n 설치 방법인 n8n docker 설치 방법부터, 간단한 테스트를 위한 n8n 로컬 설치, 설치 후 필수적인 n8n 초기 설정 과정, 그리고 초보자가 흔히 겪는 n8n 설치 오류 해결 팁까지, 2025년 최신 버전 기준으로 모든 것을 단계별로 상세히 안내합니다. 이 글 하나로 n8n 설치의 모든 과정을 완벽하게 마스터할 수 있을 것입니다.

n8n 설치 전 필수 준비사항

본격적인 n8n 설치 방법을 알아보기 전에, n8n이 원활하게 동작할 수 있는 환경을 준비해야 합니다. 복잡한 과정은 아니지만, 아래의 시스템 요구사항과 필수 소프트웨어를 미리 확인하고 준비하면 설치 과정을 훨씬 더 순조롭게 진행할 수 있습니다.

시스템 요구사항

n8n은 비교적 가벼운 프로그램이지만, 실행하는 워크플로우의 복잡성과 개수에 따라 필요한 사양이 달라집니다.

• 최소 사양 (간단한 워크플로우 1~10개):

  • CPU: 1 vCPU

  • RAM: 1 GB

  • 디스크: 20 GB 이상의 여유 공간

• 권장 사양 (복잡한 워크플로우 및 다수 사용자):

  • CPU: 2 vCPU 이상

  • RAM: 4 GB 이상

  • 디스크: 50 GB 이상의 여유 공간

필수 소프트웨어 설치

n8n을 가장 안정적으로 운영하기 위해서는 Docker 환경이 필수적입니다. 이 가이드 역시 Docker를 중심으로 설명합니다.

• Docker 및 Docker Compose
  Docker는 n8n을 격리된 환경인 ‘컨테이너’에서 실행하여, 내 컴퓨터나 서버의 다른 프로그램과 충돌하는 것을 막고 안정성과 이식성을 보장하는 가장 중요한 도구입니다. Docker Compose는 Docker의 설정을 파일 하나로 간단하게 관리하게 해주는 보조 도구입니다. 아래 링크를 통해 자신의 운영체제에 맞는 Docker Desktop을 설치하세요. Docker Desktop에는 Docker Compose가 기본적으로 포함되어 있습니다.

  • Windows용 Docker Desktop 설치

  • macOS용 Docker Desktop 설치

  • Linux (Ubuntu 기준) 설치 명령어: 터미널을 열고 아래 명령어를 순서대로 입력하세요.

  sudo apt-get update
  sudo apt-get install docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin

• (선택) Node.js 및 npm
  Docker가 아닌, 임시 테스트 목적으로 컴퓨터에 직접 n8n 로컬 설치를 원하는 경우에만 필요합니다. 실제 운영 환경에서는 권장하지 않습니다.

  • Node.js 공식 홈페이지

가장 안정적인 운영 환경 구축: n8n Docker 설치

실제 서비스를 운영하거나 중요한 자동화 워크플로우를 장기간 실행할 계획이라면, 단연 n8n docker 설치 방법을 사용해야 합니다. Docker Compose를 사용하면 n8n 실행에 필요한 모든 설정(네트워크, 데이터 저장 공간, 환경 변수)을 docker-compose.yml이라는 단 하나의 파일로 명확하게 관리할 수 있습니다. 이는 향후 n8n 버전을 업데이트하거나 설정을 변경하고, 데이터를 백업할 때 매우 편리하며 운영 환경의 안정성을 크게 높여줍니다.

단계별 설치 가이드

1. 데이터 영속성을 위한 폴더 생성

n8n의 워크플로우, API 키 등 모든 중요한 데이터는 컨테이너가 아닌, 우리 컴퓨터의 실제 폴더에 저장해야 합니다. 이렇게 해야 n8n을 업데이트하거나 컨테이너를 실수로 삭제해도 데이터가 안전하게 보존됩니다.

터미널(Windows의 경우 PowerShell 또는 CMD)을 열고 아래 명령어를 입력하여 데이터를 저장할 폴더를 생성합니다.

mkdir ~/n8n-data

이 명령어는 홈 디렉터리에 n8n-data라는 폴더를 생성합니다. 원하는 경우 다른 경로에 생성해도 무방합니다.

2. docker-compose.yml 파일 작성

이제 n8n 컨테이너의 모든 설정을 정의하는 설계도, docker-compose.yml 파일을 만들 차례입니다. 텍스트 편집기를 열어 아래 내용을 그대로 복사하여 docker-compose.yml이라는 이름으로 저장하세요. 이 파일은 방금 만든 n8n-data 폴더가 아닌, 작업을 진행할 별도의 폴더에 저장하는 것이 좋습니다.

version: '3.7'

services:
  n8n:
    image: docker.n8n.io/n8nio/n8n
    restart: always
    ports:
      - "127.0.0.1:5678:5678"
    environment:
      - N8N_HOST=localhost
      - N8N_PORT=5678
      - N8N_PROTOCOL=http
      - NODE_ENV=production
      - WEBHOOK_URL=http://localhost:5678/
      - GENERIC_TIMEZONE=Asia/Seoul
      - N8N_ENCRYPTION_KEY='YOUR_SUPER_SECRET_ENCRYPTION_KEY' # 매우 중요한 설정!
    volumes:
      - ~/n8n-data:/home/node/.n8n

3. 주요 환경 변수 상세 설명

docker-compose.yml 파일의 environment 섹션은 n8n의 동작을 제어하는 매우 중요한 설정들입니다.

환경 변수	설명
GENERIC_TIMEZONE	워크플로우의 시간 기반 트리거(예: 매일 아침 9시에 실행)가 한국 시간(Asia/Seoul)에 맞춰 정확하게 동작하도록 설정합니다. 해외 서버를 사용하더라도 이 설정을 통해 한국 시간 기준으로 작업할 수 있습니다.
N8N_ENCRYPTION_KEY	가장 중요한 설정입니다. 워크플로우에 저장되는 DB 비밀번호, API 키 등 모든 민감한 정보를 암호화하는 비밀 키입니다. 보안을 위해 반드시 'YOUR_SUPER_SECRET_ENCRYPTION_KEY' 부분을 아무도 예측할 수 없는 긴 문자열로 변경해야 합니다. 터미널에서 openssl rand -hex 32 명령어를 실행하여 생성된 값을 사용하는 것을 권장합니다. 이 키를 분실하면 암호화된 데이터를 절대 복구할 수 없으므로, 안전한 곳에 반드시 백업해두어야 합니다.
volumes	~/n8n-data:/home/node/.n8n 설정은 1번 단계에서 생성한 내 컴퓨터의 폴더(~/n8n-data)와 n8n 컨테이너 내부의 데이터 폴더(/home/node/.n8n)를 연결하는 역할을 합니다. 이를 통해 데이터가 영구적으로 보존됩니다.
ports	127.0.0.1:5678:5678 설정은 보안을 위해 현재 서버 내부(localhost)에서만 n8n에 접속할 수 있도록 제한합니다. 외부에서 안전하게 접속하려면 5번 섹션에서 설명할 ‘리버스 프록시’를 설정하는 것이 표준적인 방법입니다.

4. n8n 컨테이너 실행 및 확인

docker-compose.yml 파일 작성이 완료되었다면, 해당 파일이 저장된 폴더에서 터미널을 열고 아래 명령어를 실행하여 n8n을 시작합니다.

docker-compose up -d

-d 옵션은 컨테이너를 백그라운드에서 실행하라는 의미입니다. 잠시 후 n8n 이미지를 다운로드하고 컨테이너 생성이 완료됩니다.

정상적으로 실행되었는지 확인하려면 아래 명령어를 입력하세요.

docker ps

결과 목록에 n8n이라는 이름의 컨테이너가 보이고 Status가 Up으로 표시된다면 성공입니다. 이제 웹 브라우저를 열고 주소창에 http://localhost:5678을 입력하여 n8n 시작 화면이 나타나는지 확인하세요.

개발 및 테스트용: n8n 로컬 설치 (npm)

Docker가 익숙하지 않거나, 커스텀 노드 개발, 혹은 아주 간단한 워크플로우를 빠르게 테스트해보고 싶을 때 npm을 이용한 n8n 로컬 설치 방법이 유용할 수 있습니다. 하지만 이 방법은 데이터 관리의 어려움과 안정성 문제로 실제 운영 환경(Production)에는 절대 권장하지 않습니다.

npm 설치 과정

Node.js와 npm이 설치된 환경에서 터미널을 열고 아래 명령어를 실행하면 n8n이 전역으로 설치됩니다.

1. n8n 설치 명령어:

npm install n8n -g

2. n8n 실행 명령어:

n8n

실행 후 터미널에 나타나는 주소(http://localhost:5678)로 접속하면 바로 n8n을 사용할 수 있습니다.

주의사항: 이 방법은 워크플로우 데이터가 현재 사용자의 홈 디렉터리 아래 .n8n 폴더 안의 database.sqlite 파일에 저장됩니다. 또한, n8n을 실행한 터미널 창을 닫으면 n8n 프로세스도 함께 종료되므로 항상 터미널을 열어두어야 합니다.

설치 그 이상: n8n 초기 설정 및 운영 팁

성공적으로 n8n 설치 방법을 마쳤다면, 이제 실제 사용을 위한 몇 가지 중요한 n8n 초기 설정이 남아있습니다. 이 설정들은 n8n을 더욱 안전하고 편리하게 만들어줍니다.

Owner 계정 생성

n8n에 처음 접속하면 n8n 인스턴스를 관리할 최상위 관리자(Owner) 계정을 생성하는 화면이 나타납니다. 이름, 이메일, 비밀번호를 입력하여 계정을 생성하세요. 이 계정은 n8n의 모든 워크플로우와 설정을 관리하는 막강한 권한을 가지므로, 정보를 정확하게 입력하고 비밀번호는 안전하게 관리해야 합니다.

실제 운영을 위한 필수 설정: 리버스 프록시

현재 상태는 http://localhost:5678 또는 http://서버IP:5678 과 같이 IP 주소와 포트 번호로 직접 접속해야 합니다. 이는 보안에 취약하고 기억하기 어렵습니다. 실제 운영 환경에서는 아래와 같은 이유로 반드시 ‘리버스 프록시’를 설정해야 합니다.

• 보안 강화: 무료 SSL 인증서(Let’s Encrypt)를 적용하여 모든 통신을 HTTPS로 암호화할 수 있습니다.

• 편리한 접속: n8n.yourdomain.com과 같이 기억하기 쉬운 나만의 도메인으로 접속할 수 있습니다.

• 포트 숨김: 외부에서 5678 포트를 직접 노출하지 않아 보안성이 향상됩니다.

Nginx Proxy Manager나 Caddy와 같은 도구를 사용하면 복잡한 설정 없이 몇 번의 클릭만으로 리버스 프록시와 HTTPS 설정을 매우 쉽게 완료할 수 있습니다.

리버스 프록시 설정 후에는 docker-compose.yml 파일의 WEBHOOK_URL 환경 변수 값을 http://localhost:5678/에서 https://n8n.yourdomain.com/ 과 같이 자신의 도메인 주소로 반드시 변경하고 docker compose up -d 명령어로 컨테이너를 재시작해야 합니다. 그렇지 않으면 외부 서비스에서 n8n으로 데이터를 보내는 웹훅(Webhook) 기능이 정상적으로 동작하지 않습니다.

이메일(SMTP) 서버 설정

워크플로우가 실행되다가 오류가 발생했을 때 이메일로 알림을 받거나, 다른 사용자를 n8n으로 초대하는 등의 기능을 사용하려면 이메일 서버 설정이 필요합니다. n8n 대시보드의 [Settings] > [Email (SMTP)] 메뉴에서 사용하는 이메일 서비스(Gmail, Naver 등)의 SMTP 서버 정보를 입력하면 해당 기능들을 활성화할 수 있습니다.

결론

지금까지 가장 안정적인 n8n docker 설치 방법부터 개발을 위한 n8n 로컬 설치, 실제 운영을 위한 n8n 초기 설정 및 흔히 발생하는 n8n 설치 오류 해결 방법까지, n8n 설치에 대한 모든 것을 상세하게 알아보았습니다.

성공적으로 n8n 설치를 마친 당신은 이제 구글 시트, 슬랙, 노션, ChatGPT 등 수많은 서비스를 엮어 단순 반복 업무에서 벗어나 더 가치 있는 일에 집중할 수 있는 강력한 무기를 얻었습니다. API 연동, 데이터 처리, AI 에이전트 구축 등 n8n이 제공하는 무한한 자동화의 세계를 마음껏 탐험해 보세요.

이제 모든 준비가 끝났습니다. 다음 글에서는 ‘슬랙과 ChatGPT를 연동한 자동 응답 봇 만들기’ 예제를 통해 n8n의 실제 활용법을 알아보겠습니다. 지금 바로 여러분의 첫 번째 자동화 워크플로우 만들기를 시작해 보세요

자주 묻는 질문 (FAQ)

n8n 설치 오류 해결은 초보자들이 가장 어려워하는 부분입니다. 하지만 대부분의 문제는 몇 가지 흔한 원인에서 비롯됩니다. 당황하지 말고 아래 내용을 확인해 보세요.

Q1: 컨테이너가 실행되지 않거나 계속 재시작돼요. (Status: Restarting)

A: 가장 먼저 컨테이너가 왜 오류를 뱉는지 로그를 확인해야 합니다. 터미널에 docker logs [컨테이너_이름_또는_ID] 명령어를 입력하여 오류 원인을 파악하세요. (컨테이너 이름은 docker ps -a로 확인 가능)

• 주요 원인 1: docker-compose.yml 파일에 N8N_ENCRYPTION_KEY를 설정하지 않은 경우. 로그에 관련 오류 메시지가 나타납니다.

• 주요 원인 2: 볼륨으로 지정한 폴더(~/n8n-data)에 Docker가 접근할 권한이 없는 경우. 로그에 permission denied 오류가 포함됩니다. sudo chown -R 1000:1000 ~/n8n-data 와 같은 명령어로 폴더 소유권을 변경하여 해결할 수 있습니다.

Q2: `Error: listen EADDRINUSE: address already in use :::5678` 오류가 발생해요.

A: 5678번 포트를 다른 프로그램이 이미 사용하고 있다는 의미입니다. docker-compose.yml 파일의 ports 설정을 "127.0.0.1:5678:5678" 에서 "127.0.0.1:8888:5678" 과 같이 앞부분의 포트를 다른 번호(예: 8888)로 변경한 후, docker-compose up -d 명령어로 다시 실행하세요. 접속 주소는 http://localhost:8888 이 됩니다.

Q3: n8n 버전은 어떻게 안전하게 업데이트하나요?

A: Docker Compose를 사용하면 업데이트는 매우 간단하고 안전합니다. docker-compose.yml 파일이 있는 폴더에서 아래 두 명령어를 터미널에 순서대로 실행하면 됩니다. 기존 데이터는 볼륨 폴더에 안전하게 보관된 채 n8n 프로그램만 최신 버전으로 교체됩니다.

1. docker-compose pull (최신 버전의 n8n 이미지를 다운로드)

2. docker-compose up -d (최신 이미지로 컨테이너를 다시 생성하여 실행)

Q4: 워크플로우 데이터는 어디에 저장되나요? 백업은 어떻게 하죠?

A: Docker 설치 방법을 사용했다면 모든 데이터는 docker-compose.yml의 volumes에 설정한 로컬 폴더(이 가이드 기준 ~/n8n-data)에 저장됩니다. 따라서 가장 확실한 백업 방법은 이 폴더 전체를 압축하여 주기적으로 다른 저장 공간(클라우드 스토리지, 외장 하드 등)에 보관하는 것입니다.