AppFolio 배포 통합
개요
Docker를 사용하여 컨테이너화된 AppFolio 부동산 관리 통합 서비스를 배포합니다. 이 스킬은 AppFolio Stack API에 연결하여 자산, 세입자, 작업 지시를 관리하는 프로덕션 준비 이미지를 빌드하는 방법을 다룹니다. 멀티 자산 설정을 위한 환경 구성, API 연결성을 확인하는 헬스 체크, 자산 포트폴리오 전반에 걸쳐 제로 다운타임 배포를 위한 롤링 업데이트 전략이 포함됩니다.
사전 요구 사항
- 확인된 제공자 계약과 비밀 관리자 기반의 계약 바인딩 AppFolio 클라이언트; 이미지 레이어, 컴포즈 파일, 셸 히스토리 또는 배포 로그에 자격 증명 값을 넣지 마십시오.
- 준비 상태 확인, 트래픽 제어, 롤백, 명명된 릴리스 소유자가 있는 실제 롤링/카나리아 업데이트를 수행할 수 있는 배포 플랫폼.
- 별도의 스테이징 및 프로덕션 ID, 합성 스테이징 스모크 픽스처, 알 수 없는 쓰기 또는 조정 상태에 대한 사고 대응 계획.
지침
- 종속성이 고정된 비루트 이미지를 빌드하고 로컬 활성 종단점(liveness endpoint)만 노출하십시오; 제공자 가용성은 프로세스 생존이 아닌 준비 상태(readiness)에 속합니다.
- 확인된 클라이언트 구성을 런타임에 비밀 관리자에서 주입하고 승인된 안전 읽기를 통해 스테이징에서 계약을 검증하십시오.
- 새 리비전을 점진적으로 롤아웃하고, 수정된 준비 상태/오류 신호를 모니터링하며, 트래픽 윈도우가 성공할 때까지 이전 리비전을 유지하십시오.
- 준비 상태, 계약, 비밀 또는 조정 확인이 실패하면 트래픽 승격을 중단하고 배포 플랫폼을 통해 롤백하십시오.
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가 ${response.status}를 반환했습니다`);
res.json({ status: 'ready', service: 'appfolio-integration', timestamp: new Date().toISOString() });
} catch (error) {
res.status(503).json({ status: 'not-ready', error: '제공자 준비 상태 확인 실패' });
}
});
배포 단계
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 | 분당 너무 많은 요청 | 60초 윈도우로 지수 백오프 구현 |
| 컨테이너가 즉시 종료됨 | 필수 환경 변수 누락 | 시작 전에 모든 환경 변수가 설정되었는지 확인 |
출력
- 로컬 liveness 엔드포인트와 별도의 수정된 제공자 준비 상태 결과를 가진 비루트 컨테이너
- 이미지나 명령어에 자격 증명 값 대신 비밀 관리자/런타임 구성 경계
- 준비 상태 증거, 트래픽 상태, 소유자, 롤백 대상 및 조정 상태가 포함된 단계별 배포 영수증
예제
자산 동기화 릴리스의 경우, 합성 안전 읽기 픽스처로 스테이징에 새 이미지를 배포하고 /health가 계속 살아있는지 확인하는 동시에 /ready가 제공자 클라이언트 결과를 반영하는지 확인하십시오. 관리 ID, 수정된 준비 상태, 알림 및 롤백 대상이 확인된 후에만 소량의 프로덕션 트래픽을 승격하십시오. 준비 상태가 실패하거나, 비밀이 없거나, 이전 쓰기 결과가 알 수 없는 경우 승격을 중단하고 이전 리비전으로 트래픽을 되돌리고 후속 롤아웃 전에 조정을 할당하십시오.
리소스
다음 단계
appfolio-webhooks-events 참조.