Node.js에 배포하기

EmDash는 모든 Node.js 22+ 호스팅 플랫폼에서 실행됩니다. 이 가이드는 로컬 또는 S3 호환 스토리지와 함께 SQLite를 사용합니다. libSQL과 PostgreSQL도 Node.js에서 동일한 방식으로 작동합니다 — 데이터베이스 옵션을 참조하세요.

전제 조건

• Node.js v22.12.0 이상
• Node.js 호스팅 제공업체 또는 VPS

구성

Node.js 배포를 위해 EmDash를 구성합니다:

import { defineConfig } from "astro/config";
import node from "@astrojs/node";
import emdash, { local, s3 } from "emdash/astro";
import { sqlite } from "emdash/db";

export default defineConfig({
	output: "server",
	adapter: node({ mode: "standalone" }),
	integrations: [
		emdash({
			database: sqlite({ url: "file:./data/emdash.db" }),
			storage: local({
				directory: "./data/uploads",
				baseUrl: "/_emdash/api/media/file",
			}),
		}),
	],
});

빌드 및 실행

1. 프로젝트를 빌드합니다:

   npm run build

2. 서버를 시작합니다:

   node ./dist/server/entry.mjs

서버는 기본적으로 http://localhost:4321에서 실행됩니다. 마이그레이션은 첫 번째 요청 시 적용됩니다. 데이터베이스가 비어 있고 설정이 완료되지 않은 경우, 시드 파일(또는 없는 경우 내장 기본값)도 첫 번째 요청 시 적용됩니다.

프로덕션 스토리지

프로덕션의 경우 로컬 파일시스템 대신 S3 호환 스토리지를 사용하세요:

import emdash, { s3 } from "emdash/astro";

export default defineConfig({
	integrations: [
		emdash({
			database: sqlite({ url: `file:${process.env.DATABASE_PATH}` }),
			storage: s3({
				endpoint: process.env.S3_ENDPOINT,
				bucket: process.env.S3_BUCKET,
				accessKeyId: process.env.S3_ACCESS_KEY_ID,
				secretAccessKey: process.env.S3_SECRET_ACCESS_KEY,
				publicUrl: process.env.S3_PUBLIC_URL, // Optional CDN URL
			}),
		}),
	],
});

Docker

빌드 컨텍스트를 작게 유지하기 위해 .dockerignore를 추가합니다:

node_modules
dist
.git

Dockerfile을 생성합니다:

FROM node:22-alpine AS builder
WORKDIR /app
COPY package*.json ./
RUN npm ci
COPY . .
RUN npm run build

FROM node:22-alpine
WORKDIR /app
COPY --from=builder /app/dist ./dist
COPY --from=builder /app/node_modules ./node_modules
COPY --from=builder /app/package.json ./

RUN mkdir -p data

ENV HOST=0.0.0.0
ENV PORT=4321

EXPOSE 4321
CMD ["node", "./dist/server/entry.mjs"]

시드 파일은 빌드 시점에 읽혀 번들에 인라인되므로 런타임 이미지에 복사할 필요가 없습니다. 마이그레이션은 배포 후 첫 번째 요청 시 실행됩니다. 시드는 데이터베이스에 컬렉션이 없고 설정이 완료되지 않은 경우에만 적용됩니다 — 기존 데이터는 절대 덮어쓰지 않습니다.

이미지를 빌드하고 컨테이너를 실행합니다:

docker build -t my-emdash-site .
docker run -p 4321:4321 -v emdash-data:/app/data my-emdash-site

Docker Compose 파일은 명명된 볼륨으로 동일한 컨테이너를 관리합니다:

services:
  emdash:
    build: .
    ports:
      - "4321:4321"
    volumes:
      - emdash-data:/app/data
    restart: unless-stopped

volumes:
  emdash-data:

백그라운드에서 스택을 시작합니다:

docker compose up -d

환경 변수

권장 사항: 암호화 키

EMDASH_ENCRYPTION_KEY는 플러그인 시크릿을 저장 시 암호화하기 위한 키입니다. 키는 시작 시 검증됩니다. 플러그인 시크릿 암호화는 활성화되면 이를 사용합니다. 나중에 구성을 변경하지 않고도 시크릿이 보호되도록 모든 배포에서 설정하세요.

키를 생성하고 결과를 환경에 추가하세요:

npx emdash secrets generate  # add the result to your environment

키는 사용자가 제공하며 데이터베이스에는 절대 저장되지 않습니다. 암호화된 암호문만 저장됩니다. 영구적인 장소(비밀번호 관리자, KMS 또는 팀의 시크릿 저장소)에 백업하세요 — 분실하면 그것으로 암호화된 모든 시크릿을 잃게 됩니다.

선택 사항: 안정적인 값 재정의

EmDash는 미리보기 HMAC 시크릿과 댓글 작성자 IP 해시 솔트를 자동으로 생성하고 첫 사용 시 데이터베이스에 유지합니다. 아래 환경 변수는 이를 제어하는 값으로 고정합니다 — 별도의 프로세스가 메인 사이트와 시크릿을 공유해야 할 때 유용합니다.

데이터베이스 및 스토리지

영구 스토리지

SQLite는 영구 디스크 스토리지가 필요합니다. 호스팅 플랫폼이 다음을 제공하는지 확인하세요:

• 마운트된 볼륨 또는 영구 디스크
• 데이터베이스 디렉토리에 대한 쓰기 액세스
• 데이터베이스 파일에 대한 백업 메커니즘

상태 확인

로드 밸런서를 위한 상태 확인 엔드포인트를 추가하세요:

export const GET = () => {
  return new Response("OK", { status: 200 });
};

플랫폼을 구성하여 활성 프로브를 위해 /health를 확인하도록 하세요.