n8n 아키텍처와 도커 로컬 배포 - n8n 파이프라인 구축 시리즈 1편n8n Architecture and Docker Local Setup - n8n Pipeline Building Series Part 1
📅
들어가기 전에 🔗
오늘은 자동화 파이프라인 구축 시리즈의 본격적인 첫 번째 시간입니다.
이전 시간에는 다양한 플랫폼 중에서 우리가 사용할 도구를 선정해 보았습니다.
이번 포스팅에서는 선택한 도구의 내부 작동 원리를 컴퓨터 과학의 기본 개념과 함께 이해하고 직접 개인 컴퓨터에 설치해 보는 실습을 진행하겠습니다.
도커라는 훌륭한 가상화 도구를 활용하여 복잡한 설정 없이 간편하게 나만의 작업 공간을 만드는 과정을 하나씩 차근차근 설명해 드리겠습니다.
엔에잇엔 코어 개념 이해하기 🔗
프로그램을 직접 설치하기 전에 이 도구가 내부적으로 어떻게 돌아가는지 이해하는 것은 매우 중요합니다.
시스템의 뼈대를 이루는 두 가지 핵심 개념을 먼저 살펴보겠습니다.
노드 기반 이벤트 드리븐 아키텍처 🔗
자동화 파이프라인은 특정 조건이 만족되었을 때 다음 작업이 실행되는 방식으로 움직입니다.
이러한 방식을 소프트웨어 공학에서는
이벤트 드리븐
(Event-driven) 구조라고 부릅니다.이 구조는 자료구조의
큐
(Queue) 개념과 아주 밀접하게 연결되어 있습니다.
식당에서 주문이 들어온 순서대로 대기열에 차곡차곡 쌓인 뒤 요리사가 하나씩 꺼내어 처리하는 모습을 상상해 보시면 이해하기 쉽습니다.마찬가지로 메신저 알림이나 이메일 수신 같은 이벤트가 발생하면 큐 자료구조에 차례대로 담기게 됩니다.
이후 시스템이 큐에서 이벤트를 하나씩 꺼내어 선으로 연결된 다음 노드들에게 전달하고 정해진 작업을 수행하게 됩니다.
실행 라이프사이클 🔗
하나의 작업이 시작되고 끝나는 전체 과정을 실행 라이프사이클이라고 합니다.
작업이 큐에서 대기하는 상태를 시작으로 실행 중 상태를 거쳐 최종적으로 성공 또는 실패 상태로 마무리됩니다.
이러한 상태 변화를 시스템이 꼼꼼하게 추적하기 때문에 중간에 오류가 발생하더라도 어느 지점에서 문제가 생겼는지 쉽게 찾아낼 수 있습니다.
이벤트가 발생하여 큐에 쌓이고 각 노드를 거쳐 실행이 완료되는 라이프사이클 다이어그램
도커 설치와 사전 준비 🔗
이제 본격적인 설치를 시작하겠습니다.
우리는 복잡한 설정이나 운영체제 충돌을 피하기 위해 도커라는 훌륭한 가상화 도구를 사용할 것입니다.
운영체제별 도커 설치 가이드 🔗
도커를 사용하려면 먼저 내 컴퓨터에 도커 프로그램을 설치해야 합니다.
Mac OS와 Windows 사용자분들은 인터넷 브라우저를 열고
도커 데스크탑
(Docker Desktop) 공식 홈페이지에 접속해 주시기 바랍니다.
도커 데스크탑 다운로드 페이지↗에서 자신의 운영체제에 맞는 설치 파일을 내려받아 설치를 진행해 주시면 됩니다.홈페이지 화면에 보이는 커다란 다운로드 버튼을 눌러 설치 파일을 내려받은 뒤 평소 프로그램을 설치하듯 다음 버튼을 눌러 설치를 완료해 주시면 됩니다.
Linux 사용자분들은 터미널에서 패키지 관리자를 이용해 도커 엔진과 도커 컴포즈를 각각 설치해 주셔야 합니다.
설치가 끝났다면 도커 데스크탑 프로그램을 더블클릭하여 실행해 둡니다.
실행 후 터미널에서
docker --version 명령어를 입력하여 도커가 정상적으로 설치되고 실행되고 있는지 확인해 보시기 바랍니다.
만약, zsh: command not found: docker 라는 메시지가 나타난다면 시스템 경로에 도커가 제대로 추가되지 않은 것입니다.vi ~/.zshrc
# 파일이 열리면 아래의 줄을 추가해 줍니다.
# export PATH="/Applications/Docker.app/Contents/Resources/bin:$PATH"
# 저장 후 파일을 닫고 아래의 명령어로 변경 사항을 적용합니다.
source ~/.zshrc
# 다시 도커 버전을 확인해 봅니다.
docker --version왜 PostgreSQL을 사용할까요 🔗
시스템을 처음 설치하면 내부에 기본적으로
SQLite
라는 가벼운 데이터베이스가 들어 있습니다.
하지만 우리가 앞으로 다룰 방대한 양의 뉴스 기사와 복잡한 자동화 기록들을 안전하게 보관하기 위해서 다른 관계형 DB를 사용하고자 합니다.포스트그레스큐엘
(PostgreSQL)은 전 세계 수많은 기업이 사용하는 아주 강력하고 안정적인 데이터베이스입니다.
처음 구축할 때 조금 번거롭더라도 이를 연결해 두면 나중에 시스템이 멈추거나 데이터가 날아가는 불상사를 완벽하게 막을 수 있습니다.PostgreSQL 기반 시스템 구축 실습 🔗
지금부터는 키보드를 사용해 직접 명령어를 입력해 보겠습니다.
Mac OS 사용자는
터미널
(Terminal) 앱을 열어주시고 Windows 사용자는 명령 프롬프트
(cmd) 혹은 파워쉘
(PowerShell)을 열어주시기 바랍니다.1단계 작업 폴더 만들기 🔗
가장 먼저 우리가 작업할 안전한 폴더를 하나 만들어야 합니다.
터미널 창에 아래의 명령어들을 한 줄씩 입력하고 키보드의 엔터(Enter) 키를 눌러주시기 바랍니다.
# n8n-local 이라는 이름의 새로운 폴더를 생성합니다.
mkdir n8n-local
# 방금 만든 n8n-local 폴더 안으로 이동합니다.
cd n8n-local화면에 특별한 메시지가 나타나지 않고 입력 줄이 다음으로 넘어갔다면 성공적으로 폴더가 만들어지고 이동된 것입니다.
2단계 도커 컴포즈 파일 작성하기 🔗
이제 도커에게 포스트그레스큐엘 데이터베이스와 엔에잇엔 시스템을 어떻게 연결할지 알려주는 설계도를 그릴 차례입니다.
현재 폴더 안에
docker-compose.yml
이라는 이름의 텍스트 파일을 새로 만들어 주시기 바랍니다.메모장이나 비주얼 스튜디오 코드 같은 편집기를 열어 방금 만든 빈 파일에 아래의 내용을 그대로 복사해서 붙여넣고 저장해 줍니다.
# 도커 컴포즈 파일의 버전을 명시합니다.
version: '3.8'
# 우리가 실행할 두 개의 창고(서비스)를 정의합니다.
services:
# 첫 번째 서비스: 포스트그레스큐엘 데이터베이스
postgres:
image: postgres:16
restart: always
environment:
# 데이터베이스 접속에 필요한 비밀번호와 사용자 이름을 설정합니다.
- POSTGRES_USER=n8n_db_user
- POSTGRES_PASSWORD=n8n_db_password
- POSTGRES_DB=n8n_database
volumes:
# 데이터베이스의 정보가 컴퓨터에 영구적으로 저장되도록 다리를 연결합니다.
- db_data:/var/lib/postgresql/data
# 두 번째 서비스: 엔에잇엔 자동화 플랫폼
n8n:
image: docker.n8n.io/n8nio/n8n:latest
restart: always
ports:
- "5678:5678"
environment:
# 시스템이 한국 시간을 정확히 인식하도록 설정합니다.
- GENERIC_TIMEZONE=Asia/Seoul
- TZ=Asia/Seoul
- N8N_ENFORCE_SETTINGS_FILE_PERMISSIONS=true
- N8N_RUNNERS_ENABLED=true
# 방금 위에서 만든 데이터베이스와 연결해 주는 핵심 설정입니다.
- DB_TYPE=postgresdb
- DB_POSTGRESDB_DATABASE=n8n_database
- DB_POSTGRESDB_HOST=postgres
- DB_POSTGRESDB_PORT=5432
- DB_POSTGRESDB_USER=n8n_db_user
- DB_POSTGRESDB_SCHEMA=public
- DB_POSTGRESDB_PASSWORD=n8n_db_password
depends_on:
# 데이터베이스가 먼저 켜진 후에 시스템이 켜지도록 순서를 정해줍니다.
- postgres
volumes:
- n8n_data:/home/node/.n8n
# 데이터를 영구적으로 보존하기 위한 가상의 저장 공간(볼륨)을 선언합니다.
volumes:
db_data:
n8n_data:위 코드에서 주의 깊게 보실 부분은
환경 변수
(environment) 영역입니다.
엔에잇엔 시스템이 데이터베이스에 접속하기 위해 필요한 아이디와 비밀번호를 꼼꼼하게 적어두어 두 시스템이 안전하게 소통할 수 있도록 만들어 주었습니다.3단계 시스템 실행하기 🔗
설계도 저장을 마쳤다면 다시 터미널 창으로 돌아옵니다.
이제 도커에게 우리가 만든 설계도대로 공장을 가동하라고 명령을 내릴 차례입니다.
아래의 명령어를 터미널에 입력하고 엔터 키를 눌러주시기 바랍니다.
docker compose up -d화면에 초록색 혹은 파란색 글씨로
Started
라는 문구가 여러 개 나타나면 모든 설치와 실행이 완벽하게 끝난 것입니다.
인터넷 환경에 따라 도커 이미지를 다운로드하는 데 몇 분 정도 시간이 걸릴 수 있으니 차분히 기다려 주시기 바랍니다.
시스템 실행 완료
접속 테스트 및 초기 세팅 🔗
실행이 완료되었다면 웹 브라우저를 열고 주소창에
localhost:5678을 입력한 뒤 접속해 줍니다.
방금 우리가 설정한 5678번 포트 다리를 타고 도커 내부의 시스템으로 무사히 접속하게 됩니다.화면에 최고 관리자 계정을 생성하는 창이 나타나면 안전한 이메일과 비밀번호를 입력하여 계정을 만들어 주시기 바랍니다.
이제 강력한 포스트그레스큐엘 데이터베이스가 연결된 나만의 완벽한 자동화 공장이 완성되었습니다.
로그인 후 이 화면이 나오면 성공입니다
결론 🔗
오늘은 시스템의 뼈대인 이벤트 드리븐과 큐 자료구조를 이해하고 도커를 이용해 로컬 환경에 시스템을 구축하는 모든 과정을 차근차근 실습해 보았습니다.
특히 대용량 데이터를 다루기 위해 포스트그레스큐엘을 연동하는 조금 복잡한 과정까지 무사히 마쳤습니다.
어려운 명령어를 하나하나 따라오시느라 정말 고생 많으셨습니다.
다음 2편에서는 이렇게 튼튼하게 지어진 공장의 첫 번째 작업인 뉴스 피드 스케줄링 수집 로직을 직접 만들어 보겠습니다.