v0.21

デプロイ

はじめに

dframeworkは生のスループットと低レイテンシの実行のために設計されています。本番環境向けにdframeworkは3つのデプロイアーキテクチャを提供します:

  1. ネイティブtlsを使用した直接ベアメタル(デフォルト): ネイティブトランスポートアドオンがopenssl tls 1.3の終端、httpからhttpsへのリダイレクト、およびルーティングを処理する単一プロセスアーキテクチャ。
  2. リバースプロキシ(--proxy): 他のサービスとポートを共有する場合や既存のプロキシスタックと統合する場合のcaddyまたはnginxの背後での従来のデプロイ。
  3. エッジデプロイ(--edge): エッジでtls終端が行われるcloudflareなどのcdnの背後でプレーンhttpを実行。

デプロイ戦略

直接ベアメタル(デフォルト)

直接ベアメタルモードではdframeworkはネイティブopenssl tlsでポート443をバインドし同時にポート80で軽量なリスナーを実行してhttpトラフィックをhttpsにリダイレクトします。

1[ client ] --( https:443 )--> [ dframework ssl app (native tls) ]
2[ client ] --( http:80 )----> [ dframework redirect app (301) ]

メリット:

caddyを使用したリバースプロキシ

リバースプロキシモードではcaddyなどの専用Webサーバーがポート443でパブリックhttpsトラフィックを受信しローカルループバック(127.0.0.1:8250)経由でプレーンhttpリクエストをdframeworkにプロキシします。

1[ client ] --( https:443 )--> [ caddy ] --( loopback:8250 )--> [ dframework ]

リバースプロキシを選択する場合:

cloudflareを使用したエッジデプロイ

エッジモードではcloudflareがパブリックtls接続を終端しhttpまたはhttps経由でオリジンサーバーにリクエストを転送します。

1[ client ] --( https )--> [ cloudflare edge ] --( http/https )--> [ dframework ]

メリット:

自動デプロイ

dstrn deployコマンドは設定生成、証明書プロビジョニング、およびサービスインストールを自動化します。

直接ベアメタルのセットアップ

ドメイン向けにベアメタルの本番設定を生成するには:

1dstrn deploy --domain=api.example.com --email=admin@example.com

マルチドメイン設定の場合はカンマ区切りでドメインを指定します:

1dstrn deploy --domain=api.example.com,admin.example.com --email=admin@example.com

このコマンドは以下のアクションを実行します:

  1. .env内の本番用APP_KEYを検証または生成します。
  2. storage/certs/{domain}/内の既存の証明書を確認し不足している証明書を取得します。
  3. アプリケーションがroot権限なしでポート80および443をバインドできるようにAmbientCapabilities=CAP_NET_BIND_SERVICEを含むdeploy/dframework-<app>.serviceを作成します。
  4. 毎週の証明書更新を自動化するためにdeploy/dframework-<app>-renew.timerとdeploy/dframework-<app>-renew.serviceを作成します。

リバースプロキシのセットアップ

caddyおよびsystemdサービス設定を生成するには:

1dstrn deploy --proxy --domain=api.example.com

これにより以下が生成されます:

  1. アプリケーションポートを指すリバースプロキシのルールを含むdeploy/Caddyfile。
  2. 標準の非特権実行用に設定されたdeploy/dframework-<app>.service。

エッジのセットアップ

cloudflareガイダンス付きのsystemdサービスファイルを生成するには:

1dstrn deploy --edge --domain=api.example.com

ドライランプレビュー

ディスクに書き込まずにターミナルで生成されたすべてのサービスおよび設定ファイルをプレビューします:

1dstrn deploy --domain=api.example.com --email=admin@example.com --dry-run

システムインストール

サーバー上でroot権限(sudo)で実行している場合dstrn deployは/etc/systemd/system/に直接書き込みサービスをアクティブ化できます:

1sudo dstrn deploy --domain=api.example.com --email=admin@example.com --install

手動デプロイのセットアップ

手動でのサーバープロビジョニングを希望する場合や自動化ツールを使用している場合は以下の手順に従ってください。

手動直接ベアメタル

ssl証明書と秘密キーをアプリケーションのstorageディレクトリに配置します:

1storage/certs/api.example.com/
2 cert.pem
3 key.pem

.envで本番環境変数を設定します:

1APP_ENV=production
2APP_DEBUG=false
3APP_URL=https://api.example.com
4APP_KEY=your_64_character_hex_key

/etc/systemd/system/dframework.serviceを作成します:

1[Unit]
2Description=dframework application server
3After=network.target
4
5[Service]
6Type=simple
7User=user
8WorkingDirectory=/var/www/app
9ExecStart=/usr/bin/node dstrn serve
10Restart=always
11RestartSec=3
12Environment=NODE_ENV=production
13AmbientCapabilities=CAP_NET_BIND_SERVICE
14
15[Install]
16WantedBy=multi-user.target

サービスを有効化して起動します:

1sudo systemctl daemon-reload
2sudo systemctl enable dframework
3sudo systemctl start dframework

手動caddyリバースプロキシ

debianまたはubuntuにcaddyをインストールします:

1sudo apt install -y debian-keyring debian-archive-keyring apt-transport-https curl
2curl -1sLf 'https://dl.cloudsmith.io/public/caddy/stable/gpg.key' | sudo gpg --dearmor -o /usr/share/keyrings/caddy-stable-archive-keyring.gpg
3curl -1sLf 'https://dl.cloudsmith.io/public/caddy/stable/debian.deb.txt' | sudo tee /etc/apt/sources.list.d/caddy-stable.list
4sudo apt update
5sudo apt install caddy

/etc/caddy/Caddyfileを設定します:

1api.example.com {
2 reverse_proxy 127.0.0.1:8250
3}

caddyをリロードします:

1sudo systemctl reload caddy

caddyはapi.example.comのlet's encrypt証明書を自動的に取得し更新を管理しループバック経由でリクエストをdframeworkにプロキシします。

tlsおよび証明書管理

証明書の自動検出

dframeworkは起動時にstorage/certs/内の証明書を自動的に検出します:

1storage/certs/
2 api.example.com/
3 cert.pem (or fullchain.pem, certificate.crt, api.example.com.crt)
4 key.pem (or privkey.pem, private.key, api.example.com.key)
5 ca.pem (optional intermediate chain)
6 admin.example.com/
7 cert.pem
8 key.pem

有効な証明書が見つかりAPP_URLがhttps://で始まる場合dframeworkは自動的にポート443でネイティブopenssl tlsを使用して起動しポート80でhttpからhttpsへのリダイレクトリスナーを開始します。

証明書管理コマンド

dstrn certコマンドファミリーは証明書のライフサイクル管理を提供します。

証明書の取得

1つ以上のドメインに対して新しいlet's encrypt証明書を取得します:

1dstrn cert:obtain --domain=api.example.com --email=admin@example.com
TIP

デプロイ検証中にlet's encryptのレート制限に達するのを避けるため本番発行の前に`--staging`を使用して証明書生成をテストしてください。

1dstrn cert:obtain --domain=api.example.com --email=admin@example.com --staging

証明書の更新

30日以内に期限切れになるすべての証明書を更新します:

1dstrn cert:renew --domain=api.example.com --email=admin@example.com

証明書の状態確認

インストールされているすべての証明書の有効期限、発行者情報、および有効性を確認します:

1dstrn cert:status

マルチドメインとsniルーティング

トランスポートはserver name indication(sni)をサポートしています。storage/certs/内に複数のドメインディレクトリが存在する場合tlsハンドシェイク中に各ドメインに対応する証明書が提供されます。

ワイルドカード証明書はアンダースコア始まりのディレクトリに配置できます(例: *.example.com用のstorage/certs/_.example.com/)。ワイルドカード一致は厳密な単一階層サブドメイン規則に従うため、_.example.comはapi.example.comには一致しますが、複数階層サブドメイン(a.b.example.com)やapexドメイン(example.com)には一致しません。apexドメインも併用するマルチ証明書構成では、apex用の証明書を独立した完全一致ディレクトリ(storage/certs/example.com/)に配置してください。

これをアプリケーションルートのドメインルートグループと組み合わせます:

1Route.domain('api.example.com', (api) => {
2 api.get('/status', async () => json({ service: 'api' }));
3});
4
5Route.domain('admin.example.com', (admin) => {
6 admin.get('/status', async () => json({ service: 'admin' }));
7});

httpからhttpsへのリダイレクト

tlsが有効な場合dframeworkは自動的にポート80でネイティブの非sslリスナーを開始します。http://domain/pathへのリクエストは即座にhttps://domain/pathを指す301 Moved Permanentlyレスポンスを受け取ります。

リダイレクトリスナーを無効にするにはconfig/app.jsでtls.redirect: falseを設定するか.envでTLS_REDIRECT=falseを設定します。

websocketセキュア接続

自動wss昇格

ページがhttps://経由でロードされた場合クライアントはwebsocket接続を自動的にwss://に昇格させます。

最初のページリクエストがhttpからhttpsにリダイレクトされるためブラウザは常にhttps:経由でロードされ安全なwss://接続を確立します。

ネイティブwebsocketアップグレード

サーバー側ではポート443を介したwebsocket接続はsslイベントループ内で直接処理されます。httpアップグレードハンドシェイクは既存の暗号化されたtls接続上で行われるため平文の露出がゼロになり即座にwebsocketが利用可能になります。

systemdサービスセットアップ

アプリケーションサービスユニット

本番systemdユニットファイル(/etc/systemd/system/dframework.service):

1[Unit]
2Description=dframework application server
3After=network.target
4
5[Service]
6Type=simple
7User=ubuntu
8WorkingDirectory=/var/www/app
9ExecStart=/usr/bin/node dstrn serve
10Restart=always
11RestartSec=3
12Environment=NODE_ENV=production
13AmbientCapabilities=CAP_NET_BIND_SERVICE
14
15[Install]
16WantedBy=multi-user.target
NOTE

`AmbientCapabilities=CAP_NET_BIND_SERVICE`によりsystemdサービスは非特権ユーザーアカウントで実行しながら特権下位ポート(80および443)をバインドできます。

証明書更新タイマーユニット

自動証明書更新には週次のsystemdタイマー(/etc/systemd/system/dframework-renew.timer)を使用します:

1[Unit]
2Description=certificate renewal timer for dframework
3
4[Timer]
5OnCalendar=weekly
6RandomizedDelaySec=3600
7Persistent=true
8
9[Install]
10WantedBy=timers.target

対応するoneshot更新サービス(/etc/systemd/system/dframework-renew.service):

1[Unit]
2Description=certificate renewal for dframework
3
4[Service]
5Type=oneshot
6WorkingDirectory=/var/www/app
7ExecStart=/usr/bin/node dstrn cert:renew --domain=api.example.com --email=admin@example.com
8ExecStartPost=/bin/systemctl restart dframework

更新タイマーを有効化します:

1sudo systemctl daemon-reload
2sudo systemctl enable dframework-renew.timer
3sudo systemctl start dframework-renew.timer

環境設定

標準的な本番環境の.env設定:

1APP_NAME=dframework
2APP_ENV=production
3APP_DEBUG=false
4APP_URL=https://api.example.com
5APP_KEY=your_generated_64_character_hex_key
6ACME_EMAIL=admin@example.com

オプションの明示的なtls設定(自動検出規約をオーバーライド):

1TLS_CERT=storage/certs/api.example.com/cert.pem
2TLS_KEY=storage/certs/api.example.com/key.pem
3TLS_CA=storage/certs/api.example.com/ca.pem
4TLS_REDIRECT=true

パフォーマンスに関する考慮事項

従来のアーキテクチャではアプリケーションランタイムの前にcaddyやnginxなどのリバースプロキシを配置します。ベンチマーク測定では二重ソケットバッファリング、プロセスのコンテキストスイッチ、およびループバックtcpシリアライゼーションによりリバースプロキシレイヤーが単純なルートに対して60%以上のオーバーヘッドを追加する可能性があります。

直接ベアメタルデプロイは中間プロキシレイヤーを排除し自動化されたlet's encrypt証明書管理とマルチドメインサポートを維持しながらアプリケーションのイベントループに最大のスループットを直接提供します。