2026년 9월 13일 내용 개정. 공식 문서와 대조해 설명과 예제를 정리했습니다. 설치 버전에 따라 화면과 옵션 이름은 달라질 수 있습니다.
이 글은 새 로컬 실습 환경에서 n8n 편집기를 실행하는 방법입니다. 이미 사용 중인 n8n의 데이터 경로나 데이터베이스를 바꾸는 이전 작업에는 그대로 적용하지 마세요. 설치를 시작하기 전에 기존 컨테이너가 있는지 먼저 확인합니다.
이 글에서 확인할 내용: 로컬 Docker 실습 환경을 실행하고 저장 볼륨·재시작·백업 범위를 확인합니다. 대표 사진과 본문 사진은 작업 환경 참고용입니다. 대표 사진: Fotis Fotopoulos / Unsplash.
1. 준비 상태와 설치 범위 확인
Docker Engine과 Compose v2가 필요합니다. Windows에서는 Docker Desktop의 WSL2 환경을 사용할 수 있습니다. 터미널에서 아래 명령을 한 줄씩 실행해 Docker가 응답하는지 확인하세요. n8n의 현재 공식 Compose 안내에는 Assistant용 추가 서비스도 포함되어 있습니다. 아래 예시는 일반 워크플로우 학습을 위한 최소 구성으로, Assistant 샌드박스까지 설치하는 구성은 아닙니다.
docker version
docker compose version
docker ps -aDocker 서버 연결 오류가 나오면 n8n 설정을 바꾸기 전에 Docker Desktop 또는 Engine부터 실행합니다. 기존 n8n 컨테이너가 있다면 포트와 저장 볼륨을 확인해 새 환경과 충돌하지 않게 하세요.
2. 새 폴더에 compose.yaml 만들기
n8n-practice라는 새 폴더를 만들고 아래 내용을 compose.yaml로 저장합니다. 메모장으로 저장할 때 compose.yaml.txt가 되지 않도록 실제 확장자를 확인하세요. 이미지 태그 stable은 이후 릴리스에 따라 바뀌므로, 장기 운영에서는 검증한 버전 번호로 고정하는 편이 재현에 유리합니다.
services:
n8n:
image: n8nio/n8n:stable
restart: unless-stopped
ports:
- "127.0.0.1:5678:5678"
environment:
TZ: Asia/Seoul
GENERIC_TIMEZONE: Asia/Seoul
N8N_ENFORCE_SETTINGS_FILE_PERMISSIONS: "true"
volumes:
- n8n_practice_data:/home/node/.n8n
volumes:
n8n_practice_data:127.0.0.1 바인딩은 이 PC에서 접속하는 실습용 설정입니다. 휴대폰이나 외부 서비스가 이 주소로 접근할 수는 없습니다. 볼륨은 컨테이너를 다시 만들어도 설정과 기본 SQLite 데이터를 보존하기 위한 것입니다. 프로젝트 폴더 이름이 바뀌면 Compose가 다른 볼륨을 만들 수 있으므로 사용한 폴더를 기록해 두세요.
3. 실행하고 편집기 열기
compose.yaml이 있는 폴더에서 다음 명령을 실행합니다. 첫 실행에는 이미지 다운로드 시간이 포함됩니다.
docker compose up -d
docker compose ps
docker compose logs --tail=80 n8n컨테이너가 실행 중이면 브라우저에서 http://localhost:5678을 엽니다. 처음 표시되는 소유자 계정 설정을 완료하고, 빈 워크플로우를 만들어 연습용 이름으로 저장하세요. 이것은 n8n Cloud 계정 가입과 별개의 로컬 인스턴스 설정입니다.
| 증상 | 먼저 확인할 것 |
|---|---|
| 페이지가 열리지 않음 | Docker 실행 상태와 compose ps 결과 |
| 포트 사용 중 | 기존 5678 서비스 확인 후 호스트 포트만 5679 등으로 변경 |
| 계속 재시작 | logs에 기록된 첫 오류와 디스크·권한 상태 |
| 기존 워크플로우가 안 보임 | 다른 프로젝트 폴더 또는 다른 볼륨으로 실행했는지 |
| 예약 작업 시간 불일치 | 워크플로우 시간대와 Asia/Seoul 설정 |
4. 데이터가 유지되는지 확인하기
실습용 워크플로우를 만든 후 아래 재시작 명령을 실행합니다. 다시 접속했을 때 같은 계정과 워크플로우가 보이는지 확인하세요. 재시작 성공은 볼륨 설정을 확인하는 과정이며, 별도 백업을 대신하지 않습니다.
docker compose restart n8n중지할 때는 docker compose stop, 다시 시작할 때는 docker compose start를 사용할 수 있습니다. 볼륨 삭제 옵션이나 Docker의 데이터 초기화를 사용하면 저장 내용이 사라질 수 있으므로 데이터 보존이 필요한 상태에서는 실행하지 마세요.
5. 업데이트·백업·외부 접속의 경계
업데이트 전에는 워크플로우 내보내기와 함께 데이터베이스, .n8n 볼륨, 별도로 설정한 암호화 키를 복구할 수 있도록 백업합니다. SQLite 파일 복사는 쓰기를 멈춘 상태에서 수행하는 등 일관성을 확보해야 합니다. 내보낸 워크플로우 JSON만으로 자격 증명까지 모두 복구되는 것은 아닙니다.
릴리스 변경 사항과 백업을 확인한 뒤 docker compose pull 및 docker compose up -d로 새 이미지를 적용할 수 있습니다. 이전 버전으로 되돌릴 때 데이터베이스 변경 때문에 단순 이미지 교체만으로 해결되지 않을 수 있습니다. 외부 Webhook이 필요해지면 HTTPS·인증·프록시 주소 설정을 갖춘 별도 배포 절차로 진행하세요.
검증 범위: 공식 문서의 설치·저장 방식과 대조한 로컬 실습 구성입니다. 독자의 PC에서 설치 실행을 대신 확인한 결과는 아니며, 설치 버전과 로그를 함께 확인해야 합니다.