N8N Self-Hosting: NPM + Systemd 구성

N8N Self-Hosting: NPM + Systemd 구성

• 사전 요구 사항
• 1단계: 시스템 업데이트 및 필수 패키지 설치
• 2단계: n8n 설치
• 3단계: 환경 변수 설정
• 4단계: systemd 서비스 설정
• 5단계: 보안 및 추가 설정 (선택 사항)
• 6단계: 유지보수 및 업데이트
• 7단계: 최종 확인
• 참고 자료
• 마무리
• Keywords

Ubuntu에서 n8n을 npm을 통해 설치하고, systemd를 사용해 데몬으로 실행하는 방법을 단계별로 자세히 설명하겠습니다. 아래는 전체 프로세스를 명확하고 체계적으로 정리한 가이드입니다. 각 단계는 초보자도 따라 할 수 있도록 상세히 설명하며, 필요한 명령어와 설정을 포함합니다.

---

사전 요구 사항

시작하기 전에 다음 조건을 확인하세요:

• 운영 체제: Ubuntu 20.04 LTS 또는 22.04 LTS (최신 LTS 버전 권장)
• 권한: 루트 또는 sudo 권한이 있는 사용자 계정
• 네트워크: SSH를 통해 서버에 접근 가능
• 필수 소프트웨어:
  • Node.js (LTS 버전, 예: 18.x 또는 20.x)
  • npm (Node.js와 함께 설치됨)
  • systemd (Ubuntu에 기본 포함)

---

1단계: 시스템 업데이트 및 필수 패키지 설치

먼저, Ubuntu 시스템을 최신 상태로 유지하고 필요한 종속성을 설치합니다.

1. 시스템 업데이트:

   sudo apt update && sudo apt upgrade -y

   • 이 명령은 패키지 목록을 업데이트하고 모든 패키지를 최신 버전으로 업그레이드합니다.

2. Node.js와 npm 설치:
   n8n은 Node.js 환경에서 실행되므로, Node.js LTS 버전을 설치합니다. NodeSource 저장소를 사용해 최신 LTS 버전을 설치합니다.

   curl -fsSL https://deb.nodesource.com/setup_20.x | sudo bash -
   sudo apt-get install -y nodejs

   • setup_20.x는 Node.js 20.x 버전을 설치합니다. 필요 시 setup_18.x로 변경 가능.
   • 설치 후 버전 확인:

     node -v
     npm -v

     예: v20.17.0 (Node.js)와 10.8.3 (npm) 같은 출력이 나와야 합니다.

3. 기타 필수 패키지 설치 (선택 사항):

   sudo apt install -y build-essential

   • 일부 npm 패키지 컴파일에 필요할 수 있습니다.

---

2단계: n8n 설치

npm을 사용해 n8n을 글로벌로 설치합니다.

1. n8n 글로벌 설치:

   sudo npm install -g n8n

   • -g 플래그는 n8n을 시스템 전역에 설치합니다.
   • 설치가 완료되면 n8n 버전을 확인:

     n8n -v

     예: 1.93.0 (2025년 5월 기준 최신 버전).

2. n8n 실행 테스트:
   설치가 잘 되었는지 확인하기 위해 n8n을 수동으로 실행해봅니다.

   n8n

   • 기본적으로 n8n은 포트 5678에서 실행되며, 브라우저에서 http://<서버_IP>:5678로 접속해 확인할 수 있습니다.
   • 접속 후 계정 설정 화면이 나타나면 성공입니다. 설정은 나중에 진행하므로, Ctrl+C로 종료합니다.

3. n8n 데이터 디렉토리 확인:
   n8n은 설정과 워크플로우 데이터를 ~/.n8n 디렉토리에 저장합니다. 디렉토리 권한을 확인합니다:

   ls -ld ~/.n8n

   • 필요 시 권한 수정:

     sudo chown -R $USER:$USER ~/.n8n
     sudo chmod -R 755 ~/.n8n

---

3단계: 환경 변수 설정

n8n의 동작을 사용자 정의하려면 환경 변수를 설정합니다. 이는 보안, 포트, 호스트 등을 제어하는 데 사용됩니다.

1. 환경 변수 파일 생성:
   홈 디렉토리에 .env 파일을 생성합니다:

   nano ~/.n8n/.env

   아래는 기본적인 환경 변수 예시입니다:

   N8N_HOST=0.0.0.0
   N8N_PORT=5678
   N8N_PROTOCOL=http
   N8N_BASIC_AUTH_ACTIVE=true
   N8N_BASIC_AUTH_USER=your_username
   N8N_BASIC_AUTH_PASSWORD=your_secure_password
   WEBHOOK_URL=http://<your_server_ip_or_domain>:5678/
   N8N_ENCRYPTION_KEY=your_secret_encryption_key
   GENERIC_TIMEZONE=Asia/Seoul

   • N8N_HOST: 모든 IP에서 접근 가능하도록 0.0.0.0 설정.
   • N8N_PORT: 기본 포트 5678. 필요 시 변경.
   • N8N_BASIC_AUTH_*: 기본 인증 활성화 및 사용자 설정.
   • WEBHOOK_URL: 웹훅 호출을 위한 공용 URL.
   • N8N_ENCRYPTION_KEY: 데이터 암호화용 고유 키(랜덤 문자열 권장).
   • GENERIC_TIMEZONE: 서버 시간대 설정(한국은 Asia/Seoul).
   • 저장 후 파일 닫기: Ctrl+O, Enter, Ctrl+X.

2. 환경 변수 로드 확인:
   환경 변수를 적용하려면 n8n을 실행할 때 자동으로 로드됩니다. 테스트로 다시 실행:

   n8n

   • 브라우저에서 http://<서버_IP>:5678 접속 시 인증 창이 나타나면 성공.

---

4단계: systemd 서비스 설정

n8n을 시스템 부팅 시 자동으로 실행되도록 systemd 서비스로 설정합니다.

1. systemd 서비스 파일 생성:
   systemd 유닛 파일을 생성합니다:

   sudo nano /etc/systemd/system/n8n.service

   아래 내용을 붙여넣고, <your_username>을 실제 사용자 이름으로 변경:

   [Unit]
   Description=n8n Workflow Automation Tool
   After=network.target
   
   [Service]
   Type=simple
   User=<your_username>
   EnvironmentFile=/home/<your_username>/.n8n/.env
   ExecStart=/usr/bin/n8n
   Restart=always
   WorkingDirectory=/home/<your_username>/.n8n
   
   [Install]
   WantedBy=multi-user.target

   • User: n8n을 실행할 사용자 계정. 루트가 아닌 일반 사용자를 권장.
   • EnvironmentFile: 환경 변수 파일 경로.
   • ExecStart: n8n 실행 명령어. 글로벌 설치 시 /usr/bin/n8n 사용.
   • WorkingDirectory: n8n 데이터 디렉토리.
   • 저장 후 파일 닫기: Ctrl+O, Enter, Ctrl+X.

2. systemd 서비스 활성화 및 시작:
   systemd에 서비스를 등록하고 시작합니다:

   sudo systemctl daemon-reload
   sudo systemctl enable n8n
   sudo systemctl start n8n

   • daemon-reload: systemd 설정 변경 적용.
   • enable: 부팅 시 자동 시작.
   • start: 즉시 서비스 시작.

3. 서비스 상태 확인:
   서비스가 정상적으로 실행 중인지 확인합니다:

   sudo systemctl status n8n

   • active (running) 상태면 성공입니다. 오류가 있다면 로그를 확인:

     journalctl -u n8n -b

4. 브라우저에서 확인:
   http://<서버_IP>:5678로 접속해 n8n이 실행 중인지 확인합니다. 인증 정보 입력 후 워크플로우 편집 화면이 나타나면 성공입니다.

---

5단계: 보안 및 추가 설정 (선택 사항)

n8n을 안전하게 운영하려면 추가 설정이 필요합니다.

1. 방화벽 설정:
   UFW를 사용해 필요한 포트만 엽니다:

   sudo apt install ufw -y
   sudo ufw allow 22
   sudo ufw allow 5678
   sudo ufw enable

   • SSH(22)와 n8n(5678) 포트 허용.
   • HTTPS를 사용할 경우 443 포트를 추가로 엽니다.

2. SSL/TLS 설정 (Nginx + Certbot):
   HTTPS를 위해 Nginx와 Certbot을 설정합니다.

   • Nginx 설치:

     sudo apt install nginx -y

   • Nginx 설정 파일 생성:

     sudo nano /etc/nginx/sites-available/n8n

     아래 내용을 추가(도메인 이름은 your_domain.com으로 변경):

     server {
         listen 80;
         server_name your_domain.com;
     
         location / {
             proxy_pass http://localhost:5678;
             proxy_set_header Host $host;
             proxy_set_header X-Real-IP $remote_addr;
             proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
             proxy_set_header X-Forwarded-Proto $scheme;
         }
     }

     • 설정 활성화:

       sudo ln -s /etc/nginx/sites-available/n8n /etc/nginx/sites-enabled/
       sudo nginx -t
       sudo systemctl restart nginx

   • Certbot으로 SSL 설정:

     sudo apt install certbot python3-certbot-nginx -y
     sudo certbot --nginx -d your_domain.com

     • Certbot이 자동으로 Nginx 설정을 HTTPS로 업데이트합니다.
     • 환경 변수 업데이트:

       nano ~/.n8n/.env

       N8N_PROTOCOL=http를 N8N_PROTOCOL=https로 변경하고, WEBHOOK_URL도 https://your_domain.com/로 수정.

3. 데이터베이스 설정 (선택 사항):
   기본적으로 n8n은 SQLite를 사용하지만, 프로덕션 환경에서는 PostgreSQL 또는 MySQL을 권장합니다. 예: PostgreSQL 설정:

   • 설치:

     sudo apt install postgresql postgresql-contrib -y

   • 데이터베이스 및 사용자 생성:

     sudo -u postgres psql
     CREATE DATABASE n8n;
     CREATE USER n8n_user WITH PASSWORD 'your_password';
     GRANT ALL PRIVILEGES ON DATABASE n8n TO n8n_user;
     \q

   • .env 파일에 추가:

     DB_TYPE=postgresdb
     DB_POSTGRESDB_HOST=localhost
     DB_POSTGRESDB_PORT=5432
     DB_POSTGRESDB_DATABASE=n8n
     DB_POSTGRESDB_USER=n8n_user
     DB_POSTGRESDB_PASSWORD=your_password

   • n8n 서비스 재시작:

     sudo systemctl restart n8n

---

6단계: 유지보수 및 업데이트

1. n8n 업데이트:
   npm으로 설치한 n8n은 다음 명령어로 업데이트합니다:

   sudo npm install -g n8n@latest
   sudo systemctl restart n8n

2. 로그 확인:
   문제가 발생하면 systemd 로그를 확인합니다:

   journalctl -u n8n -b

3. 백업:
   ~/.n8n 디렉토리를 정기적으로 백업합니다:

   tar -czf n8n_backup_$(date +%F).tar.gz ~/.n8n

---

7단계: 최종 확인

• 브라우저에서 http://<서버_IP>:5678 또는 https://your_domain.com에 접속해 n8n이 정상 작동하는지 확인.
• 워크플로우 생성 및 테스트를 통해 기능 점검.
• 방화벽 및 인증 설정이 제대로 적용되었는지 확인.

---

참고 자료

• n8n 공식 문서: https://docs.n8n.io[](https://docs.n8n.io/hosting/)
• systemd 서비스 설정 예시: https://sysadmin.info.pl[](https://sysadmin.info.pl/en/blog/how-to-install-n8n-and-run-it-during-boot-thanks-systemd-unit/)
• Nginx 및 Certbot 설정: https://medium.com/@SebastianTorralba[](https://medium.com/%40sebastiantorralba/how-to-install-n8n-on-ubuntu-with-https-e4070beb51e4)

마무리

이 가이드를 통해 n8n을 Ubuntu 환경에서 성공적으로 설치하고, systemd를 사용해 안정적으로 운영할 수 있는 방법을 배웠습니다. 추가적인 보안 설정과 데이터베이스 설정을 통해 프로덕션 환경에서도 안전하게 사용할 수 있습니다. 지속적인 업데이트와 유지보수를 통해 n8n의 최신 기능과 보안 패치를 적용하세요.

---

Keywords

n8n, Ubuntu, Node.js, Workflow Automation, Systemd, 워크플로우 자동화, 시스템 설정, 환경 변수, 보안 설정, 데이터베이스