Intégration du déploiement AppFolio
Aperçu
Déployez un service d'intégration conteneurisé pour la gestion immobilière AppFolio avec Docker. Ce skill couvre la construction d'une image prête pour la production qui se connecte à l'API AppFolio Stack pour gérer les propriétés, les locataires et les ordres de travaux. Il inclut la configuration d'environnement pour les configurations multi-propriétés, des contrôles de santé qui vérifient la connectivité de l'API, et des stratégies de mise à jour progressives pour des déploiements sans interruption sur l'ensemble de votre portefeuille immobilier.
Prérequis
- Un contrat de fournisseur vérifié et un client AppFolio lié au contrat, soutenu par un gestionnaire de secrets ; ne placez pas les valeurs d'identification dans les couches d'image, les fichiers compose, l'historique du shell ou les journaux de déploiement.
- Une plateforme de déploiement capable d'effectuer une véritable mise à jour progressive/canari avec des vérifications de disponibilité, un contrôle du trafic, un rollback et un propriétaire de version nommé.
- Des identités de staging et de production séparées, un fixture synthétique de smoke test en staging, et un plan d'incident pour les écritures ou l'état de réconciliation inconnus.
Instructions
- Construisez une image non-root avec des dépendances verrouillées et exposez uniquement un point de terminaison de liveness local ; la disponibilité du fournisseur relève de la readiness, pas de la survie du processus.
- Injectez la configuration client vérifiée au moment de l'exécution depuis le gestionnaire de secrets et validez son contrat en staging via une lecture sécurisée autorisée.
- Déployez une nouvelle révision progressivement, surveillez les signaux de readiness/erreur masqués, et conservez la révision précédente jusqu'à ce que la fenêtre de trafic réussisse.
- En cas d'échec d'une vérification de readiness, de contrat, de secret ou de réconciliation, arrêtez la promotion du trafic et effectuez un rollback via la plateforme de déploiement.
Configuration 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"]
Configuration d'exécution
# Les valeurs sont injectées par le gestionnaire de secrets de la plateforme de déploiement ; ne
# collez pas d'identifiants en clair dans une commande terminal ou une configuration versionnée.
APPFOLIO_BASE_URL="URL de base fournie par le fournisseur"
APPFOLIO_COMPANY_ID="identifiant de portefeuille approuvé"
export LOG_LEVEL="info"
export PORT="3000"
export NODE_ENV="production"
Point de terminaison de contrôle de santé
import express from 'express';
const app = express();
// Liveness prouve que ce processus peut servir ; il ne doit pas redémarrer un worker sain
// uniquement parce que le fournisseur externe est dégradé.
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' });
}
});
Étapes de déploiement
Étape 1 : Construire
docker build -t appfolio-integration:latest .
Étape 2 : Exécuter
docker run -d --name appfolio-integration \
-p 3000:3000 \
-e APPFOLIO_API_KEY -e APPFOLIO_BASE_URL -e APPFOLIO_COMPANY_ID \
appfolio-integration:latest
Étape 3 : Vérifier
curl -s http://localhost:3000/health | jq .
Étape 4 : Mise à jour progressive
# Soumettez le digest d'image immuable au contrôleur de déploiement de la plateforme.
# Configurez /health comme liveness et /ready comme readiness, déplacez le trafic par
# étapes, et conservez la révision précédente jusqu'à la fin de la fenêtre de version.
Gestion des erreurs
| Problème | Cause | Solution |
|---|---|---|
401 Unauthorized | Clé API invalide ou expirée | Régénérer la clé dans le portail partenaire AppFolio Stack |
403 Forbidden | Champ d'accès à la propriété manquant | Demander des champs supplémentaires à l'admin AppFolio |
404 Not Found | URL de base ou ID d'entreprise incorrect | Vérifier que APPFOLIO_BASE_URL correspond à votre sous-domaine |
429 Rate Limited | Trop de requêtes par minute | Implémenter un backoff exponentiel avec fenêtre de 60s |
| Le conteneur se termine immédiatement | Variables d'environnement requises manquantes | S'assurer que toutes les vars d'env sont définies avant de démarrer |
Résultat
- Un conteneur non-root avec un point de terminaison de liveness local et un résultat de readiness du fournisseur distinct et masqué
- Une frontière de configuration entre le gestionnaire de secrets et l'exécution plutôt que des valeurs d'identification dans les images ou les commandes
- Un reçu de déploiement par étapes avec preuve de readiness, état du trafic, propriétaire, cible de rollback et statut de réconciliation
Exemples
Pour une version de synchronisation des propriétés, déployez la nouvelle image en staging avec un fixture synthétique de safe-read et confirmez que /health reste actif pendant que /ready reflète le résultat du client fournisseur. Ne promouvez une petite partie du trafic de production qu'après avoir vérifié l'identité gérée, la readiness masquée, les alertes et la cible de rollback. Si la readiness échoue, un secret est absent ou une écriture antérieure a un résultat inconnu, gelez la promotion, ramenez le trafic à la révision précédente et assignez une réconciliation avant de tenter un autre déploiement.
Ressources
Prochaines étapes
Voir appfolio-webhooks-events.