제 3부. N8N 설치와 실행: 내 PC에 자동화 서버 구축하기 (Docker Run 명령어 상세 분석)

인트로: 단 하나의 명령어로 N8N 서버를 구동하다

제2부에서 우리는 N8N 셀프 호스팅의 핵심 기반 기술인 도커(Docker)의 개념을 완벽하게 이해하고, N8N 데이터 보존을 위한 볼륨 폴더 생성 및 도커 엔진 설치까지 완료했습니다. 이제 모든 준비가 끝났습니다.

대부분의 서버 구축 과정은 복잡한 설정 파일 수정, 의존성 설치, 그리고 긴 초기화 과정을 요구합니다. 그러나 도커 환경에서는 이 모든 복잡성이 단 하나의 명령어로 대체됩니다. 이 명령어는 단순한 텍스트 줄이 아니라, 우리가 앞서 배운 모든 개념(이미지, 컨테이너, 볼륨)을 한 번에 실행시키는 '자동화 서버 실행 계획서'입니다.

이번 제3부에서는 그 마법의 명령어, 바로 docker run 명령어를 상세히 분석할 것입니다. 우리는 이 명령어를 구성하는 각 옵션(--name, -p, -v, -e)이 어떤 의미를 가지며, N8N 서버를 가장 안전하고 영속적으로 운영하는 데 왜 필수적인지를 명확하게 설명할 것입니다.

• docker run 명령어의 옵션 해부: N8N을 실행하는 데 필요한 최소한의 필수 옵션부터 데이터 보존과 보안을 위한 고급 옵션까지 자세히 다룹니다.

• N8N 서버 실행: 명령어를 입력하고, N8N 컨테이너가 성공적으로 구동되는 과정을 직접 확인합니다.

• 최초 접속 확인: 웹 브라우저를 통해 실행된 N8N 서버에 접속하여, 여러분의 개인 PC가 진정한 자동화 서버로 변신했음을 눈으로 확인하는 단계까지 완료할 것입니다.

이제 터미널을 열고, 여러분의 컴퓨터를 데이터 주권을 가진 독립적인 자동화 서버로 바꾸는 핵심 명령어를 입력할 준비를 하십시오.

1: N8N 서버 구동의 핵심, docker run 명령어의 구조 해부

N8N 서버를 여러분의 PC에 띄우는 과정은 복잡한 설치가 아닌, 단 하나의 docker run 명령어를 터미널에 입력하는 것으로 끝납니다. 이 명령어를 올바르게 구성해야 N8N 서버가 안정적으로 실행되고, 중요한 데이터가 영구적으로 보존됩니다.

1. N8N 서버 실행을 위한 표준 명령어 (Windows/Mac/Linux 공통)

가장 안정적이고 영속적인 N8N 서버를 구축하기 위한 표준 docker run 명령어는 다음과 같습니다. 이 명령어를 한 줄로 연결하여 사용합니다.

Bash

docker run -it --rm \
    --name n8n \
    -p 5678:5678 \
    -v C:\docker\n8n:/home/node/.n8n \
    -e N8N_HOST=localhost \
    -e N8N_PROTOCOL=http \
    n8nio/n8n:latest

[참고] 위의 명령어는 Windows 환경에서 볼륨 경로(C:\docker\n8n)를 예시로 들었습니다. macOS나 Linux 사용자는 해당 경로를 ~/docker/n8n 등 본인이 2부에서 생성한 폴더 경로로 변경해야 합니다.

2. docker run 명령어 옵션 상세 분석

이 하나의 명령어에 우리가 앞서 배운 도커의 모든 핵심 개념이 포함되어 있습니다. 각 옵션이 어떤 역할을 하는지 정확히 이해해야 문제가 발생했을 때 대처할 수 있습니다.

A. 컨테이너 기본 설정 옵션

옵션	예시	역할	설명
-it	-it	상호 작용 모드	컨테이너 내부와 터미널 간의 상호 작용을 가능하게 합니다. (컨테이너 로그를 확인할 수 있음)
--rm	--rm	임시 컨테이너 설정	컨테이너가 중지될 때 자동으로 삭제됩니다. 실행 후 생기는 부산물(쓰레기 파일)을 남기지 않아 PC 환경을 깨끗하게 유지합니다.
--name	--name n8n	컨테이너 이름 지정	이 컨테이너에 'n8n'이라는 이름을 부여하여 나중에 중지(docker stop n8n)하거나 관리하기 쉽게 만듭니다.

B. 포트 연결 옵션: -p (Port Mapping)

옵션	예시	역할	설명
-p	-p 5678:5678	포트 포워딩	호스트 PC의 포트와 컨테이너 내부 포트를 연결합니다. [호스트 PC 포트]:[컨테이너 포트] 형식이며, N8N은 내부적으로 5678 포트를 사용합니다. 이를 통해 웹 브라우저에서 localhost:5678로 접속할 수 있게 됩니다.

C. 데이터 영속성 옵션: -v (Volume Mapping)

옵션	예시	역할	설명
-v	-v C:\docker\n8n:/home/node/.n8n	볼륨 연결	가장 중요한 옵션입니다. 호스트 PC의 볼륨 폴더(C:\docker\n8n)와 N8N 컨테이너 내부의 데이터 저장 위치(/.n8n)를 연결(매핑)합니다. 이로써 워크플로, 크레덴셜 등의 중요한 N8N 데이터가 컨테이너가 삭제되어도 안전하게 여러분의 PC에 보존됩니다.

D. 이미지 지정

옵션	예시	역할	설명
(마지막)	n8nio/n8n:latest	이미지 지정	도커 허브에서 어떤 이미지를 가져와 실행할 것인지 지정합니다. n8nio/n8n은 공식 N8N 이미지를 의미하며, :latest는 최신 버전을 사용하겠다는 의미입니다.

2: N8N 환경 변수 설정과 서버 실행하기

N8N을 실행하는 마지막 필수 단계는 환경 변수(-e)를 설정하는 것입니다. 이 환경 변수는 컨테이너 내부의 N8N 애플리케이션에 외부 환경 정보를 전달하여, N8N이 웹 브라우저를 통해 정상적으로 접속되도록 설정하는 중요한 역할을 합니다.

1. 환경 변수 옵션: -e (Environment Variables)

옵션	예시	역할	설명
-e N8N_HOST	-e N8N_HOST=localhost	호스트 이름 지정	N8N이 실행되는 호스트의 주소를 지정합니다. 개인 PC에서 실행할 경우 localhost로 설정해야 웹 브라우저에서 올바르게 접속할 수 있습니다.
-e N8N_PROTOCOL	-e N8N_PROTOCOL=http	통신 프로토콜 지정	N8N과의 통신에 사용될 프로토콜을 지정합니다. 초기에는 간단하게 암호화되지 않은 http를 사용하며, 나중에 HTTPS로 전환할 수 있습니다.

2. 최종 명령어 조합 및 실행

지금까지 분석한 모든 필수 옵션을 조합하여, N8N 서버를 영구적으로 운영할 수 있는 최종 docker run 명령어를 완성합니다. 이 명령어를 복사하여 터미널(Command Prompt, PowerShell, Terminal 등)에 붙여넣고 실행하십시오.

• Windows 사용자 예시: (경로를 반드시 여러분이 2부에서 생성한 폴더 경로로 변경하십시오.)

Bash

docker run -it --rm \
    --name n8n \
    -p 5678:5678 \
    -v C:\docker\n8n:/home/node/.n8n \
    -e N8N_HOST=localhost \
    -e N8N_PROTOCOL=http \
    n8nio/n8n:latest

• macOS / Linux 사용자 예시: (경로를 반드시 여러분이 2부에서 생성한 폴더 경로로 변경하십시오.)

Bash

docker run -it --rm \
    --name n8n \
    -p 5678:5678 \
    -v ~/.n8n:/home/node/.n8n \
    -e N8N_HOST=localhost \
    -e N8N_PROTOCOL=http \
    n8nio/n8n:latest

3. 서버 구동 확인 및 로그 분석

명령어를 실행하면 도커는 다음 단계를 자동으로 수행합니다.

1. 이미지 다운로드: 만약 n8nio/n8n:latest 이미지가 로컬에 없다면, 도커 허브에서 이미지를 다운로드합니다.

2. 컨테이너 생성 및 실행: 다운로드한 이미지를 바탕으로 n8n이라는 이름의 컨테이너를 생성하고 N8N 애플리케이션을 구동합니다.

3. 로그 출력: 컨테이너가 실행되면서 N8N 서버의 초기화 과정이 터미널에 실시간 로그로 출력됩니다.

로그 출력 중 다음과 같은 메시지가 보인다면 N8N 서버 구동에 성공한 것입니다.

n8n ready on http://localhost:5678

이제 여러분의 PC는 N8N 서버를 호스팅하고 있으며, 이 터미널 창은 N8N 서버의 실시간 로그를 보여주고 있으므로, 창을 닫지 않은 상태로 다음 단계로 넘어갑니다.

3: N8N 서버 최초 접속 확인 및 컨테이너 관리 방법

docker run 명령어를 통해 N8N 서버를 구동하는 데 성공했습니다. 이제 웹 브라우저를 통해 N8N 워크플로 환경에 접속하고, 서버를 중지하거나 재시작하는 기본적인 관리 방법을 익혀야 합니다.

1. N8N 서버에 최초 접속하기

서버 구동 로그에 n8n ready on http://localhost:5678 메시지를 확인했다면, 이제 웹 브라우저를 열어 접속합니다.

• 접속 주소: 웹 브라우저 주소창에 http://localhost:5678을 입력하고 접속하십시오.

최초 접속 시 N8N은 관리자 계정 생성을 요구합니다. 이 계정은 여러분의 워크플로 환경을 보호하는 마스터 계정이 되므로, 강력한 암호와 함께 계정을 생성하십시오.

• 최초 설정 확인: 계정 생성을 완료하고 대시보드(캔버스)가 보인다면, N8N 셀프 호스팅 설치가 성공적으로 완료된 것입니다.

2. 구동된 컨테이너 확인 및 관리 (백그라운드 실행을 위한 준비)

현재 N8N은 터미널 창(-it 옵션)에 로그를 출력하며 실행 중입니다. 이 창을 닫으면 N8N 서버도 중지됩니다. 안정적인 운영을 위해서는 N8N을 백그라운드에서 실행해야 합니다.

A. 현재 실행 중인 컨테이너 목록 확인

새로운 터미널 창을 열고, 현재 도커에서 실행 중인 컨테이너 목록을 확인합니다.

• 명령어:

  Bash

  docker ps
  

• 확인 사항: CONTAINER ID, IMAGE (n8nio/n8n:latest), 그리고 NAMES (n8n)이 목록에 나타나야 합니다.

B. N8N 서버 중지 및 재시작

N8N 서버를 중지하거나 재시작해야 할 때 사용하는 명령어는 다음과 같습니다. 컨테이너를 관리하기 쉽게 --name n8n 옵션을 사용했기 때문에 이름으로 제어가 가능합니다.

• 서버 중지 (Graceful Shutdown):

  Bash

  docker stop n8n
  

• 서버 재시작:

  Bash

  docker start n8n
  

3. 서버 상시 구동을 위한 백그라운드 실행 (-d 옵션)

터미널 창을 닫아도 N8N 서버가 계속 작동하도록 하려면, 다음번 실행 시 -it --rm 옵션을 제거하고 -d 옵션으로 대체해야 합니다.

• -d (Detached Mode): 서버를 백그라운드(데몬 모드)에서 실행하고, 터미널은 즉시 다른 작업을 할 수 있도록 반환합니다.

다음번 N8N 서버를 재시작할 때는 이 명령어를 사용하십시오 (단, 기존 n8n 컨테이너가 중지되어 있어야 합니다):

Bash

docker run -d \
    --name n8n \
    -p 5678:5678 \
    -v C:\docker\n8n:/home/node/.n8n \
    -e N8N_HOST=localhost \
    -e N8N_PROTOCOL=http \
    n8nio/n8n:latest

🔒 4: N8N 셀프 호스팅 서버의 자체 방어 능력 구축

N8N을 개인 PC나 사내 서버에 구축한다는 것은, 여러분의 서버가 외부 공격의 대상이 될 수 있음을 의미합니다. N8N 자체의 보안 설정 외에, 서버 수준에서 필수적으로 구축해야 할 방어 능력은 다음과 같습니다.

1. 전송 데이터 암호화: HTTPS 강제 적용

현재 N8N_PROTOCOL=http로 설정하여 사용하고 있지만, 이는 데이터가 평문(암호화되지 않은 상태)으로 전송된다는 것을 의미하며, 중간에서 데이터 가로채기(Man-in-the-Middle Attack)에 취약합니다. 외부와 통신하는 모든 워크플로의 보안을 위해 HTTPS를 반드시 적용해야 합니다.

• 방어 능력: 데이터 전송 시 SSL/TLS 암호화를 통해 워크플로의 내용, 특히 API 키나 비밀번호가 노출되는 것을 방지합니다.

• 구축 방법:

  • 도메인 사용 시: Let's Encrypt와 같은 인증서를 발급받고, 리버스 프록시(Reverse Proxy) 서버(예: Nginx, Caddy)를 도커 앞에 두어 SSL 인증을 처리하도록 설정해야 합니다. (이는 고급 과정에서 다룹니다.)

  • 로컬 환경 시: 외부 접근 없이 로컬에서만 사용할 경우 http로 충분하지만, 데이터 노출 위험이 있는 외부 API와 통신한다면 리버스 프록시를 통한 HTTPS 적용을 고려해야 합니다.

2. 접근 통제 강화: 인증 정보 및 계정 보안

N8N 자체가 제공하는 가장 기본적인 방어선은 접근 통제입니다.

• 방어 능력: 강력한 비밀번호 설정과 정기적인 변경을 통해 관리자 계정에 대한 무단 접근을 차단합니다.

• 구축 방법:

  • 강력한 비밀번호 사용: 최초 로그인 시 설정한 관리자 비밀번호를 강력하게 유지하고 주기적으로 변경합니다.

  • 접근 제한: N8N을 외부에서 접속할 필요가 없다면, 방화벽을 설정하여 5678 포트를 외부 IP로부터 차단하고 내부 네트워크(로컬 환경)에서만 접근 가능하도록 제한합니다.

3. 서버/OS 수준의 외부 위협 방어

N8N 컨테이너 자체의 문제가 아니라, 컨테이너를 구동하는 호스트 PC(서버)를 보호해야 합니다. 바이러스나 해킹 시도는 대부분 호스트 OS의 취약점을 노립니다.

• 방어 능력: 외부 침입 경로를 최소화하고, 알려진 취약점을 통한 공격을 차단합니다.

• 구축 방법:

  • 방화벽(Firewall) 설정: 호스트 PC의 방화벽을 활성화하고, N8N이 사용하는 5678 포트만 필요한 IP 대역에 한해 접근을 허용합니다. 불필요한 모든 포트는 닫아둡니다.

  • 운영체제(OS) 및 도커 업데이트: 호스트 OS(Windows, macOS, Linux)와 도커 엔진을 항상 최신 버전으로 업데이트하여 알려진 보안 취약점을 패치합니다.

  • 백신/보안 프로그램 사용: 호스트 PC에 안티바이러스 및 엔드포인트 보안 솔루션을 설치하고 항상 활성화합니다.

4. 데이터 보호: 백업 및 복구 능력

최악의 상황(랜섬웨어, 하드웨어 손상 등)에서도 워크플로 데이터를 보호하는 것이 최종 방어 능력입니다.

• 방어 능력: 물리적 손상이나 악성 코드 감염 시에도 데이터 손실 없이 이전 상태로 복구할 수 있는 능력을 확보합니다.

• 구축 방법:

  • 볼륨 백업: 본론 2에서 설정한 N8N 볼륨 폴더(C:\docker\n8n 등)를 클라우드 저장소나 외장 하드에 정기적으로 백업합니다.

  • 버전 관리: 워크플로를 버전 관리 시스템(예: 깃허브)에 백업하여 관리할 수도 있습니다.

이러한 자체 방어 능력을 구축하는 것은 셀프 호스팅의 필수 과정이며, 이 시리즈의 이후 고급 활용편에서 리버스 프록시와 HTTPS 설정을 통해 보안을 강화하는 방법을 구체적으로 다룰 예정입니다.

5. 핵심 방어선 구축: 방화벽을 이용한 외부 접근 차단 액션 플로우

N8N을 오직 여러분의 PC나 사내망 내부에서만 사용하고 외부에 노출할 필요가 없다면, 가장 먼저 외부 IP로부터의 접근을 방화벽을 통해 차단해야 합니다. 이는 무단 침입을 막는 가장 효과적인 첫 번째 방어선입니다.

5-1. Windows 방화벽 설정 (인바운드 규칙 생성)

Windows PC를 서버로 사용한다면, 다음의 단계에 따라 5678 포트의 외부 접근을 차단하십시오.

1. Windows 방화벽 열기:

   • Windows 검색창에 "Windows Defender 방화벽"을 검색하여 실행합니다.

   • 좌측 메뉴에서 "고급 설정"을 클릭합니다.

2. 인바운드 규칙 생성:

   • 좌측 트리 메뉴에서 "인바운드 규칙"을 선택합니다.

   • 우측 메뉴의 "새 규칙..."을 클릭합니다.

3. 규칙 설정 단계:

   • 규칙 종류: "포트"를 선택하고 [다음]을 클릭합니다.

   • 프로토콜 및 포트: "TCP"를 선택하고 "특정 로컬 포트"*에 5678을 입력한 후 [다음]을 클릭합니다.

   • 작업: "연결 허용"을 선택하고 [다음]을 클릭합니다. (차단 규칙을 따로 만들 필요 없이, 허용할 IP 범위를 좁혀서 기본 차단 정책을 활용합니다.)

   • 프로필: 모두 체크합니다. (도메인, 개인, 공용) [다음]을 클릭합니다.

   • 이름: 규칙 이름을 N8N-Local-Only 등으로 지정하고 [마침]을 클릭합니다.

4. IP 범위 제한 (로컬만 허용):

   • 방금 만든 N8N-Local-Only 규칙을 더블 클릭합니다.

   • "범위" 탭을 선택합니다.

   • "원격 IP 주소" 섹션에서 "다음 IP 주소"를 선택하고 [추가]를 클릭합니다.

   • "이 IP 주소 또는 서브넷"에 127.0.0.1 (로컬 호스트 주소)와 여러분의 내부 네트워크 대역 (예: 192.168.0.0/24 또는 192.168.1.0/24)을 추가합니다.

   • 결과: 이 설정은 외부의 알 수 없는 IP가 5678 포트에 접근하는 것을 방화벽이 차단하고, 오직 로컬 PC와 내부 네트워크의 접속만 허용하게 됩니다.

5-2. macOS 및 Linux 환경 안내

• macOS: macOS는 기본적으로 외부 포트가 닫혀있으나, 혹시 모를 상황에 대비하여 Little Snitch와 같은 서드파티 방화벽 앱을 사용하여 아웃바운드 및 인바운드 연결을 관리할 수 있습니다.

• Linux (Ubuntu/CentOS 등): UFW (Uncomplicated Firewall) 도구를 사용하여 명시적으로 포트 접근을 제한합니다.

  • sudo ufw deny proto tcp from any to any port 5678 (모든 외부 접속 차단)

  • sudo ufw allow proto tcp from 192.168.0.0/24 to any port 5678 (내부 네트워크만 허용)

이러한 방화벽 설정을 통해, 여러분은 N8N 서버를 외부 위협으로부터 1차적으로 보호하며, 데이터 주권을 더욱 강력하게 확보할 수 있습니다.

클로징: 자동화 서버 구동 성공, 이제 워크플로를 만들 차례입니다 (CTA)

여러분은 이제 가장 큰 기술적 산을 넘었습니다. 제1부에서 셀프 호스팅의 가치를, 제2부에서 도커의 원리를 배웠고, 이번 제3부를 통해 마침내 단 하나의 docker run 명령어로 N8N 서버를 여러분의 PC에 성공적으로 구동했습니다.

• 데이터 주권 확보: 이제 여러분의 모든 워크플로 데이터와 민감한 크레덴셜은 외부 클라우드가 아닌, 여러분의 볼륨 폴더에 안전하게 저장됩니다.

• 비용 부담 제거: 실행 횟수에 제한이 없는 무제한 자동화 환경을 구축했습니다.

또한, 우리는 방화벽 설정이라는 구체적인 액션 플로우를 통해 외부 IP로부터의 접근을 차단하여, 로컬 환경에서 발생하는 보안 위험까지 성공적으로 방어했습니다. 현재는 HTTP 환경이지만, 다음 고급 활용편에서 HTTPS와 리버스 프록시를 통한 궁극적인 보안 강화 방법을 다룰 것임을 약속드립니다.

여러분은 더 이상 자동화 서비스의 가격 정책에 묶여 고민할 필요가 없습니다. 진정한 데이터 오너십과 무한한 확장성을 가진 자동화 환경의 마스터가 되었습니다.

이 포스팅은 쿠팡 파트너스 활동으로, 일정의 수수료를 제공받습니다

행동 유발 (CTA):

N8N 서버는 지금 여러분의 PC에서 실행되고 있습니다.

이제 http://localhost:5678에 접속하여, 첫 번째 워크플로를 만들 준비를 하십시오! 다음 편, 제 4부에서는 이 강력한 N8N 서버 위에서 실제 업무에 바로 적용 가능한 실용적인 워크플로를 만드는 방법을 구체적으로 안내하고, N8N의 핵심인 노드(Node)를 연결하는 방법을 단계별로 익힐 것입니다.

여러분의 자동화 여정은 이제 시작입니다. 다음 편에서 첫 번째 워크플로를 완성합시다!

가나 투데이 #ganatoday

그린아프로