Integración de Despliegue AppFolio
Resumen
Despliega un servicio de integración de gestión inmobiliaria AppFolio contenerizado con Docker. Esta skill cubre la construcción de una imagen lista para producción que se conecta a la API Stack de AppFolio para gestionar propiedades, inquilinos y órdenes de trabajo. Incluye configuración de entorno para configuraciones multi-propiedad, health checks que verifican la conectividad de la API y estrategias de actualización rolling para despliegues sin tiempo de inactividad en tu cartera de propiedades.
Requisitos Previos
- Un contrato de proveedor verificado y un cliente AppFolio respaldado por un gestor de secretos y vinculado al contrato; no coloques valores de credenciales en capas de imagen, archivos compose, historial del shell o registros de despliegue.
- Una plataforma de despliegue que pueda realizar una actualización rolling/canary real con comprobaciones de readiness, control de tráfico, rollback y un propietario de versión nombrado.
- Identidades separadas de staging y producción, un fixture sintético de staging para pruebas de humo y un plan de incidencias para estados de escritura o reconciliación desconocidos.
Instrucciones
- Construye una imagen no-root con dependencias fijadas y expón solo un endpoint local de liveness; la disponibilidad del proveedor pertenece al readiness, no a la supervivencia del proceso.
- Inyecta la configuración del cliente verificado en tiempo de ejecución desde el gestor de secretos y valida su contrato en staging mediante una lectura segura autorizada.
- Despliega una nueva revisión gradualmente, monitorea señales de readiness/error redactadas y retén la revisión anterior hasta que la ventana de tráfico se complete con éxito.
- Ante cualquier fallo de readiness, contrato, secreto o verificación de reconciliación, detén la promoción de tráfico y revierte el cambio a través de la plataforma de despliegue.
Configuración de 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"]
Configuración de Ejecución
# Los valores son inyectados por el gestor de secretos de la plataforma de despliegue; no
# pegues credenciales en vivo en un comando de terminal o en una configuración versionada.
APPFOLIO_BASE_URL="URL base proporcionada por el proveedor"
APPFOLIO_COMPANY_ID="identificador de cartera aprobado"
export LOG_LEVEL="info"
export PORT="3000"
export NODE_ENV="production"
Endpoint de Health Check
import express from 'express';
const app = express();
// Liveness demuestra que este proceso puede servir; no debe reiniciar un worker sano
// únicamente porque el proveedor externo esté degradado.
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 devolvió ${response.status}`);
res.json({ status: 'ready', service: 'appfolio-integration', timestamp: new Date().toISOString() });
} catch (error) {
res.status(503).json({ status: 'not-ready', error: 'la comprobación de readiness del proveedor falló' });
}
});
Pasos de Despliegue
Paso 1: Construir
docker build -t appfolio-integration:latest .
Paso 2: Ejecutar
docker run -d --name appfolio-integration \
-p 3000:3000 \
-e APPFOLIO_API_KEY -e APPFOLIO_BASE_URL -e APPFOLIO_COMPANY_ID \
appfolio-integration:latest
Paso 3: Verificar
curl -s http://localhost:3000/health | jq .
Paso 4: Actualización Rolling
# Envía el digest de la imagen inmutable al controlador de despliegue de la plataforma.
# Configura /health como liveness y /ready como readiness, cambia el tráfico en
# etapas y retén la revisión anterior hasta que la ventana de versión se complete.
Manejo de Errores
| Problema | Causa | Solución |
|---|---|---|
401 No Autorizado | Clave API inválida o expirada | Regenerar clave en el portal de socios de AppFolio Stack |
403 Prohibido | Falta ámbito de acceso a propiedades | Solicitar ámbitos adicionales al administrador de AppFolio |
404 No Encontrado | URL base o ID de empresa incorrectos | Verificar que APPFOLIO_BASE_URL coincida con tu subdominio |
429 Límite de Velocidad | Demasiadas solicitudes por minuto | Implementar backoff exponencial con ventana de 60s |
| El contenedor sale inmediatamente | Faltan variables de entorno requeridas | Asegurar que todas las variables de entorno estén configuradas antes de iniciar |
Salida
- Un contenedor no-root con un endpoint local de liveness y un resultado de readiness del proveedor separado y redactado
- Un límite de configuración entre el gestor de secretos y el entorno de ejecución, en lugar de valores de credenciales en imágenes o comandos
- Un recibo de despliegue por etapas con evidencia de readiness, estado del tráfico, propietario, objetivo de rollback y estado de reconciliación
Ejemplos
Para una versión de sincronización de propiedades, despliega la nueva imagen en staging con un fixture sintético de lectura segura y confirma que /health permanezca vivo mientras que /ready refleje el resultado del cliente del proveedor. Promociona una pequeña porción de tráfico de producción solo después de que la identidad gestionada, el readiness redactado, las alertas y el objetivo de rollback estén verificados. Si el readiness falla, falta un secreto o una escritura previa tiene un resultado desconocido, congela la promoción, devuelve el tráfico a la revisión anterior y asigna reconciliación antes de intentar otro despliegue.
Recursos
Próximos Pasos
Consulta appfolio-webhooks-events.