E EmDash CMS Everything Guides, use cases, plugins, templates
日本語

Node.js へデプロイ

このページ

EmDash は Node.js 22.16 以降で動作します。このガイドは 1 台のサーバー向けに SQLite とローカルストレージを使います。複数インスタンスが 1 つのデータベースを必要とする場合は PostgreSQL または libSQL を使い、メディアがサーバーディスクとは独立して残る必要がある場合は S3 互換ストレージを使います。

前提条件

  • Node.js v22.16.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

    サーバーを起動する前に、ホスティングプロバイダーのプロセス環境経由で EMDASH_ENCRYPTION_KEY とその他のランタイム資格情報を設定します。スタンドアロン Node エントリは .env を自動では読み込みません。生成された .env ファイルを使うローカル実行では、 node --env-file=.env ./dist/server/entry.mjs で起動します。

サーバーはデフォルトで http://localhost:4321 で動作します。デフォルトの auto マイグレーションモードでは、最初のリクエストが保留中のコアミグレーションを適用します。新しいデータベースは埋め込みシードも受け取ります。Manage core database migrations は、本番トラフィックを再開する前にマイグレートする方法を説明します。

スケジュールタスク

組み込みスケジューラは Node.js プロセスが動作している間だけ動きます。スケジュール公開、プラグインタスク、一般的なメンテナンスを扱います。

本番では少なくとも 1 つの Node.js プロセスを継続的に動かしてください。すべてのプロセスが停止またはスリープすると、スケジュールタスクは一時停止します。

プラグインサンドボックス

マーケットプレイスプラグインと sandboxed: [] 以下に列挙されたプラグインにはサンドボックスランナーが必要です。Node.js ではランナーは @emdash-cms/sandbox-workerd で、プラグインを workerd 子プロセスで実行します。Plugin Sandbox はインストール、workerd プロセスの動作、および失敗モードを扱います。

本番データサービスを選ぶ

データベースが永続ボリュームに残り、メディアが S3 互換ストレージへ移る場合は、次のパターンを使います。

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

export default defineConfig({
	integrations: [
			emdash({
				database: sqlite({ url: `file:${process.env.DATABASE_PATH}` }),
				storage: s3(),
		}),
	],
});

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

値はオペレーターが提供し、データベースには保存されません。シークレットマネージャーと別の復旧バックアップに保管してください。ローテーション中は、まず新しいキーを提供し、すべてのプラグインシークレットが再保存されるまでカンマ区切りで古いキーを保持します。EmDash は現在どのキー ID が使用中かを報告しないため、再保存した各資格情報を追跡し、古いキーを削除する前に統合を確認してください。参照されるキーなしでデータベースを復元すると、対応する設定が読めなくなります。

任意: 安定値のオーバーライド

EmDash はプレビュー HMAC シークレットとコメンター IP ハッシュ ソルトを自動生成し、初回使用時にデータベースへ永続化します。下記の環境変数は それらをあなたが制御する値に固定します — 別プロセスがメインサイトと シークレットを共有する必要がある場合に便利です。

変数説明
EMDASH_PREVIEW_SECRET自動生成プレビュー HMAC シークレットのオーバーライド。
EMDASH_IP_SALT自動生成コメンター IP ハッシュソルトのオーバーライド。
EMDASH_AUTH_SECRET任意。設定されている場合、IP ソルトのソースとして使われます（EMDASH_IP_SALT も設定されている場合はそちらが優先）。既にそれに依存するインストールでコメンター IP ハッシュを安定に保ちます。新規デプロイでは未設定のままにします。

キー形式、サポートされるすべてのシークレット、ローテーションや損失の影響については Secrets and key management を参照してください。

データベースとストレージ

変数説明例
DATABASE_PATHSQLite データベースへのパス/data/emdash.db
HOSTサーバーホスト0.0.0.0
PORTサーバーポート4321
S3_ENDPOINTS3 エンドポイント URLhttps://xxx.r2.cloudflarestorage.com
S3_BUCKETS3 バケット名my-media-bucket
S3_ACCESS_KEY_IDS3 アクセスキーAKIA...
S3_SECRET_ACCESS_KEYS3 シークレットキー...
S3_REGIONS3 リージョンauto
S3_PUBLIC_URLメディアの公開 URLhttps://cdn.example.com

永続ストレージ

SQLite には永続ディスクストレージが必要です。ホスティングプラットフォームが次を提供することを確認してください。

  • マウントされたボリュームまたは永続ディスク
  • データベースディレクトリへの書き込みアクセス
  • データベースファイルのバックアップ機構

SQLite ファイルとアップロードディレクトリの両方をバックアップします。復旧中にいずれかを置き換える前にプロセスを停止してください。Backups を参照してください。

ヘルスチェック

ロードバランサー向けにヘルスチェックエンドポイントを追加します。

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

このエンドポイントは、Node.js プロセスが Astro ルートを提供できることを示します。データベース、ストレージバックエンド、マイグレーション状態、プラグインサンドボックスが健全であることは示しません。新しいリリースにトラフィックを送る前に、それらの依存関係を別途確認してください。

トラフィック送信前に確認する

新しいビルドを起動した後、本番リクエストが使うのと同じランタイムサービスを確認します。

  1. /health と公開コンテンツページをリクエストします。両方とも成功レスポンスを返す必要があります。
  2. ビルド済みプロジェクトから npx emdash migrate --check を実行します。構成済みデータベースに保留または未知のマイグレーションがないと報告する必要があります。
  3. /_emdash/admin にサインインし、使い捨て下書きを作成または編集して公開します。公開ページに変更が表示されることを確認します。
  4. 使い捨てメディアファイルをアップロードし、返された URL を開きます。確認後にファイルを削除します。
  5. サイトがサンドボックスプラグインを使う場合、1 つのプラグインルートまたはフックを呼び出し、サーバーログに sandbox-unavailable または workerd 起動エラーがないことを確認します。

該当するすべてのチェックが通るまで、新しいインスタンスをロードバランサーから外しておきます。