AlexandrAI AGENTS.md
agents-md

AB Deploy Agent Guide

Project-specific AGENTS.md guidance for the AB deployment harness, ita and prod profiles, APK builds, blue-green updates, rollback, and secret hygiene.

AGENTS.md

Guidance for coding agents working on AB Deploy. This repo contains the deployment harness for the AB API server, admin console, and Expo mobile APK workflow.

Project overview

ab-deploy drives two isolated deployment profiles. The internal test profile builds images, starts the full Docker stack, seeds data when needed, and can build an Android APK. The production profile uses image-based deployment with blue-green API and admin instances behind nginx.

The entry point is deploy.sh. Runtime state, generated env, logs, and active color files live under generated run directories and should not be treated as source.

Common commands

bashcd <project-root>/ab-deploy
./deploy.sh help
./deploy.sh ita --no-apk
./deploy.sh ita --seed
./deploy.sh apk ita
./deploy.sh prod
./deploy.sh deploy prod patch
./deploy.sh rollback prod
./deploy.sh versions prod
./deploy.sh stop ita --force

Use --no-upload when building an APK without sending it to a configured chat integration.

Deployment model

  • The internal test profile and production profile use separate Docker projects and non-overlapping endpoint placeholders.
  • API and admin images are built from the sibling application repos.
  • Blue-green updates start the standby color, wait for health, switch nginx active include, reload nginx, then drain the previous color.
  • Rollback uses the same active color switch and should leave the previous active color serving traffic if standby health fails.
  • Database bootstrap is idempotent at API start; do not add manual migration steps unless the app contract changes.

Configuration and secrets

Profile env files are copied from examples and then edited locally. Never publish real values for public host, admin token, database password, object storage credentials, chat token, or room id. Use <PUBLIC_HOST>, <ADMIN_TOKEN>, <DB_PASSWORD>, <S3_ACCESS_KEY>, <S3_SECRET>, <CHAT_TOKEN>, and <ROOM_ID> placeholders in docs.

APK workflow

APK builds should use the latest mobile source. The harness chooses local Android tooling when available and cloud build otherwise. The APK must embed the profile API URL placeholder resolved from local deployment configuration, not a hardcoded address.

Commit and PR rules

Treat shell changes as production operations code: keep functions small, preserve rollback safety, test both help output and a dry run where possible, and document any changed profile variable. Do not commit generated run state or copied env files.