AppFolio Deploy Integration
Visão Geral
Implante um serviço de integração containerizado de gerenciamento de propriedades AppFolio com Docker. Este skill cobre a construção de uma imagem pronta para produção que se conecta à AppFolio Stack API para gerenciar propriedades, inquilinos e ordens de serviço. Inclui configuração de ambiente para setups multi-propriedade, verificações de integridade que confirmam a conectividade da API e estratégias de atualização contínua para implantações com zero downtime em todo o seu portfólio de propriedades.
Pré-requisitos
- Um contrato de provedor verificado e um cliente AppFolio vinculado ao contrato e apoiado por um gerenciador de segredos; não coloque valores de credenciais em camadas de imagem, arquivos compose, histórico de shell ou logs de implantação.
- Uma plataforma de implantação que possa realizar uma atualização contínua/canary real com verificações de prontidão, controle de tráfego, rollback e um proprietário de release nomeado.
- Identidades separadas de staging e produção, um fixture sintético de smoke test para staging e um plano de incidente para estado de gravação ou reconciliação desconhecido.
Instruções
- Construa uma imagem não-root com dependências travadas e exponha apenas um endpoint de liveness local; a disponibilidade do provedor pertence à prontidão, não à sobrevivência do processo.
- Injete a configuração verificada do cliente em runtime a partir do gerenciador de segredos e valide seu contrato em staging por meio de uma leitura segura autorizada.
- Lance uma nova revisão gradualmente, monitore sinais de prontidão/erro (com dados sensíveis omitidos) e retenha a revisão anterior até que a janela de tráfego seja bem-sucedida.
- Em qualquer falha de prontidão, contrato, segredo ou verificação de reconciliação, interrompa a promoção de tráfego e reverta por meio da plataforma de implantação.
Configuração 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"]
Configuração em Tempo de Execução
# Os valores são injetados pelo gerenciador de segredos da plataforma de implantação;
# não cole credenciais ativas em um comando de terminal ou em configuração versionada.
APPFOLIO_BASE_URL="URL base fornecida pelo provedor"
APPFOLIO_COMPANY_ID="identificador de portfólio aprovado"
export LOG_LEVEL="info"
export PORT="3000"
export NODE_ENV="production"
Endpoint de Verificação de Integridade
import express from 'express';
const app = express();
// Liveness prova que este processo pode atender; não deve reiniciar um worker
// saudável apenas porque o provedor 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 retornou ${response.status}`);
res.json({ status: 'ready', service: 'appfolio-integration', timestamp: new Date().toISOString() });
} catch (error) {
res.status(503).json({ status: 'not-ready', error: 'verificação de prontidão do provedor falhou' });
}
});
Etapas de Implantação
Etapa 1: Construir
docker build -t appfolio-integration:latest .
Etapa 2: Executar
docker run -d --name appfolio-integration \
-p 3000:3000 \
-e APPFOLIO_API_KEY -e APPFOLIO_BASE_URL -e APPFOLIO_COMPANY_ID \
appfolio-integration:latest
Etapa 3: Verificar
curl -s http://localhost:3000/health | jq .
Etapa 4: Atualização Contínua
# Submeta o digest da imagem imutável ao controlador de implantação da plataforma.
# Configure /health como liveness e /ready como readiness, desloque o tráfego em
# estágios e retenha a revisão anterior até que a janela de release seja concluída.
Tratamento de Erros
| Problema | Causa | Correção |
|---|---|---|
401 Unauthorized | Chave de API inválida ou expirada | Regere a chave no portal AppFolio Stack Partner |
403 Forbidden | Escopo de acesso a propriedade ausente | Solicite escopos adicionais ao administrador AppFolio |
404 Not Found | URL base ou ID da empresa incorretos | Verifique se APPFOLIO_BASE_URL corresponde ao seu subdomínio |
429 Rate Limited | Muitas requisições por minuto | Implemente backoff exponencial com janela de 60s |
| Container sai imediatamente | Variáveis de ambiente obrigatórias ausentes | Certifique-se de que todas as variáveis de ambiente estão definidas antes de iniciar |
Saída
- Um contêiner não-root com um endpoint de liveness local e um resultado de prontidão do provedor separado e com dados sensíveis omitidos
- Um limite de configuração entre gerenciador de segredos/runtime em vez de valores de credenciais em imagens ou comandos
- Um recibo de implantação em estágios com evidência de prontidão, estado do tráfego, proprietário, alvo de rollback e status de reconciliação
Exemplos
Para um release de sincronização de propriedades, implante a nova imagem no staging com um fixture sintético de leitura segura e confirme que /health permanece ativo enquanto /ready reflete o resultado do cliente do provedor. Promova uma pequena fatia de tráfego de produção apenas após a identidade gerenciada, prontidão (com dados omitidos), alertas e alvo de rollback serem verificados. Se a prontidão falhar, um segredo estiver ausente ou uma gravação anterior tiver um resultado desconhecido, congele a promoção, retorne o tráfego para a revisão anterior e atribua reconciliação antes de tentar outro rollout.
Recursos
Próximos Passos
Consulte appfolio-webhooks-events.