로컬 방식으로 n8n을 설치하는 방법을 알아보겠습니다. 로컬 방식은 기능이나 횟수 제한 없이 자유롭게 워크플로를 만들고 실행할 수 있다는 장점이 있지만, 직접 자신의 컴퓨터에 설치해야 합니다. 직접 설치하는 방법도 있지만 여기서는 도커Docker를 사용하여 설치하는 방식을 다루겠습니다.
[01] 설치를 위해 필요한 준비물
도커
도커는 프로그램을 ‘컨테이너’라는 독립적인 환경에서 실행하는 기술입니다. 쉽게 말해, 컴퓨터 안에 작은 가상 컴퓨터를 하나 만들어서 그 안에서 프로그램을 실행하는 것과 비슷합니다. 이 도커를 사용하면 프로그램을 설치하는 것도 매우 간단해집니다. 마치 누군가가 n8n을 실행하는 데 필요한 모든 설정과 파일을 하나의 상자 안에 미리 정리해서 제공하는 것이라고 생각하면 됩니다. 복잡한 설치 과정을 생략하고 단 한 줄의 명령어만으로 n8n을 실행할 수 있다는 점이 도커의 가장 큰 장점입니다. 또한 프로그램이 이 컨테이너 안에서 독립적으로 실행되기 때문에 내 컴퓨터에 설치된 다른 프로그램에 영향을 주지 않고, 안정적이고 안전한 실행 환경을 만들 수 있습니다.
스타터 키트
도커를 이용해 n8n을 설치할 때, 여기서는 n8n을 따로 설치하지 않고 n8n에서 제공하는 스타터 키트인 Self-hosted Starter Kit를 사용해 설치할 예정입니다. Self-hosted Starter Kit는 n8n을 로컬에서 안정적으로 실행할 수 있도록 필요한 모든 설정을 미리 구성해둔 템플릿입니다. 쉽게 말해 필요한 설정 파일들이 포함되어 있다고 생각하면 됩니다. 복잡한 설정을 하나하나 직접 할 필요 없이, 단 한 줄의 명령어만으로도 실행 가능한 환경을 자동으로 구성해줍니다. Starter Kit는 단순히 n8n만 설치하는 것이 아니라 Ollama, Qdrant, PostgreSQL 같이 AI 기능에 필요한 여러 도구를 함께 설치하고 연결하는 역할도 합니다. 덕분에 초보자도 복잡한 설치 과정을 거치지 않고 AI 기능이 탑재된 n8n 환경을 빠르게 구성할 수 있습니다. 그리고 n8n만 설치할 때는 AI 기능을 사용하려면 OpenAI, Claude 같은 외부 API를 연결해야 하고 그때마다 호출 비용이 발생합니다. 하지만 스타터 키트에는 로컬에서 직접 실행되는 AI 모델이 함께 구성되어 있어 API 호출 비용 없이 AI 기능을 사용할 수 있습니다.
Self-hosted Starter Kit는 깃허브를 통해 제공되기 때문에 깃이 설치되어 있어야 내려받을 수 있습니다. 또한 설치된 구성들을 실제로 실행하려면 도커도 반드시 설치되어 있어야 합니다. 즉, 스타터 키트를 사용하려면 깃과 도커, 이 두 가지가 필요합니다. 그럼 지금부터 깃과 도커 설치부터 시작해서 n8n을 실행하기까지의 전체 과정을 차근차근 단계별로 설명하겠습니다.
[02] 깃 설치하기
01단계 구글에서 Git을 검색하거나 직접 브라우저 주소창에 URL을 입력하여 Git 공식 페이지로 이동한 다음, 메인 화면에서 [Download for Windows] 버튼을 클릭합니다. 이 버튼은 지금 자신의 운영체제에 맞는 것으로 나타납니다. 여기에서는 윈도우를 기준으로 설명하겠습니다.
Git 공식 홈페이지 : git-scm.com
02단계 윈도우 다운로드 페이지로 넘어가서 가장 상단에 [Click here to download]를 클릭하면 설치 파일 다운로드가 시작됩니다.
03단계 내려받은 파일을 실행하여 설치를 시작합니다. 설치 시에 선택 옵션들이 있는 경우가 나오는데 모두 기본 권장 설치 옵션을 그대로 두고 아래의 [Next] 버튼을 클릭합니다.
04단계 설치가 정상적으로 완료되었는지 확인해보기 위해 ➊ 윈도우 검색 메뉴에서 ‘cmd’를 입력한 다음 ➋ 명령 프롬프트를 실행합니다.
05단계 명령 프롬프트 창에서 ‘git’을 입력한 다음 키보드의 [Enter]를 눌러줍니다. 다음과 같이 명령어 목록이나 도움말이 출력되면 깃이 제대로 설치되어 있고 정상적으로 실행할 수 있는 상태라는 뜻입니다.
이번에는 도커를 설치해볼 텐데, 윈도우에 도커를 설치하려면 몇 가지 필수 조건들이 있습니다.
윈도우의 버전이 Windows 10 Pro, Enterprise, Education(빌드 19044 이상)이거나 Windows 11이어야 합니다. (Home 에디션은 도커 설치 전에 WSL 2를 설치해야 합니다.)
최소 4GB 이상의 RAM을 권장합니다. 일부 경우 2GB로도 가능하지만 속도 저하와 오류 가능성이 있습니다.
도커는 64비트 CPU에서만 작동합니다.
CPU 가상화(Virtualization)를 활성화해야 합니다.
1번부터 3번까지의 조건은 PC 사양에 따라 결정되며, 4번의 때에는 기존에 활성화되어 있지 않았어도 우리가 직접 활성화할 수 있습니다. 따라서 먼저 CPU 가상화 활성화 방법을 함께 알아보겠습니다.
[03] CPU 가상화 옵션 활성화하기
가상화 옵션을 간략히 설명하자면, 컴퓨터의 CPU가 가상 머신을 만들 수 있게 하는 기능입니다. 앞에서 도커는 프로그램을 ‘컨테이너’라는 독립적인 환경에서 실행할 수 있게 한다고 설명했는데, 이 컨테이너는 리눅스를 기반으로 작동합니다. 따라서 윈도우 운영체제를 사용하는 때에는 이 리눅스 환경을 실행하기 위해 WSL 2나 Hyper-V 같은 가상 머신 기술을 사용합니다. 따라서 가상화 기능이 꺼져 있으면 가상 머신을 실행할 수 없기 때문에 도커도 실행되지 않습니다. n8n을 실행하기 위해 꼭 필요한 개념은 아니기 때문에 조금 어렵게 느껴진다면 그냥 도커를 실행하기 위해 필요한 기능이라고만 생각하고 그냥 따라해도 괜찮습니다.
01단계 가상화 옵션을 활성화려면 먼저 윈도우 검색에서 ‘Windows 기능 켜기/끄기’를 검색하여 실행합니다.
02단계 여러 옵션 중 ➊ Hyper-V, ➋ Linux용 Windows 하위 시스템, ➌ Windows용 하이퍼바이저 플랫폼을 모두 체크한 다음 확인 버튼을 클릭하세요. 그러면 자동으로 설치가 시작됩니다.
만약 이 세 가지 옵션을 이미 설치해서 체크되어 있다면 그대로 두고 도커 설치 과정을 바로 진행하면 됩니다.
<한 걸음 더!> Windows 기능 켜기/끄기에 Hyper-V 기능이 보이지 않아요!
Windows Home 등 일부 윈도우 에디션은 “Windows 기능 켜기/끄기” 목록에 Hyper-V가 나타나지 않을 수 있습니다. 그럴 때 다음의 코드로 윈도우 안에 이미 들어 있는 Hyper-V 파일들을 찾아서 자동으로 설치하고 활성화할 수 있습니다.
우선 메모장을 켜고 다음 명령어를 붙여넣어 저장하세요. 이때, 확장자는 .txt가 아닌 .bat로 합니다.
```
pushd "%~dp0"
dir /b %SystemRoot%\servicing\Packages\*Hyper-V*.mum >hyper-v.txt
for /f %%i in ('findstr /i . hyper-v.txt 2^>nul') do dism /online /norestart /add-package:"%SystemRoot%\servicing\Packages\%%i"
del hyper-v.txt
Dism /online /enable-feature /featurename:Microsoft-Hyper-V -All /LimitAccess /ALL
pause
```
.bat 파일을 관리자 권한으로 실행하면 다음과 같은 cmd창을 마주할 수 있습니다.
실행이 완료되면 컴퓨터를 다시 시작하세요.
03단계 설치가 모두 끝나면 하단의 [다시 시작(N)] 버튼을 클릭하여 컴퓨터를 다시 실행합니다.
<한 걸음 더!> 도커 실행 시 가상화 오류 메시지가 떠요
만약 이렇게 가상화 옵션을 켠 다음 도커까지 설치했으나 도커 실행 시 가상화 관련 오류 메시지가 뜨면 하드웨어 차원(BiOS/UEFI)에서 가상화 옵션이 켜졌는지 확인해야 합니다. 단축키 [Ctrl + Shift + Esc]로 작업 관리자를 열고, [성능] 탭에서 [CPU]를 선택하세요. 오른쪽 아래에 ‘가상화: 사용’이라고 표시되어 있으면 하드웨어 차원의 가상화 옵션도 설정이 이미 되어 있는 겁니다.
‘가상화: 사용 안 함’일 때는 BiOS에 진입해서 켜야 합니다. 대부분의 최신 컴퓨터의 경우에는 이미 CPU의 가상화 옵션이 켜졌기 때문에 문제없이 진행됩니다.
BiOS 진입하려면 컴퓨터를 재시작 후 부팅 시작 시 특정 키를 연타합니다. 일반적으로 [F2], [F10], [Delete], [F12], [Esc] 등의 키를 사용하는데, PC 제조사별로 다르기 때문에 부팅 화면에 표시되는 메시지를 확인하고 해당 키를 연타하면 됩니다.
BiOS에 진입한 다음, 가상화 옵션을 찾습니다. 가상화 옵션의 이름은 CPU 제조사에 따라 다르게 표시될 수 있으며, Intel CPU와 AMD CPU에서 사용하는 가상화 옵션의 이름들은 다음과 같습니다.
Intel CPU : Intel Virtualization Technology, Intel VT-x, VT-x
AMD CPU : SVM Mode, AMD-V
따라서 자신의 CPU에 해당하는 가상화 옵션 이름을 찾아야 합니다. 해당 옵션이 위치하는 메뉴도 제조사에 따라 다르지만, 보통 다음 메뉴 중 하나에 위치합니다.
Advanced ➝ CPU Configuration
Security ➝ Virtualization
Advanced ➝ Intel Virtualization Technology
System Configuration ➝ Virtualization Technology
해당 옵션을 찾아 Enabled로 변경한 다음, [F10] 키를 눌러 설정 저장 후 종료합니다. 또는 [Exit] 메뉴에서 [Save Changes and Exit]을 선택해도 됩니다. 그러면 시스템이 재부팅되며, 가상화가 활성화된 상태로 Windows로 들어갑니다.
Windows 부팅 후 다시 한번 작업 관리자를 열어 ‘가상화: 사용’으로 표시가 되는지 확인합니다.
[04] 도커 설치하기
01단계 도커를 설치하기 위해 구글이나 검색 사이트에서 도커를 검색하여 공식 사이트에 접속합니다. 또는 브라우저 주소창에 바로 주소를 입력하여 사이트로 이동합니다.
도커 홈페이지 : docker.com
도커 사이트의 메인 화면에서 [Download Docker Desktop] 버튼에 마우스 오버를 하면 운영체제별 파일 다운로드 링크가 연결된 목록이 나타납니다. 이번에도 자신의 컴퓨터의 운영체제를 선택하여 설치 파일 다운로드를 시작합니다.
02단계 내려받은 파일을 실행하여 설치합니다. Configuration에서 다음과 같이 [USE WSL 2 instead of Hyper-V] 옵션을 반드시 선택하고 [OK] 버튼을 눌러 설치를 진행합니다.
<한 걸음 더!> [USE WSL 2 instead of Hyper-V] 옵션이 나타나지 않아요!
[USE WSL 2 instead of Hyper-V] 옵션이 나타나지 않을 수 있습니다. 이 경우, 윈도우 버전이 Hyper-V를 지원하지 않아 자동으로 WSL 2 백엔드를 사용하도록 설정하기 때문에 신경쓰지 않아도 됩니다.
03단계 설치가 완료되면 ‘Installation succeeded’라는 문구와 함께 컴퓨터를 재부팅해야 한다는 문구가 나타납니다.
다시 한번 재부팅하고 나서 Docker Desktop을 실행하면 다음과 같이 도커 라이선스 동의 페이지가 켜집니다. [Accept]를 눌러 진행하세요.
04단계 여기서 [Accept] 버튼을 클릭하면 명령 프롬프트가 열리면서 Linux용 Windows 하위 시스템을 최신 버전으로 업데이트해야 한다는 문구가 나타납니다. 아무 키를 누르면 업데이트가 시작되고, 업데이트를 완료하면 다시 한번 자체적으로 버전을 확인합니다. 최신 버전이 이미 설치되어 있다는 표시가 뜨면 [Enter]를 눌러 창을 종료합니다.
05단계 Finish setting up Docker Desktop 창에서 [Use recommended settings]를 선택한 후 [Finish] 버튼을 누르면 도커 설치가 완료됩니다.
06단계 설치 종료 후 도커가 자동으로 실행되는데, 만약 ‘Linux용 Windows 하위 시스템 시작’이라는 창이 같이 뜨면 해당 창은 종료합니다. 실행된 도커에서 계정 로그인 화면이 뜨는데, 여기서는 상단의 [Skip] 버튼을 클릭해 넘어가겠습니다.
<한 걸음 더!> ‘WSL needs updating’ 문구가 떠요!
명령 프롬프트를 열어 wsl --update를 입력합니다. ‘Linux용 Windows 하위 시스템 최신 버전이 이미 설치되어 있습니다.’라는 문구가 뜰 경우 [Restart]를 눌러 도커를 다시 실행하여 진행하면 됩니다. 최신 시스템이 아니면 wsl.exe --update를 입력하여 진행하세요. 04단계와 같은 흐름입니다.
07단계 이제 docker desktop의 메인 화면이 나타납니다. 왼쪽 메뉴바에 Containers, Images, Volumes과 같은 메뉴가 보입니다. 여기서 도커의 핵심 개념만 간략히 알아보고 넘어가겠습니다.
➊ 이미지Images : 도커 안에 어떤 프로그램을 설치하려면 이미지가 필요합니다. 프로그램 설치 파일과 같습니다.
➋ 컨테이너Containers : 내려받은 이미지를 실행한 상태, 실제 작동 중인 프로그램을 말합니다.
➌ 볼륨Volumes : 데이터 저장 공간입니다.
컨테이너는 종료하면 저장된 내용이 사라지지만 볼륨을 연결해두면 데이터를 유지할 수 있습니다. 내 윈도우 컴퓨터의 특정 폴더를 볼륨으로 연결해두면 컨테이너의 데이터를 해당 위치에 저장하게 됩니다. n8n을 설치하려면 이미지를 다운로드 해야 하고, 내려받은 이미지를 실행하면 n8n 컨테이너가 만들어집니다. 그리고 n8n에서 작업한 데이터가 저장된 공간을 확인하려면 볼륨을 확인해야 합니다.
[05] 스타터 키트 설치하기
이제 도커에 n8n을 설치하겠습니다. 앞에서 우리는 n8n Self-hosted Starter Kit를 설치할 것이고, 이 스타터 키트는 깃을 통해 제공된다고 배웠습니다.
01단계 스타터 키트 설치를 위해 먼저 해당 깃허브 페이지에 접속합니다. 구글에 ‘n8n self hosted ai starter kit’를 검색하거나 브라우저 주소창에 URL을 입력하여 해당 페이지에 접속합니다.
스타터 키트 깃허브 : github.com/n8n-io/self-hosted-ai-starter-kit
02단계 스크롤을 아래로 내리면 ‘Installation’에 여러 명령어가 있습니다. ‘Running n8n using Docker Compose’에서 자신의 환경에 맞는 명령어를 찾아 실행하면 됩니다. 이 명령어는 총 네 줄로, 앞의 세 줄은 같고 마지막 줄만 환경에 따라 다릅니다. 우선 자기 환경에 맞는 명령어를 찾으세요.
03단계 혼동을 줄이기 위해 N8N이라는 폴더를 만들고, 해당 폴더의 주소창에 cmd를 입력한 다음 [Enter]를 눌러 명령 프롬프트를 실행합니다.
명령 프롬프트가 열리면 이제 깃허브 페이지의 명령어 코드를 실행합니다. 먼저 실행할 세 줄의 코드는 설치 준비 단계입니다. 코드는 다음과 같습니다.
```
git clone https://github.com/n8n-io/self-hosted-ai-starter-kit.git
cd self-hosted-ai-starter-kit
copy .env.example .env
```
코드를 한 줄씩 살펴봅시다. 우선 ➊ git clone~으로 시작하는 코드로 깃허브에서 스타터 키트 코드를 내려받습니다. 다음으로 ➋ cd 명령어를 이용해 내려받은 디렉터리로 이동합니다. 마지막으로 ➌ copy .env.example .env로 환경 설정 파일을 복사해서 사용합니다. 이때 .env 파일 안의 비밀번호, API 키, OLLAMA 설정 등은 필요하면 직접 수정해야 합니다. 여기까지의 코드를 한 줄씩 차례대로 명령 프롬프트에 붙여넣어 실행합니다.
04단계 코드를 실행하고 나면 N8N 폴더 하위에 self-hosted-ai-starter-kit라는 폴더가 생성됩니다. 그 안에 여러 파일과 폴더가 있는데, 그중 docker_compose.yml 파일을 메모장으로 엽니다. 파일을 보면 environment:라는 환경 변수 항목이 있습니다. 그 아래줄에 ‘N8N_SECURE_COOKIE=false’를 직접 입력합니다. 입력할 때는 그다음 줄과 공백이나 형식을 동일하게 맞춰줍니다.
이 항목을 추가하는 이유는 바로 접속 오류를 방지하기 위해서입니다. n8n은 기본적으로 보안을 위해 HTTPS(보안 연결)에서만 로그인 쿠키를 저장하는데, HTTP(비보안) 연결로 접속하면 오류가 발생합니다. http://localhost:5678이나 http://127.0.0.1:5678과 같이 우리가 사용하는 로컬 호스트는 HTTP로 접속하기 때문에 이 설정을 추가해주지 않으면 쿠키가 저장되지 않아 로그인 오류가 발생합니다.
[NOTE] 만약 n8n으로 나중에 외부에 서비스를 제공하게 된다면, 도메인을 연결하고 HTTPS 설정을 한 다음 이 설정을 True로 변경하여 운영하면 됩니다.
05단계 여기에 기본 시간대를 설정하는 환경 변수를 추가하겠습니다. n8n은 기본적으로 서버의 시간대가 UTC(협정세계시)로 설정되어 있습니다. 만약 워크플로에서 시간 데이터를 다루거나 시간을 설정해서 동작을 하게 한다면 우리가 생각한 시간과 n8n에서 처리하는 시간이 다를 수 있습니다. 이런 차이를 없애기 위해 n8n의 기본 설정 시간대를 한국 시간으로 변경해야 합니다. 시간대 설정은 두 개의 환경 변수를 추가해야 하는데, 시스템 시간대를 설정하는 TZ와 n8n 워크플로 내부의 시간대를 설정하는 GENERIC_TIMEZONE을 모두 설정해야 하기 때문입니다. TZ는 서버 로그나 시스템 차원의 시간 계산에 적용되고, GENERIC_TIMEZONE은 워크플로 내부에서 스케줄이나 시간 관련 노드의 기본 시간대로 사용됩니다.
앞에서 추가한 항목 위에 다시 또 새로운 줄을 추가하여 ‘TZ=Asia/Seoul’와 ‘GENERIC_TIMEZONE=Asia/Seoul’을 입력합니다. 마찬가지로 공백이나 형식은 다른 환경 변수 항목들과 동일하게 맞춰서 입력해야 합니다.
입력이 완료되면 파일을 저장합니다.
06단계 다시 명령 프롬프트로 돌아와서 마지막 줄의 코드를 실행합니다. 마지막 코드는 환경별로 Docker Compose 명령어가 다릅니다. NVIDIA GPU를 사용하는 경우, AMD GPU를 사용하는 경우(리눅스Linux), Mac M1/M2를 사용하는 경우, 마지막으로 GPU 없이 일반 CPU만 사용하는 경우로 나뉩니다. 자신의 환경에 맞게 코드를 선택하여 실행하세요. 예를 들어 일반 CPU 사용자의 때에는 위의 세 줄의 코드를 실행한 후 마지막에 다음의 코드를 실행합니다.
```
docker compose --profile cpu up
```
실행 도중 방화벽 확인이 뜨면 반드시 허용을 누르세요.
07단계 여기까지 완료됐으면 드디어 모든 설치가 끝났습니다. 이제 다시 도커로 돌아가 보면 컨테이너에 아까는 없었던 self-hosted ai-starter-kit가 설치된 것이 보일 겁니다.
➊ 이름 왼쪽의 화살표를 클릭해서 열어보면 스타터 키트에 포함된 많은 프로그램들이 보입니다. 그중 n8n을 찾아 ➋ Actions의 재생 버튼 [▷]을 클릭해 실행하세요.
08단계 postgres-1 컨테이너도 확인하고 실행 중이 아니라면 실행합니다. postgres는 PostgreSQL Database를 가리키고, 데이터베이스 서버를 의미합니다. 스타터 키트로 설치했으면 n8n을 실행할 때 데이터베이스 서버를 사용하도록 기본 설정이 되어 있습니다. 따라서 postgres가 실행 중이 아니면 n8n 오류가 발생하므로 항상 같이 실행해야 합니다.
09단계 n8n을 실행하면 n8n의 Port(s) 부분의 5678:5678이 활성화됩니다. 여기서 5678은 n8n이 내부적으로 웹 서비스를 구동할 때 사용하는 고정 기본 포트입니다. 활성화된 5678 포트를 클릭하면 브라우저 창이 열리면서 n8n에 접속합니다.
10단계 최초 접속하면 관리자 계정을 만드는 ‘Set up owner account’ 페이지가 열립니다. 여기에 메일과 이름, 비밀번호를 차례로 입력하여 계정을 만듭니다.
이 계정 생성은 어떤 서비스 가입을 하는 게 아니라 내 컴퓨터에서만 사용하는 정보이기 때문에 비밀번호를 잊어버리면 찾기 어렵습니다. 따라서 잘 기억할 수 있는 메일과 비밀번호를 사용해야 합니다. 계정 생성까지 완료하면 n8n에 접속할 수 있습니다.