n8n-self-hosting

セルフホスト n8n のデプロイ

このスキルでは、新規の Linux VM（Ubuntu/Debian、root または sudo で SSH 接続）から、稼働中の HTTPS 対応本番環境の n8n を、Caddy（Let's Encrypt による自動 TLS）の背後で Docker Compose を使って構築します。 対象は Docker 上のセルフホスト n8n です。n8n Cloud は対象外であり、ワークフローの作成も対象外です（その内容はこのパックの別の箇所で扱います）。

デプロイ方法は 2 種類です。アーキテクチャが異なるため、作業を始める前にモードを選択してください。

SSH 経由で、事前確認 → Docker のインストール → プロジェクトの配置 → シークレットの生成 → 起動 → TLS の確認 → 引き継ぎまで、一連の作業を行います。テンプレートファイルは assets/ にあり、モードごとの詳細とセキュリティの詳細は、以下に記載するリファレンスファイルにあります。

ルール 0 — モードを選ぶ（ユーザーに確認する）

推測してはいけません。確認してから、いずれか 1 つに決めてください。

	シングル／通常	キュー
プロセス	n8n が 1 つ	メイン + N 個のワーカー
追加サービス	なし（SQLite）	Redis（キュー）+ Postgres（DB）
ワークフローの実行場所	メインプロセス内	ワーカー上で並列実行
適した用途	1 ユーザー、軽度から中程度の負荷、最もシンプルな運用	大量の処理、負荷の高い／長時間の実行、水平スケーリング
Compose	assets/docker-compose.single.yml	assets/docker-compose.queue.yml
詳細	SINGLE_MODE.md	QUEUE_MODE.md

迷った場合は、まず シングル から始めてください。最もシンプルで適切な選択肢であり、ほとんどのニーズを満たします。後からキューに移行するには、Compose ファイルを切り替え、SQLite から Postgres に移行する必要があります。そのため、ユーザーがすでに本格的な処理量を想定している場合は、最初から キュー を選んでください。

ルール 1 — シークレットの取り扱い（絶対厳守）

ここでミスをすると、クライアントの認証情報が漏えいします。細心の注意を払ってください。

1. すべてのシークレットは、デプロイ先のマシン上で新たに生成してください。 別の n8n インスタンスの暗号化キー、DB パスワード、.env を流用してはいけません。openssl コマンドについては SECURITY.md を参照してください。
2. シークレットは .env（モード 600）にのみ保存し、Compose から ${VAR} として参照してください。シークレットを docker-compose.yml、Caddyfile、その他コミットするものに直接記述してはいけません。
3. N8N_ENCRYPTION_KEY は厳重に管理してください。 保存されているすべての認証情報を暗号化します。紛失または変更すると、保存済みの認証情報をすべて復号できなくなります。必ず明示的に設定し、ユーザーにはマシンの外部にバックアップするよう伝えてください。引き渡しに必要な場合を除き、長期間保存されるログやチャット履歴に出力してはいけません。
4. 内部サービスを公開してはいけません。 公開するのは Caddy（80/443）のみです。n8n（5678）、Postgres（5432）、Redis（6379）はプライベートな Docker ネットワーク上に留めてください。テンプレートでは、すでにホスト側のポートマッピングを省いています。追加してはいけません。
5. .env と Caddy の caddy_data ボリューム（発行済み証明書と ACME アカウントキー）は共有してはいけない成果物です。 git リポジトリ内で作業する場合は、コミット前に .env が git の対象外になっていることを確認してください。

事前に収集する情報

• SSH 接続先 — user@host と認証方法（キーのパス、またはユーザーがエージェントにすでにアクセス権があることを確認）。root または sudo ユーザーが必要です。
• ドメイン — n8n のホスト名全体（例：n8n.example.com。→ SUBDOMAIN=n8n、DOMAIN_NAME=example.com）。ユーザーがその DNS を管理している必要があります。
• TLS 用メールアドレス — Let's Encrypt 用（SSL_EMAIL）。
• タイムゾーン — Schedule/Cron ノード用の IANA 名（例：Europe/Warsaw）。指定がなければ Etc/UTC を使用します。
• モード — シングルまたはキュー（ルール 0）。キューの場合は、マシンに十分な RAM があることを確認してください（最低でも約 4 GB、ワーカー 1 つあたり約 1～2 GB が必要です）。
• オプションモジュール — 一部の機能（現在は エージェント）はバックエンドモジュールであり、N8N_ENABLED_MODULES に指定しない限り無効です。ユーザーから話が出た場合にのみ確認してください。有効にする場合は、キューモードではワーカーにも到達できるようにする必要があるため、事前に QUEUE_MODE.md のモジュールのセクションを読んでください。

デプロイの流れ

以下の順序で進めてください。モードごとのコマンドの詳細は SINGLE_MODE.md／QUEUE_MODE.md、シークレットの生成とセキュリティ強化については SECURITY.md、更新／バックアップ／復元については DAY2.md を参照してください。

1. 事前確認（ここで問題を検出するのが最も低コストです）

• SSH でログインし、OS が Debian／Ubuntu 系であることを確認します（. /etc/os-release）。
• DNS がすでにこのサーバーを指している必要があります。 サーバーのパブリック IP（curl -s ifconfig.me）と dig +short <fqdn> の結果を比較します（サーバー上と、できればノート PC 上の両方で実行します）。一致しない場合は、作業を中止してください。Caddy の ACME チャレンジが失敗します。ユーザーに A レコードを作成してもらい、反映を待ってから続行します。
• ポート 80 と 443 にインターネットからアクセスできる必要があります。ホストのファイアウォールに加え、クラウドのセキュリティグループやネットワークファイアウォール（Hetzner Cloud、AWS SG など）も確認してください。これらはサーバーの外部にあり、気づきにくい一般的なブロッカーです。

2. Docker のインストール（未インストールの場合）

• docker --version と docker compose version を確認します。インストールされていない場合は、Docker Engine と Compose プラグインをインストールします（Ubuntu／Debian では Docker の公式 get.docker.com スクリプトで問題ありません）。 続行する前に、docker compose version を再確認します。

3. プロジェクトを配置する

• DATA_FOLDER を選びます。例：/opt/n8n のような絶対パスです。.env 内の DATA_FOLDER の値は、このディレクトリと完全に一致する必要があります（compose は ${DATA_FOLDER}/caddy_config/Caddyfile をマウントし、init-data.sh は相対パス ./ でマウントされるため、必ずここから docker compose を実行します）。このディレクトリと、その中に caddy_config/ および local_files/ を作成します。
• テンプレートファイルをサーバーに転送します。 テンプレートはサーバー上ではなく、お使いのマシンにあるこのスキルの assets/ 内にあります。それぞれを転送してください。scp で転送するか、ローカルコピーを使わずに SSH 経由で各ファイルの内容を書き込むことができます。例： ssh <target> 'cat > <DATA_FOLDER>/docker-compose.yml' < assets/docker-compose.single.yml 次の名前で配置してください。
  • 選択した compose → <DATA_FOLDER>/docker-compose.yml（名前を必ずこれに変更してください）
  • Caddyfile → <DATA_FOLDER>/caddy_config/Caddyfile
  • キューモードのみ： init-data.sh → <DATA_FOLDER>/init-data.sh に配置してから、chmod +x を実行します
  • 対応する .env.*.example → <DATA_FOLDER>/.env

4. .env の設定とシークレットの生成

• DATA_FOLDER、DOMAIN_NAME、SUBDOMAIN、SSL_EMAIL、GENERIC_TIMEZONE を設定します。
• 各シークレットは openssl を使ってサーバー上で生成し（コマンドは SECURITY.md にあります）、対応する REPLACE_WITH_… プレースホルダーを置き換えて .env に書き込みます。N8N_ENCRYPTION_KEY を設定します。キューモードでは、さらに POSTGRES_PASSWORD と POSTGRES_NON_ROOT_PASSWORD も設定します。
• 起動前に、未設定の値が残っていないことを確認してください： grep REPLACE_WITH_ .env が何も返さないことを確認します。プレースホルダーが残っていると、その文字列がパスワードとして使われ、Postgres／n8n の接続に失敗します。
• chmod 600 .env を実行します。暗号化キーを記録し、ユーザーがサーバー外にバックアップできるようにします。

5. ファイアウォール

• ufw で OpenSSH、80、443 を許可してから、有効にします。5678／5432／6379 は開放しないでください。

6. 起動

• cd <DATA_FOLDER> && docker compose up -d を実行します。
• キューモードでは Redis、Postgres、メイン、ワーカー（replicas 経由）が起動します。処理能力を追加するには、docker compose up -d --scale n8n-worker=N を実行します。

7. 検証する（確認する前に成功を宣言しないでください）

• docker compose ps — すべてのサービスが Up／healthy であること（キューモードでは、まず postgres と redis が healthy であること）。
• n8n 自体が起動していること（内部）： docker compose exec n8n wget -qO- http://localhost:5678/healthz → {"status":"ok"}。これにより、「n8n は稼働している」ことと「TLS の準備がまだできていない」ことを切り分けられます。
• 証明書が発行されていること： docker compose logs caddy | grep -i 'certificate obtained'。初回起動時の ACME 処理には 1〜2 分かかる場合があります。完了するまでは、公開 https:// リクエストは TLS エラーで失敗します。これは証明書がまだ発行待ちであることを意味し、n8n がダウンしているわけではありません。
• 公開アクセスの確認（リトライ付き）： curl -fsS --retry 5 --retry-delay 10 https://<fqdn>/healthz → {"status":"ok"}。（/healthz で確認できるのはプロセスに到達可能であることだけです。/healthz/readiness では、DB が接続され、マイグレーション済みであることも確認できます。起動ループのデバッグにはこちらを使用してください。）
• キューモード — メインとワーカーの設定が一致していること。 環境変数を比較します。 diff <(docker compose exec -T n8n env | sort) <(docker compose exec -T --index 1 n8n-worker env | sort)。 異なってよいのは公開 URL／プロキシ関連の変数だけです。それ以外の違いがある場合、動作に影響する設定がメインにしか反映されていません。ワークフローを実行するのはワーカーなので、起動時ではなく実行時にノードで失敗します。このルールについては QUEUE_MODE.md を参照してください。
• https://<fqdn> を開き、オーナー設定画面を表示します。この登録フォームを最初に完了したユーザーがインスタンスの所有者になります。所有者が未設定のまま公開されたインスタンスは先着争いになるため、URL を共有する前にすぐオーナーアカウントを作成してください。2FA を有効にしてください。（自動デプロイでは、代わりに環境変数を使ってオーナーを事前設定できます。SECURITY.md のオーナーの行を参照してください。）

8. 引き継ぐ

• ユーザーに、URL、プロジェクトの保存場所、安全に保管すべき暗号化キー、および DAY2.md に記載されている運用開始後の基本事項（更新／バックアップ／復元）を伝えます。

やってはいけないこと

• DNS／ポートの事前確認を省略しないでください。 A レコードの誤りやクラウドファイアウォールのポート閉鎖は、Caddy が証明書を取得できず、n8n が「壊れている」ように見える最大の原因です。
• 5678／5432／6379 をホストに公開しないでください。 Caddy はプライベートネットワーク経由で n8n に接続します。
• 別のインスタンスの暗号化キーや .env を再利用しないでください。 マシンごとに新しいシークレットを設定します。
• SQLite でキューモードを実行しないでください。 キューモードには Postgres が必要です（テンプレートにはすでに設定されています）。
• docker-compose.yml や Caddyfile にシークレットを記載しないでください。 .env のみを使用してください。
• （キューモードで）動作に影響する環境変数をメインのみに追加しないでください。 モジュール、DB、キュー、バイナリデータ、暗号化の設定は、ワーカーにも適用されるよう共有 x-n8n-env アンカーに記述します。メインのみに設定するのは公開 URL／プロキシ関連の変数だけです。QUEUE_MODE.md を参照してください。
• むやみに :latest を使用しないでください。 N8N_IMAGE_TAG を固定し、計画的に更新してください（DAY2.md）。

参考ファイル

• SINGLE_MODE.md — 単一インスタンス固有の内容、SQLite と Postgres の比較、キューへの移行時期。
• QUEUE_MODE.md — キューアーキテクチャ、ワーカー／同時実行／スケーリング、共有暗号化キー、メインとワーカー間の環境変数の整合性ルール、オプションのバックエンドモジュール（N8N_ENABLED_MODULES、例：Agents）、バイナリデータ（database モード。キューモードではファイルシステムは非対応。S3／Azure は Enterprise）、Webhook プロセッサー、複数メインのライセンス。
• SECURITY.md — シークレットの生成、暗号化キーのルール、完全なセキュリティ強化チェックリスト（テレメトリの無効化、環境変数へのアクセスのブロック、パブリック API、ファイアウォール、セキュア Cookie）。
• CREDENTIAL_OVERWRITES.md — 管理対象 OAuth：インスタンス全体で OAuth アプリを 1 つ登録すると、ユーザーにクライアント ID／シークレットを表示せずに済みます（セルフホスト環境で「Google でサインイン」）。エンドポイントと環境変数の選択、必須のエンドポイント認証トークン、親タイプの継承、永続化、ワーカーの再読み込み。
• DAY2.md — 設定（環境変数）の安全な変更、イメージの更新、バックアップ（暗号化キー＋ボリューム＋Postgres）、復元。
• assets/ — テンプレート：docker-compose.single.yml、docker-compose.queue.yml、Caddyfile、.env.single.example、.env.queue.example、init-data.sh。

信頼できるアップストリームの参照先：公式ホスティングドキュメントは https://docs.n8n.io/deploy/host-n8n にあります（2026 年半ばに以前の /hosting/ パスから再編成されたため、 これらの URL を優先してください）。環境変数のリファレンス一覧は https://docs.n8n.io/deploy/host-n8n/configure-n8n/basic-configuration/use-environment-variables にあります。 このスキルと最新のドキュメントに相違がある場合は、ドキュメントを優先してユーザーに伝えてください。