자동화기초 01 안티그래비티로 n8n 로컬 설치(도커)까지 한 번에

작성자:

이번 시리즈는 n8n을 클라우드가 아니라 도커로 직접 설치(셀프호스팅)해서 쓰는 흐름을 다룹니다. 그 첫 편에서는 “내 PC에서 로컬로 n8n을 띄우는 것”을 목표로 하고, 이 과정을 안티그래비티(Antigravity)로 더 빠르고 안전하게 진행하는 방법까지 정리합니다.

이 글을 끝내면
  • Docker Compose로 n8n을 로컬에서 실행할 수 있고
  • http://localhost:5678로 접속해 n8n 화면을 확인할 수 있으며
  • 워크플로우/설정 데이터가 Docker 볼륨에 저장되어 컨테이너를 껐다 켜도 유지됩니다.

0. 시작 전: “안티그래비티로 설치”를 안전하게 쓰는 원칙

안티그래비티는 에이전트가 터미널 명령을 제안하고 실행까지 도울 수 있어 편하지만, 설치 과정은 파일 생성/명령 실행이 포함되므로 통제권은 항상 내가 쥐는 방식으로 진행하는 걸 추천합니다.

  • 명령 실행 전 승인(Review): 에이전트가 제안한 명령은 실행 전에 반드시 내가 확인
  • 파일 먼저, 명령 나중: compose.yaml 내용을 먼저 보여주게 하고, 그 다음 실행
  • 보안 규칙: 토큰/키/비밀번호는 채팅에 붙여넣지 않기 (환경변수로 분리)

1. 준비물 체크 (안티그래비티에게 시켜도 OK)

  • Docker Engine 또는 Docker Desktop 설치
  • 터미널에서 docker, docker compose 명령이 동작
  • 포트 5678 사용 가능 (이미 사용 중이면 포트 변경)

안티그래비티에 이렇게 말해보세요 (체크용 프롬프트)

내 PC에서 n8n을 Docker Compose로 로컬 실행하려고 해.
공식 문서 기준으로만 안내해줘.

먼저 아래를 확인하는 터미널 명령을 '실행 전에' 목록으로 보여줘:
- docker 설치 여부
- docker compose 사용 가능 여부
- 포트 5678 점유 여부(가능하면)

주의:
- 터미널 명령은 항상 내가 리뷰(승인)한 뒤에만 실행해.

2. 로컬 실행용 compose.yaml 만들기 (가장 단순한 시작)

로컬에서는 “일단 뜨는 것”이 중요합니다. 아래 구성은 볼륨으로 데이터가 유지되고, 타임존도 Asia/Seoul로 맞춰 둬서 스케줄 노드(Cron 등) 테스트할 때 덜 헷갈립니다. 

services:
  n8n:
    image: docker.n8n.io/n8nio/n8n
    restart: unless-stopped
    ports:
      - "5678:5678"
    environment:
      - N8N_PORT=5678
      - NODE_ENV=production
      - GENERIC_TIMEZONE=Asia/Seoul
      - TZ=Asia/Seoul
    volumes:
      - n8n_data:/home/node/.n8n

volumes:
  n8n_data:
왜 볼륨이 중요해요?

볼륨이 없으면 컨테이너를 내릴 때 워크플로우/설정이 함께 날아갈 수 있습니다. 위 구성은 /home/node/.n8n 경로를 볼륨에 연결해 데이터가 유지되도록 합니다.

안티그래비티에 이렇게 말해보세요 (파일 생성 프롬프트)

n8n을 로컬에서 Docker Compose로 실행하려고 해.
공식 문서 기준으로만 안내해줘.

해야 할 일:
1) n8n-local 폴더 만들기
2) compose.yaml 파일 생성(볼륨 포함, 포트 5678, 타임존 Asia/Seoul)
3) compose.yaml 내용을 먼저 보여주고 내가 확인하면 저장
4) 그 다음 실행 명령을 제안하고, 실행은 항상 리뷰(승인) 후 진행

3. 실행/중지/로그 확인

프로젝트 폴더(n8n-local) 안에서 아래 명령을 실행합니다.

# 실행
docker compose up -d

# 로그 확인(문제 생기면 제일 먼저)
docker compose logs -f

# 중지(데이터는 볼륨에 남음)
docker compose stop

실행 후 브라우저에서 http://localhost:5678 접속해서 n8n 화면이 뜨면 성공입니다.

4. 자주 막히는 포인트 3가지

1) 포트 충돌(5678 사용 중)

다른 앱이 5678을 쓰고 있으면 실행이 안 됩니다. 이 경우 포트를 바꾸거나 점유 앱을 종료해야 합니다. (포트를 바꾸려면 "5678:5678"의 앞쪽 숫자를 다른 값으로 변경)

2) Docker가 실행 중이 아님

Docker Desktop이 꺼져 있거나, 엔진이 떠 있지 않으면 compose 실행이 실패할 수 있습니다.

3) 데이터가 유지되지 않음

볼륨을 쓰지 않았거나, 볼륨을 삭제한 경우입니다. compose.yaml에 volumes 구성이 있는지 확인하세요.

다음 편 예고

2편에서는 로컬에서 Webhook 트리거를 실제로 테스트하면서, n8n의 데이터 흐름(트리거 → 처리 → 실행)을 몸으로 익히는 워크플로우를 만들어봅니다. 그리고 안티그래비티에게 “Import 가능한 워크플로우 JSON”을 뽑게 하는 기본 프롬프트도 살짝 맛봅니다.

댓글 남기기