Dokploy と Nixpacks を使って Astro プロジェクトをデプロイし、キャッシュ最適化でビルド速度を向上させる

1. Dokploy の設定

Dokploy はオープンソースでセルフホスト可能なデプロイメントプラットフォームです。Docker と Traefik 上に構築されており、Heroku、Vercel、Netlify の無料代替として設計されています。

1. 新規プロジェクトを作成し、GitHub リポジトリを接続

2. 環境変数を設定

NIXPACKS_NODE_VERSION=22
NIXPACKS_PNPM_STORE_PATH=/root/.local/share/pnpm/store/v3
NIXPACKS_INSTALL_CACHE_DIRS=/app/node_modules
NIXPACKS_BUILD_CACHE_DIRS=/app/node_modules/.cache,/app/astro_cache

3. キャッシュのクリーンアップを無効化

• プロジェクトサービス → Clean Cache：オフ
• Web サーバー → Daily Docker Cleanup：オフ

---

2. Nixpacks ビルドエンジン

Nixpacks は Railway によって開発されたオープンソースのビルドツールで、ソースコードを標準的な Docker イメージに変換します。Dokploy はデフォルトで Nixpacks を使用しており、nixpacks.toml または nixpacks.json ファイルで設定が可能です。

プロジェクトのルートディレクトリに nixpacks.toml を作成し、キャッシュディレクトリを定義します。

設定の優先順位（低 → 高）

1. プロバイダーのデフォルトロジック
2. nixpacks.toml
3. 環境変数
4. CLI 引数

よく使われる環境変数

変数名	説明
NIXPACKS_INSTALL_CMD	カスタムインストールコマンド
NIXPACKS_BUILD_CMD	カスタムビルドコマンド
NIXPACKS_START_CMD	カスタム起動コマンド
NIXPACKS_PKGS	追加の Nix パッケージ
NIXPACKS_APT_PKGS	追加の Apt パッケージ
NIXPACKS_INSTALL_CACHE_DIRS	インストール時のキャッシュディレクトリ
NIXPACKS_BUILD_CACHE_DIRS	ビルド時のキャッシュディレクトリ
NIXPACKS_NO_CACHE	キャッシュを無効化（非推奨）
NIXPACKS_CONFIG_FILE	設定ファイルの指定
NIXPACKS_DEBIAN	Debian ベースのイメージを使用

---

3. Astro プロジェクトの設定

Astro はコンテンツ重視の静的サイト向けに設計されたモダンな Web フレームワークです。画像や静的リソースが多い場合、ビルド速度が低下することがありますが、キャッシュを活用することで大幅に改善できます。

1. Astro にキャッシュディレクトリを設定

Astro の設定ファイルでキャッシュディレクトリを指定します。絶対パスまたは相対パスが使用可能です。

// astro.config.mjs
export default defineConfig({
  cacheDir: './astro_cache',
});

---

2. Nixpacks 用キャッシュ設定ファイル

Astro プロジェクトのルートに nixpacks.toml を作成し、キャッシュディレクトリとビルドコマンドを定義します。

# Node.js と pnpm のバージョン指定
[phases.setup]
nixPkgs = ["nodejs_22", "pnpm"]

# pnpm キャッシュを有効にした依存関係インストール
[phases.install]
cmds = ["pnpm install --frozen-lockfile"]
cacheDirectories = ["/root/.local/share/pnpm/store/v3"]

# Astro プロジェクトのビルドとキャッシュ設定
[phases.build]
cmds = ["pnpm run build"]
cacheDirectories = [
  "node_modules/.cache",
  "astro_cache"
]

# 起動コマンド（NGINX で dist を提供する前提）
[start]
cmd = "echo 'ビルド完了。dist ディレクトリを NGINX で提供してください。'"

---

4. Docker ビルドコンテキストの最適化

Astro プロジェクトのルートに .dockerignore を追加：

node_modules
astro_cache
dist
*.log
.DS_Store
.vscode
.env*

---

5. デプロイと検証

Dokploy による自動デプロイ後、以下のログを確認してキャッシュが有効になっているか確認します。

1. キャッシュマウント付きのビルドコマンド

RUN --mount=type=cache,id=xxxx-node_modules/cache,target=/app/node_modules/.cache \
    --mount=type=cache,id=xxxx-astro_cache,target=/app/astro_cache \
    pnpm run build

2. Astro によるキャッシュ再利用（特に画像最適化）

▶ /_astro/202409272055577_Z2smeTW.avif (reused cache entry)
▶ /_astro/202409272055575_Z2wPyJN.avif (reused cache entry)
▶ /_astro/202409272055577_1IgP6g.avif (reused cache entry)

✅ --mount=type=cache や reused cache entry が表示されていれば、キャッシュは有効に機能しており、ビルド時間が短縮されています。

🎉 Dokploy の Deployments タブで、キャッシュ無効時には 31 分かかったビルドが、キャッシュ有効時にはわずか 3 分で完了することを確認できます。時間と帯域の大幅な節約です。

---

6. 注意事項

• Astro の cacheDir と Nixpacks の cacheDirectories を一致させる
• 各ビルドフェーズでキャッシュディレクトリを明示的に定義すること
• nixpacks.toml は "..." で環境変数とのマージをサポート
• デフォルトでは node_modules/.astro はキャッシュ対象外なので、明示的に astro_cache に追加が必要