AppFolio デプロイ統合
概要
コンテナ化されたAppFolio物件管理統合サービスをDockerでデプロイします。このスキルは、物件、テナント、作業指示書を管理するためにAppFolio Stack APIに接続するプロダクション対応イメージの構築をカバーします。マルチプロパティセットアップのための環境構成、API接続状態を確認するヘルスチェック、および物件ポートフォリオ全体でダウンタイムゼロのデプロイを実現するローリングアップデート戦略が含まれます。
前提条件
- 認証済みのプロバイダー契約と、秘密管理マネージャーでバックアップされた契約依存のAppFolioクライアント。イメージレイヤー、Composeファイル、シェル履歴、デプロイログに資格情報を直接記述しないでください。
- 実際のローリング/カナリアアップデートを実行できるデプロイメントプラットフォーム。準備完了チェック、トラフィック制御、ロールバック、および指名されたリリース所有者が必要です。
- ステージングと本番環境で別々のID、合成されたステージング用スモークテストフィクスチャ、および不明な書き込みや調整状態に対するインシデント計画。
手順
- 依存関係を固定した非rootイメージをビルドし、ローカルの生存確認エンドポイントのみを公開します。プロバイダーの可用性は生存確認ではなく準備完了チェックに属します。
- 認証済みのクライアント設定をシークレットマネージャーからランタイムに注入し、ステージング環境で許可された安全な読み取りを通じてその契約を検証します。
- 新しいリビジョンを段階的にロールアウトし、編集された準備完了/エラーシグナルを監視し、トラフィックウィンドウが成功するまで以前のリビジョンを保持します。
- 準備完了、契約、シークレット、または調整チェックが失敗した場合、トラフィックの昇格を停止し、デプロイメントプラットフォームを通じてロールバックします。
Docker構成
FROM node:20-slim AS builder
WORKDIR /app
COPY package*.json ./
RUN npm ci
COPY tsconfig.json ./
COPY src/ ./src/
RUN npm run build
FROM node:20-slim
RUN addgroup --system app && adduser --system --ingroup app app
WORKDIR /app
COPY --from=builder /app/dist ./dist
COPY --from=builder /app/node_modules ./node_modules
COPY package*.json ./
USER app
EXPOSE 3000
HEALTHCHECK --interval=30s --timeout=5s --retries=3 \
CMD node -e "fetch('http://127.0.0.1:3000/health').then(r => process.exit(r.ok ? 0 : 1)).catch(() => process.exit(1))"
CMD ["node", "dist/index.js"]
ランタイム構成
# 値はデプロイメントプラットフォームのシークレットマネージャーによって注入されます。ライブ資格情報をターミナルコマンドやチェックインされた構成に貼り付けないでください。
APPFOLIO_BASE_URL="プロバイダー発行のベースURL"
APPFOLIO_COMPANY_ID="承認済みポートフォリオ識別子"
export LOG_LEVEL="info"
export PORT="3000"
export NODE_ENV="production"
ヘルスチェックエンドポイント
import express from 'express';
const app = express();
// Livenessはこのプロセスがサービスを提供できることを証明します。外部プロバイダーが低下しているという理由だけで正常なワーカーを再起動してはなりません。
app.get('/health', (_req, res) => {
res.json({ status: 'healthy', service: 'appfolio-integration' });
});
app.get('/ready', async (_req, res) => {
try {
const response = await createVerifiedAppFolioClient().get('/properties?limit=1');
if (response.status < 200 || response.status >= 300) throw new Error(`AppFolio API returned ${response.status}`);
res.json({ status: 'ready', service: 'appfolio-integration', timestamp: new Date().toISOString() });
} catch (error) {
res.status(503).json({ status: 'not-ready', error: 'provider readiness check failed' });
}
});
デプロイ手順
ステップ1: ビルド
docker build -t appfolio-integration:latest .
ステップ2: 実行
docker run -d --name appfolio-integration \
-p 3000:3000 \
-e APPFOLIO_API_KEY -e APPFOLIO_BASE_URL -e APPFOLIO_COMPANY_ID \
appfolio-integration:latest
ステップ3: 確認
curl -s http://localhost:3000/health | jq .
ステップ4: ローリングアップデート
# イミュータブルなイメージダイジェストをプラットフォームのデプロイコントローラーに送信します。
# /healthをlivenessとして、/readyをreadinessとして構成し、段階的にトラフィックを移行し、リリースウィンドウが完了するまで前のリビジョンを保持します。
エラーハンドリング
| 問題 | 原因 | 修正方法 |
|---|---|---|
401 Unauthorized | APIキーが無効または期限切れ | AppFolio Stackパートナーポータルでキーを再生成 |
403 Forbidden | プロパティアクセススコープが不足 | AppFolio管理者に追加スコープをリクエスト |
404 Not Found | ベースURLまたは会社IDが誤り | APPFOLIO_BASE_URLがサブドメインと一致するか確認 |
429 Rate Limited | 1分あたりのリクエスト数が多すぎる | 60秒ウィンドウで指数バックオフを実装 |
| コンテナがすぐに終了する | 必要な環境変数が不足 | すべての環境変数が起動前に設定されていることを確認 |
出力
- ローカルの生存確認エンドポイントと、別個の編集済みプロバイダー準備完了結果を持つ非rootコンテナ
- イメージやコマンドに資格情報値を含めない、シークレットマネージャー/ランタイム構成の境界
- 準備完了証明、トラフィック状態、所有者、ロールバックターゲット、調整ステータスを含む段階的デプロイ受領証明
例
プロパティ同期リリースの場合、新しいイメージをステージングにデプロイし、合成された安全な読み取りフィクスチャを使用して、/healthが生き続け、/readyがプロバイダークライアントの結果を反映することを確認します。管理されたID、編集された準備完了、アラート、ロールバックターゲットが確認された後にのみ、本番トラフィックの小さなスライスを昇格します。準備完了チェックが失敗した場合、シークレットがない場合、または以前の書き込みの結果が不明な場合は、昇格を停止し、トラフィックを以前のリビジョンに戻し、次のロールアウトを試みる前に調整を割り当てます。
リソース
次のステップ
appfolio-webhooks-eventsを参照してください。