VPS 로컬 서버

업데이트 기록:

머리말

NotionNext는 Vercel 무료 호스팅으로 쉽게 사용할 수 있습니다. 하지만 무료 트래픽과 함수 실행 횟수에는 제한이 있습니다. 사이트 방문량이 매우 크다면 자신의 클라우드 서버나 VPS에 배포하는 방식을 시도할 수 있습니다.

대상 사용자와 가까운 지역의 VPS에 배포하면 사이트 접속 속도를 크게 높일 수 있습니다.

Node.js 환경을 직접 설치해 bare metal 방식으로 실행할 수도 있습니다. 다만 서버 운영체제, CPU, 메모리 구성은 서비스 실행에 영향을 줄 수 있습니다. Docker 컨테이너 배포를 권장합니다.

기술 경험이 있는 사용자에게 더 적합한 방식입니다.

참고할 만한 커뮤니티 실습 글:

VPS bare metal 환경에 NotionNext 개인 블로그 설치하기 | Ywba's Blog

개인 블로그

설치 단계

임의의 운영체제를 사용하는 VPS 클라우드 서버를 준비하세요. 시스템별 설치 단계는 대체로 비슷합니다. 아래에서는 linux-centos-7 호스트를 예로 듭니다.

설치는 세 단계로 나뉩니다. 첫째 NotionNext 코드 다운로드, 둘째 실행 환경 설치, 셋째 프로젝트 실행입니다.

1. NotionNext 코드 다운로드

Git 설치

Git은 코드 호스팅 도구입니다. GitHub의 코드를 다운로드할 때 사용할 수 있습니다.

Bash

# Install with one command
yum install git -y

실행 결과 예시

설치 중에는 의존성 확인, 패키지 다운로드, 설치 검증 로그가 출력됩니다. 마지막에 Complete!가 표시되면 Git 설치가 완료된 것입니다.

GitHub 저장소에서 코드 가져오기

Bash

# Move to your user home directory
cd ~

# Download the code from Git to the server
git clone https://github.com/tangly1024/NotionNext

# If the server cannot access GitHub due to network issues,
# manually download the NotionNext code and upload it to the server.

2. 프로젝트 실행

Docker로 실행하거나 시스템에 Node.js 환경을 설치해 실행할 수 있습니다. 호환성과 안정성을 고려하면 Docker 방식을 권장합니다.

1. Docker 실행

기존 문서에서는 서버에 Node.js 환경을 설치하는 방식을 권장했습니다. 하지만 NotionNext V4.0 이후 새 버전은 Node 20 이상 환경이 필요하고, 일부 서버에서는 설치 호환성 문제가 발생할 수 있습니다. Docker는 프로덕션 환경에서 더 안정적으로 사용하기 좋으므로 2025년 7월 8일 문서에 Docker 실행 방식을 추가했습니다.

Docker 최신 버전 설치(CentOS 예시)

Bash

# 1. Update the system
sudo yum update -y
# 2. Install dependencies
sudo yum install -y yum-utils device-mapper-persistent-data lvm2
# 3. Add the Docker CE repository
sudo yum-config-manager --add-repo http://mirrors.aliyun.com/docker-ce/linux/centos/docker-ce.repo
# 4. Install Docker
sudo yum install -y docker-ce
# 5. Start Docker
sudo systemctl start docker

다른 운영체제 - Debian

JavaScript

sudo apt-get update
sudo apt-get install apt-transport-https ca-certificates curl gnupg lsb-release
echo "deb [arch=$(dpkg --print-architecture) signed-by=/usr/share/keyrings/docker-archive-keyring.gpg] https://mirrors.aliyun.com/docker-ce/linux/debian $(lsb_release -cs) stable" | sudo tee /etc/apt/sources.list.d/docker.list &gt; /dev/null
sudo apt update
sudo apt install docker-ce docker-ce-cli containerd.io docker-compose-plugin

Dockerfile 만들기

일부 네트워크 환경에서는 Docker가 공식 Node.js 이미지를 다운로드하기 어려울 수 있습니다. 아래 예시는 대체 이미지 소스를 사용한 Dockerfile입니다. 실제 사용 시에는 이미지 소스가 만료되었는지 확인하세요.

Bash

# 1. Make sure the current directory is the NotionNext code folder.
cd NotionNext

# 2. Create the build file.
cat &gt; Dockerfile &lt;&lt;EOF
# Stage 1: base image
FROM swr.cn-north-4.myhuaweicloud.com/ddn-k8s/docker.io/library/node:20-alpine AS base

# Stage 2: install dependencies
FROM base AS deps
ARG NOTION_PAGE_ID
ARG NEXT_PUBLIC_THEME
RUN apk add --no-cache libc6-compat
WORKDIR /app
COPY package.json ./
RUN yarn config set registry https://registry.npmmirror.com && \
    yarn config set disturl https://npmmirror.com/dist && \
    yarn install --frozen-lockfile --network-timeout 600000

# Stage 3: build
FROM base AS builder
ARG NOTION_PAGE_ID
ARG NEXT_PUBLIC_THEME
ENV NEXT_BUILD_STANDALONE=true
ENV NEXT_DEBUG=${NEXT_DEBUG:-false}
WORKDIR /app
COPY --from=deps /app/node_modules ./node_modules
COPY . .
RUN yarn build

# Stage 4: run
FROM base AS runner
ENV NODE_ENV=production
WORKDIR /app
COPY --from=builder /app/public ./public
# Automatically leverage output traces to reduce image size.
# https://nextjs.org/docs/advanced-features/output-file-tracing
COPY --from=builder /app/.next/standalone ./
COPY --from=builder /app/.next/static ./.next/static

# If you keep a configured .env.local file in the project root,
# you can copy it into the runtime image.
# COPY --from=builder /app/.env.local ./

EXPOSE 3000

# Next.js collects anonymous telemetry data about general usage.
# Learn more here: https://nextjs.org/telemetry
# Uncomment the following line if you want to disable telemetry.
# ENV NEXT_TELEMETRY_DISABLED 1

CMD ["node", "server.js"]
EOF

빌드 시작

다음 명령은 현재 NotionNext 폴더의 Dockerfile을 읽어 Node.js 환경을 다운로드하고, blog.config.js 등 설정을 포함한 NotionNext 코드를 실행 가능한 Docker 이미지로 패키징합니다. 이미지 이름은 my-app입니다.

Bash

docker build --build-arg NEXT_DEBUG=true -t my-app .

서버 네트워크 환경에 따라 첫 패키징 과정은 10분 정도 걸릴 수 있습니다.

Docker로 프로젝트 실행

Bash

docker run -d -p 3000:3000 --name app --restart unless-stopped my-app

Docker 프로젝트 재시작

Bash

docker restart app

Docker 사용법은 Docker 문서나 AI 도구를 참고해 더 확인할 수 있습니다.

프로젝트 업데이트

최신 코드를 가져오거나 설정 파일을 수정한 뒤 아래 명령으로 다시 패키징합니다.

Bash

docker build --build-arg NEXT_DEBUG=true -t my-app .

이후 기존 서비스를 중지하고 삭제합니다.

Bash

docker rm -f app

새 서비스를 시작합니다.

Bash

docker run -d -p 3000:3000 --name app --restart unless-stopped my-app

2. 시스템에서 실행(Node.js 로컬 설치)

Docker 외에도 시스템에 Node.js 환경을 직접 설치해 실행할 수 있습니다. Node.js를 시스템에 설치하려면 nvm 사용을 권장합니다. NVM(Node version manager)은 Node.js 전용 버전 관리 도구이며, Node.js 버전을 빠르게 설치하고 전환할 수 있어 이후 환경 업그레이드가 편리합니다.

Node.js 환경 관련 경고
- 서버 버전이 최신 Node.js와 호환되지 않으면 실행 시 오류가 발생할 수 있습니다. 이 경우 시스템 모듈 업그레이드가 필요할 수 있는데 위험한 작업입니다. 가능하면 위에서 권장한 Docker 방식을 사용하세요.

Node.js 명령 실행 시 다음과 같은 오류가 나타날 수 있습니다.

NVM과 Node.js 설치 단계:

Git으로 nvm 소스 코드 다운로드

Bash

# Download nvm source code from GitHub.
git clone https://github.com/cnpm/nvm.git ~/.nvm && cd ~/.nvm && git checkout `git describe --abbrev=0 --tags`

서버가 네트워크 제한으로 GitHub에 접근할 수 없다면 Gitee의 nvm 소스 코드를 사용할 수 있습니다.

nvm으로 Node.js 설치

Bash

# 1. Add nvm to shell environment variables.
echo "source ~/.nvm/nvm.sh" &gt;&gt; ~/.bashrc

# 2. Reload shell environment.
source ~/.bashrc

# 3. Install Node.js. Node 20 is used here to match the official README.
nvm install 20

참고:

Yarn 환경 설치

Node.js에는 NPM(Node Package Manager)이 포함되어 있습니다. NPM으로 NotionNext처럼 Webpack 기반으로 패키징되는 프로젝트의 의존성을 설치하고 빌드할 수 있습니다. 다만 여기서는 NPM보다 사용성이 좋은 Yarn을 설치합니다.

Java

# 1. Optional: switch NPM registry for faster installation.
npm config set registry https://registry.npmmirror.com

# 2. Install yarn globally with npm.
npm install -g yarn

Node.js로 NotionNext 실행:

NotionNext 의존성 설치

JavaScript

# Install all project dependencies with yarn.
yarn

Yarn을 설치하지 않았다면 npm install 명령으로 의존성을 설치할 수도 있습니다.

프로젝트 컴파일

코드 수정, blog.config.js 파일 수정을 포함해 코드를 바꾼 뒤에는 매번 이 단계를 다시 실행해야 합니다.

Bash

# Build the project.
yarn build

# Set your notion_page_id as an environment variable, for example:
NOTION_PAGE_ID=29d5ia78b858e4a3bbc13e51b5400fb82

프로젝트 시작

JavaScript

# Start the service.
yarn start

실행 결과 예시

yarn, yarn build, yarn start를 실행하면 의존성 설치 로그, Next.js 빌드 로그, 정적 페이지 생성 로그, 서버 시작 로그가 차례로 표시됩니다. 마지막에 ready - started server on 0.0.0.0:3000과 비슷한 메시지가 표시되면 실행에 성공한 것입니다.

3. 프로젝트 접속

프로젝트는 기본적으로 3000 포트에서 시작됩니다. 서버 주소 http://ip:3000에 접속하면 사이트를 열 수 있습니다.

3000 포트에 접근할 수 없는 경우가 있습니다. 서버 방화벽이나 클라우드 서비스 제공자의 security group 제한 때문일 수 있습니다.

Alibaba Cloud 서버 security group 참고

Alibaba Cloud ECS의 security group에서 수동으로 규칙을 추가해 3000 포트를 노출합니다. 허용 대상 0.0.0.0/0은 모든 IP가 이 포트에 접근할 수 있음을 뜻합니다. Nginx 접근을 위해 80 포트도 함께 노출하는 것을 권장합니다.

Untitled

접속 효과: 서버 IP와 포트 번호로 웹페이지를 열었습니다.

Untitled

이 방식으로 실행하면 서버 콘솔에 사이트 로그가 실시간으로 출력되므로 디버깅과 문제 확인에 유용합니다.

4. Node.js 프로젝트 백그라운드 실행

시스템의 Node.js 방식으로 실행하는 경우에는 이 단계로 백그라운드 실행을 설정해야 합니다. Docker로 실행한다면 이 장은 무시해도 됩니다.

yarn start로 서비스를 직접 시작하는 방식은 로그 디버깅에 주로 사용합니다. SSH 터미널을 닫거나 서버에서 로그아웃하면 이 프로세스도 함께 종료됩니다.

방식 1: nohup 실행

nohup은 Linux 시스템 명령으로, 명령을 백그라운드에서 끊기지 않게 실행할 때 사용합니다. 사이트를 항상 백그라운드에서 유지하려면 다음 방식으로 실행합니다.

ctrl+c를 눌러 위에서 실행 중인 yarn 프로세스를 종료합니다.
nohup으로 실행합니다.

Bash

cd NotionNext

nohup yarn start &gt;/dev/null 2&gt;&1 &

로그 파일을 출력하고 싶다면 nohup yarn start > notionnext.log 2>&1 &를 실행하세요.

실행 결과

Bash

[root@tangly1024 ~]# nohup yarn start &gt;/dev/null 2&gt;&1 &
[1] 5240
# The background process id is printed.

프로세스 종료 방법

Bash

pkill -f "yarn start"

방식 2: PM2로 NotionNext 관리

PM2는 Node 프로세스 관리 도구입니다. 사이트 유지보수 효율을 높일 수 있습니다. 자세한 내용은 PM2로 NotionNext 실행하기를 참고하세요.

https://jjdctg.com/pm2

5. Node.js 사이트 중단 문제

이 장은 Node.js로 프로젝트를 실행할 때 발생할 수 있는 문제를 다룹니다. Docker로 실행한다면 무시해도 됩니다.

일부 사용자의 서버에서는 NotionNext 사이트를 실행한 뒤 일정 시간이 지나면 사이트 프로세스가 이유 없이 종료되어 사이트가 중단되는 문제가 있었습니다. 아직 정확한 원인은 찾지 못했으며, 서버 사양 부족 때문일 수도 있습니다.

이런 상황이 발생한다면 시작 스크립트를 만들고, 사이트가 종료되었을 때 자동으로 다시 시작하도록 실시간으로 감시할 수 있습니다.

서버의 NotionNext 폴더 아래에 start_yarn.sh 스크립트를 만듭니다. 내용은 다음과 같습니다.

Bash

#!/bin/bash

while true; do
    # Check whether the Yarn process exists.
    if pgrep -x "yarn" &gt; /dev/null; then
        echo "Yarn process is already running."
    else
        # Run the command.
        nohup yarn start &gt;/dev/null 2&gt;&1 &

        # Get the latest started process id.
        pid=$!

        echo "Yarn process started with PID: $pid"
    fi

    # Wait before running again.
    sleep 5
done

이 스크립트를 파일에 붙여 넣고 저장하는 방법

Bash

# Enter the project folder.
cd NotionNext
# Create and open this file with an editor.
vim start_yarn.sh

# Press i to enter INSERT mode.
# Paste the script above with Shift + Insert.
# Press Esc to leave edit mode.
# Type :wq and press Enter to save the script.

스크립트에 실행 권한을 부여합니다.

Bash

chmod +x start_yarn.sh

시작 스크립트를 실행합니다.

Bash

nohup ./start_yarn.sh &gt; /dev/null 2&gt;&1 &

스크립트를 종료합니다.

Bash

pkill -f "yarn"

6. 로컬 코드 설정 수정

Docker 방식을 사용한다면 NOTION_CONFIG 또는 설정 파일 config.js를 직접 수정하는 것을 권장합니다. Docker는 환경 변수 호환성이 충분하지 않을 수 있습니다.

1. 환경 변수로 설정 수정

환경 변수의 장점은 코드를 수정하지 않아도 되고 다시 패키징하거나 컴파일할 필요도 없다는 것입니다. 서비스를 다시 시작하기만 하면 됩니다.

NOTION_PAGE_ID를 포함한 많은 설정은 환경 변수로 설정할 수 있습니다.

Bash

# 1. Set environment variable.
NOTION_PAGE_ID=29d5ia78b858e4a3bbc13e51b5400fb82
# 2. Stop the old process.
# See the command above.
# 3. Run in the background.
nohup yarn start &gt;/dev/null 2&gt;&1 &

환경 변수 삭제는 다음 명령을 사용합니다. unset NOTION_PAGE_ID

환경 변수를 지원하는 설정은 blog.config.js 파일을 참고하세요.

2. 코드 수정

blog.config.js 또는 다른 코드 파일을 수정했다면 Node.js 환경에서는 yarn build를 다시 실행해야 적용됩니다. Docker 환경에서는 앞의 docker build 관련 명령을 다시 실행해 이미지를 재구성하면 됩니다.
프로젝트 루트 디렉터리의 .env.local 파일에서 환경 변수를 설정할 수 있습니다.
다시 컴파일한 뒤에는 기존 프로세스를 먼저 종료하고 yarn start로 서비스를 다시 시작해야 합니다.

3. 사용자 정의 포트

시스템 Node.js 환경으로 배포할 때 3000 포트가 이미 사용 중이거나 NotionNext를 여러 개 실행하고 싶다면 아래 명령으로 포트를 지정할 수 있습니다.

Bash

yarn start -p 8080
# -p [custom port]

Docker 환경에서는 Docker의 포트 매핑 기능을 사용하면 됩니다.

Bash

docker run -d -p 8080:3000 --name app my-app

포트 숨기기: Nginx reverse proxy

3000 포트 번호를 숨기려면 Nginx를 사용하면 됩니다. 서버 관리 패널 같은 운영 도구가 있다면 더 쉽게 설정할 수 있습니다.
Nginx 설치 예시:

Bash

# Add nginx repository.
sudo rpm -ivh http://nginx.org/packages/centos/7/noarch/RPMS/nginx-release-centos-7-0.el7.ngx.noarch.rpm

# Install nginx.
sudo yum install nginx
sudo systemctl enable nginx
sudo systemctl start nginx

설치 성공 후 서버 주소 접속 효과

Untitled

reverse proxy 설정 참고

관련 설정 파일 /etc/nginx/conf.d/default.conf를 수정합니다.

Bash

# Edit with vi.
vi /etc/nginx/conf.d/default.conf

# Add one line under location /.
proxy_pass  http://127.0.0.1:3000;

# Reload nginx configuration.
sudo systemctl reload nginx

Untitled

접속 오류가 발생한다면 SELinux 설정이 Nginx forwarding을 허용하지 않는 것일 수 있습니다. setsebool -P httpd_can_network_connect on을 실행하면 해결할 수 있습니다.

VPS에 배포한 NotionNext를 자동 업데이트하는 방법

코드는 자신의 서버에서 가져오고 배포하므로 매번 코드 업데이트, 컴파일, 서비스 재시작 단계를 실행해야 합니다. 서버에 update.sh 스크립트를 만드는 것을 권장합니다.

참고용 예시 코드:

Bash

#!/bin/bash

# Move to working directory.
cd NotionNext

# Pull the latest code from the repository.
git pull https://github.com/tangly1024/NotionNext

# Build the new code.
yarn build

# Start service.
yarn start

가장 단순한 자동 스크립트 예시입니다. 필요하다면 대화형 고급 스크립트로 만들 수도 있습니다.

원문 링크

https://docs.tangly1024.com/article/deploy-notion-next-on-vps

VPS 로컬 서버 ​

머리말 ​

설치 단계 ​

1. NotionNext 코드 다운로드 ​

2. 프로젝트 실행 ​

1. Docker 실행 ​

2. 시스템에서 실행(Node.js 로컬 설치) ​

3. 프로젝트 접속 ​

4. Node.js 프로젝트 백그라운드 실행 ​

방식 1: nohup 실행 ​

프로세스 종료 방법 ​

방식 2: PM2로 NotionNext 관리 ​

5. Node.js 사이트 중단 문제 ​

6. 로컬 코드 설정 수정 ​

1. 환경 변수로 설정 수정 ​

2. 코드 수정 ​

3. 사용자 정의 포트 ​

포트 숨기기: Nginx reverse proxy ​

VPS에 배포한 NotionNext를 자동 업데이트하는 방법 ​

원문 링크 ​

VPS 로컬 서버

머리말

설치 단계

1. NotionNext 코드 다운로드

2. 프로젝트 실행

1. Docker 실행

2. 시스템에서 실행(Node.js 로컬 설치)

3. 프로젝트 접속

4. Node.js 프로젝트 백그라운드 실행

방식 1: nohup 실행

프로세스 종료 방법

방식 2: PM2로 NotionNext 관리

5. Node.js 사이트 중단 문제

6. 로컬 코드 설정 수정

1. 환경 변수로 설정 수정

2. 코드 수정

3. 사용자 정의 포트

포트 숨기기: Nginx reverse proxy

VPS에 배포한 NotionNext를 자동 업데이트하는 방법

원문 링크