Raspberry Pi에서 Node.js 웹사이트 자체 호스팅

많은 개발자에게 자체 호스팅의 매력은 비용뿐만 아니라 제어권에 있습니다. Vercel이나 Netlify와 같은 플랫폼이 원활한 배포를 제공하지만, 레거시 동적 라이브러리 필요성이나 전체 환경 소유에 대한 선호와 같은 특정 기술 요구 사항이 있을 때는 홈 서버가 더 나은 선택이 될 수 있습니다.

Raspberry Pi를 웹 서버로 사용하는 것은 네트워킹, 서버 관리 및 배포 파이프라인의 복잡성을 배우는 훌륭한 방법입니다. 이 가이드는 Raspberry Pi에서 Node.js 기반 웹사이트(예: Astro 또는 Svelte로 구축된 사이트)를 호스팅하기 위한 간소화된 절차를 설명합니다.

아키텍처: 라우터에서 브라우저까지

홈 네트워크에서 웹사이트를 전 세계에 접근 가능하게 하려면 로컬 사설 IP와 공용 IP 주소 사이의 간극을 연결해야 합니다.

1. 포트 포워딩 및 리버스 프록시

첫 번째 단계는 라우터를 설정하여 들어오는 트래픽을 Raspberry Pi의 특정 내부 IP 주소로 포워딩하는 것입니다. 라우터 인터페이스는 다양하기 때문에 해당 하드웨어의 문서를 확인해야 합니다.

트래픽이 Pi에 도달하면 요청을 처리하고 SSL 인증서를 관리할 방법이 필요합니다. Caddy는 HTTPS를 자동으로 처리해 주기 때문에 강력히 권장되는 도구입니다. Astro 사이트에 대한 일반적인 Caddyfile 구성은 다음과 같습니다:

m4rt.nl {
    root * /home/mart/Documents/m4rt.nl
    file_server
    reverse_proxy localhost:4321
}

이 설정에서는 Caddy가 정적 파일을 직접 제공하고 포트 4321에서 실행 중인 Node.js 프로세스로 요청을 프록시합니다.

2. DNS 구성

서버 설정이 완료되면 도메인을 홈 네트워크에 연결해야 합니다. 이는 DNS 제공업체 설정에 A Record를 추가하여 도메인(예: yoursite.com)을 ISP가 제공하는 공용 IP 주소에 매핑함으로써 수행됩니다.

애플리케이션 라이프사이클 관리

변경할 때마다 빌드 스크립트를 수동으로 실행하는 것은 비효율적입니다. 프로덕션 준비 환경을 만들려면 프로세스 관리자와 배포 파이프라인이 필요합니다.

프로세스 관리를 위한 PM2 사용

Node.js 앱을 배포할 때 터미널 세션에서 시작 명령을 실행하기만 하면 안 됩니다. 세션이 종료되면 프로세스가 종료되기 때문입니다. PM2는 애플리케이션을 백그라운드에서 유지하고 충돌 시 재시작하는 프로덕션용 프로세스 관리자입니다.

npm run build를 실행한 후, 진입점을 다음과 같이 실행할 수 있습니다: pm2 run entry.mjs

GitHub Actions를 통한 배포 자동화

현대 클라우드 플랫폼의 “push-to-deploy” 경험을 흉내 내기 위해 GitHub Actions를 사용해 CI/CD 파이프라인을 구현할 수 있습니다. 워크플로 파일(예: .github/workflows/update_server.yml)을 생성하면 코드를 리포지토리에 푸시할 때마다 SSH를 통해 원격 업데이트를 트리거할 수 있습니다.

appleboy/ssh-action을 사용하면 워크플로가 호스트 IP와 비밀번호에 대한 시크릿을 이용해 Pi에 안전하게 연결한 뒤, 업데이트를 처리하는 로컬 셸 스크립트를 실행할 수 있습니다.

업데이트 스크립트

견고한 업데이트 스크립트는 여러 프로젝트를 처리하고 최신 코드를 가져와 빌드하도록 해야 합니다. 이러한 스크립트의 예시 로직은 다음을 포함합니다:

  1. 기본 폴더 내 디렉터리를 순회합니다.
  2. .git 폴더가 존재하는지 확인하고 git pull을 수행합니다.
  3. package.json을 통해 Node.js 프로젝트를 식별하고 특정 포트와 함께 빌드 명령을 실행합니다.
  4. 모든 PM2 프로세스를 재시작하여 변경 사항을 적용합니다.

보안 고려 사항 및 대안

포트 포워딩은 사이트를 빠르게 온라인에 올리는 가장 쉬운 방법이지만, 홈 네트워크의 포트를 공용 인터넷에 노출시켜 보안 위험을 초래할 수 있습니다.

이 설정에 대한 논의에서 커뮤니티 구성원들이 지적했듯이, 홈 방화벽에 구멍을 내는 것은 위험할 수 있습니다. 보다 안전한 대안은 Cloudflare Tunnel을 사용하는 것입니다. 터널은 서버와 Cloudflare 네트워크 사이에 안전한 아웃바운드 전용 연결을 생성하여 라우터에서 포트를 열 필요를 없애고 홈의 공용 IP 주소를 외부에 숨깁니다.

Raspberry Pi와 Caddy, PM2, GitHub Actions와 같은 도구를 결합하면 개발자는 거실에서 바로 완전 자동화된 전문가 수준의 호스팅 환경을 구축할 수 있습니다.

Sources