부록 16. Docker Desktop 설치 가이드 (Windows)
📋 개요 책의 설치 가이드대로
docker compose로 n8n을 띄우려면, 먼저 내 컴퓨터에 Docker Desktop이 설치되어 실행 중이어야 합니다. 이 부록은 Windows에 Docker Desktop을 설치하고 동작을 확인하는 과정, 그리고http://localhost:5678접속이 안 될 때의 점검 순서를 안내합니다.
결론부터 말씀드리면, 설치 자체는 10분이면 끝납니다. 다만 초보자분들이 가장 많이 막히는 자리는 설치가 아니라 "Docker Desktop을 켜지 않은 채 명령만 실행한 경우" 예요. 이 부분은 아래 "자주 만나는 문제"에서 따로 짚어 드립니다.
💡 공식 다운로드: https://www.docker.com/
왜 Docker가 필요한가요
Docker는 내 컴퓨터 안에 "작은 가상 컴퓨터"를 띄워 주는 도구입니다. 이 작은 컴퓨터(컨테이너) 한 대마다 따로 살림이 차려져 있어서, 안에서 무엇을 깔거나 망가뜨려도 본 컴퓨터에는 영향이 가지 않습니다.
n8n과의 관계
n8n을 내 컴퓨터에서 직접 운영하려면(Self-hosted) n8n 프로그램과 그 실행 환경이 함께 필요합니다. Docker를 쓰면 이 둘이 한 묶음(이미지)으로 내려와서, 명령 한 줄로 n8n이 켜집니다.
- 내 컴퓨터에 다른 프로그램을 따로 깔 필요가 없습니다.
- 문제가 생기면 컨테이너만 지우고 다시 띄우면 됩니다. 본 컴퓨터는 깨끗하게 유지됩니다.
- 워크플로와 인증 정보는 별도 저장 공간(볼륨)에 남으므로, 컨테이너를 다시 만들어도 사라지지 않습니다.
Docker Desktop은 무엇인가요
Docker Desktop은 Docker를 Windows와 Mac에서 쉽게 쓸 수 있도록 만든 공식 앱입니다. 이 앱이 켜져 있는 동안에만 docker 명령과 n8n 컨테이너가 동작합니다. 앱을 끄면 n8n도 함께 멈춥니다.
시스템 요구사항
설치 전에 본인 컴퓨터가 다음 요건을 만족하는지 확인하세요. 최근 5년 안에 산 노트북이면 대부분 통과합니다.
- CPU 가상화 지원 (Intel VT-x 또는 AMD-V). BIOS에서 켜져 있어야 합니다.
- RAM: 최소 4GB, 권장 8GB 이상
- 디스크 여유 공간: 4GB 이상
- 운영체제: Windows 10 또는 Windows 11
설치 과정
1단계. Docker Desktop 다운로드와 설치 마법사 실행
공식 사이트(https://www.docker.com)에서 Download for Windows를 클릭해 설치 파일을 받습니다. 다운로드된 Docker Desktop Installer.exe를 더블 클릭하면 마법사가 열립니다.
최신 설치 프로그램에서는 아래와 같은 Configuration 화면이 먼저 나옵니다. 기본으로 선택된 Per-user installation (Recommended) 을 그대로 두고 OK를 누르세요.
| 선택지 | 의미 | n8n 실습에서는 |
|---|---|---|
| Per-user installation (Recommended) | 지금 로그인한 계정에만 설치합니다. 관리자 암호가 필요 없고 WSL 2 방식으로 동작합니다 | 이쪽을 선택 |
| All-users installation (Requires password) | PC의 모든 계정에 설치합니다. 관리자 암호가 필요합니다 | 선택하지 않아도 됩니다 |
| Add shortcut to desktop | 바탕화면에 바로가기를 만듭니다 | 체크한 그대로 두면 편합니다 |
💡 설치 프로그램 버전에 따라 화면이 조금씩 다릅니다. 이 화면 대신 아래처럼 체크박스가 있는 옵션 화면이 나올 수도 있는데, 어느 쪽이든 기본값 그대로 진행하시면 됩니다.
옵션 화면에서는 WSL 2 활성화 항목이 체크돼 있는지 확인하세요. 권장 옵션이고, 체크돼 있으면 필요한 Linux 커널을 자동으로 함께 깔아 줍니다.
2단계. Docker Desktop 실행
설치가 끝나면 시작 메뉴에서 Docker Desktop을 검색해 실행합니다. 첫 실행 때 라이선스 동의 화면과 간단한 설문이 나오면 그대로 넘기시면 됩니다.
3단계. WSL 2 안내 따라가기
WSL 2가 아직 활성화되지 않은 컴퓨터에서는 Docker Desktop이 안내 팝업을 띄웁니다. 안내된 링크를 클릭해 Microsoft 공식 페이지의 설명대로 따라가면 Linux 커널이 자동으로 깔립니다. 안내가 끝나면 컴퓨터를 한 번 재부팅합니다.
4단계. 재부팅 후 실행 확인
재부팅이 끝나면 Docker Desktop을 다시 실행합니다. 창 왼쪽 아래의 고래 아이콘이 초록색이고 Engine running이라고 표시되면 정상 동작 상태입니다.
⚠️ 컴퓨터를 켤 때마다 확인하세요. Docker Desktop이 자동 실행되지 않도록 설정돼 있으면, 재부팅 후에는 직접 켜 주셔야 n8n도 다시 동작합니다.
5단계. 명령줄에서 설치 확인
PowerShell을 새로 열고 아래 명령을 입력합니다.
docker version
Client와 Server 양쪽 버전 정보가 함께 출력되면 설치가 완료된 것입니다.
💡 Client 정보만 나오고 Server 쪽에 오류가 나온다면, Docker Desktop이 꺼져 있다는 뜻입니다. 앱을 켠 뒤 다시 실행해 보세요.
설치 후 n8n 실행 확인
Docker Desktop이 켜진 상태에서, 책의 설치 가이드에서 만든 docker-compose.yml 파일이 있는 폴더로 이동해 아래 명령을 실행합니다.
docker compose up -d
docker compose ps
docker compose ps 결과에서 STATUS가 Up이고 PORTS에 0.0.0.0:5678->5678/tcp가 보이면 성공입니다. 이제 브라우저 주소창에 http://localhost:5678을 입력하면 n8n 계정 생성 화면이 나타납니다.
💡 처음 실행할 때는 n8n 이미지를 내려받느라 몇 분이 걸릴 수 있습니다. 다운로드가 끝나고 1~2분 뒤에 접속해 보세요.
자주 만나는 문제
localhost:5678에 접속하면 "사이트에 연결할 수 없음"이 나옵니다
브라우저에 "localhost에서 연결을 거부했습니다" 와 함께 ERR_CONNECTION_REFUSED가 표시되는 경우입니다. 주소를 잘못 입력한 것이 아닙니다. 5678번 포트에서 응답하는 n8n이 지금 떠 있지 않다는 뜻이에요. 당황하지 마시고 아래 순서대로 확인해 보세요.
1. Docker Desktop이 켜져 있는지 확인합니다.
작업 표시줄 오른쪽 아래(안 보이면 ^ 버튼 안쪽)에 고래 아이콘이 있는지 봅니다. 없으면 시작 메뉴에서 Docker Desktop을 실행하고 Engine running이 뜰 때까지 기다립니다.
2. docker-compose.yml이 있는 폴더에서 컨테이너 상태를 확인합니다.
docker compose ps -a
| 결과 | 의미 | 해결법 |
|---|---|---|
| 목록이 비어 있음 | 컨테이너가 만들어지지 않음 | docker compose up -d를 다시 실행하고 오류 메시지를 확인 |
no configuration file provided | 다른 폴더에서 명령을 실행함 | cd로 docker-compose.yml이 있는 폴더로 이동한 뒤 다시 실행 |
STATUS가 Exited 또는 Restarting | 컨테이너가 뜨다가 종료됨 | 아래 3번의 로그를 확인 |
STATUS는 Up인데 PORTS가 비어 있음 | 포트 연결 설정이 빠짐 | docker-compose.yml의 ports: 아래에 - "5678:5678"이 있는지, 들여쓰기가 맞는지 확인 |
3. 로그를 확인합니다.
docker compose logs --tail 50
로그에 아래 문장이 보이면 n8n이 정상적으로 켜진 것입니다.
Editor is now accessible via:
http://localhost:5678
이 문장 대신 오류가 보인다면, 그 내용이 원인입니다. 해결이 어려우면 오류 부분을 그대로 복사해 커뮤니티에 질문해 주세요.
4. 그래도 안 되면 주소를 바꿔 접속해 봅니다.
http://127.0.0.1:5678로 접속해 보세요. 일부 환경에서는 localhost가 다른 주소로 해석되어 접속이 안 되는 경우가 있습니다.
설치·실행 단계의 문제
| 증상 | 원인 | 해결법 |
|---|---|---|
| "가상화가 사용 안 함" 오류 | BIOS에서 가상화 기능이 꺼져 있음 | BIOS에서 Intel VT-x 또는 AMD-V 옵션을 켭니다. 진입 키(F2, Del 등)는 제조사마다 다르니 노트북 모델명으로 검색하세요 |
| WSL 2 커널 자동 설치 실패 | WSL이 오래된 버전임 | PowerShell을 관리자 권한으로 열고 wsl --update를 실행합니다 |
| 고래 아이콘이 계속 주황색 | WSL 연동이 꺼져 있음 | Docker Desktop 오른쪽 위 톱니바퀴 → Resources → WSL Integration에서 토글이 켜져 있는지 확인합니다 |
docker 명령을 찾을 수 없다는 오류 | 설치 전에 열어 둔 터미널을 그대로 사용함 | PowerShell 창을 닫고 새로 엽니다 |
port is already allocated 오류 | 5678번 포트를 다른 프로그램이 사용 중 | 이전에 띄운 n8n 컨테이너가 남아 있는지 docker ps -a로 확인하고 정리합니다 |
마무리
Docker Desktop이 켜져 있고, docker compose ps에서 n8n이 Up 상태이며, http://localhost:5678에서 n8n 화면이 보이면 준비가 끝난 것입니다. 이제 책으로 돌아가 계정을 만들고 첫 워크플로를 시작해 보세요.
진행하시다가 막히는 부분이 생기면
docker compose ps -a와docker compose logs --tail 50의 출력 화면을 함께 올려 커뮤니티에 질문해 주세요. 원인을 훨씬 빨리 찾을 수 있습니다.