Docker Deployment

The AppMecca API runs as a Docker container deployed via the standard CodeBuild + agent pipeline, the same as any other AppMecca application. The container runs uvicorn serving the FastAPI app.

Prerequisites

• An existing AppMecca environment with RDS provisioned (appmecca infra setup -e <env>)
• Docker host pool running with the deployment agent
• The appmecca-api app registered — on a fresh environment the agent registers and auto-deploys it on boot, so this is normally already true

Configuration

There is nothing to configure by hand. The API's deployment shape lives in its own appmecca.yaml, exactly like a tenant app:

containers:
  - name: api
    dockerfile: Dockerfile
    context: .

deploy:
  - name: api
    container: api
    port: 8080
    replicas: 3
    health_check:
      path: /api/health
      startup_timeout: 120
    resources:
      memory: 512m

Every runtime setting reaches the container as an environment variable injected by the agent at docker run time — see Environment Variables. The environment's own conf/{env}.yaml supplies the infrastructure values (region, domain, RDS engine version), and Secrets Manager supplies the secrets.

Deploy

The API ships with the rest of the platform from one git ref. There is no API-only publish:

appmecca publish <ref> -e dev

The release publish rebuilds only the components that changed since the environment's running release. The API rebuilds when its own source changed, and also whenever the agent rebuilds, because the API image stages the agent's appmecca_common wheel. For the API, the publish:

1. Resolves the ref on origin to one commit and checks it out in a throwaway worktree
2. Stamps the version derived for the environment into that worktree, uncommitted (a publish never commits, bumps or tags)
3. Ships the agent first and waits for the fleet to converge, then runs the API's own checks against the worktree: the appmecca_common floor and identity gates, and the SES configuration-set warning
4. Triggers a CodeBuild build of the pinned commit — which stages the appmecca_common wheel into the build context and passes --build-arg PG_MAJOR=<major> derived from the environment's RDS engine_version
5. Pushes the image to ECR and queues a deploy; the agent performs the normal zero-downtime blue/green swap, and the publish waits for it to finish

Flag	Effect
-e, --env	Environment name (required; also read from APPMECCA_ENV)
--dry-run	Print the commit, the minted version and which components would rebuild or skip; write nothing
-t, --timeout	Seconds to wait for each phase (fleet convergence, then the builds)
--json	Emit a CommandResult envelope instead of Rich output

The full sequence is Publishing the platform on the developer guide's operations page.

To reload the API's injected secrets or environment variables without a build, use appmecca api redeploy -e <env>. It redeploys the image the API is running now; a publish never redeploys an API whose code is unchanged.

Recovering when the API is down

appmecca publish <ref> queues its builds through the API. If the API is unreachable, use appmecca api recover -e <env> instead — it writes the BUILD and DEPLOY rows straight to PostgreSQL, falling back to an SSH-exec on a Docker host when your laptop cannot reach RDS (the normal case, since RDS sits in a private subnet).

Migrations

Migrations are not a separate deployment step. The container's entrypoint.sh runs the alembic chain before uvicorn starts, and exits non-zero if the schema is not present afterwards — so a failed migration fails the deploy rather than cutting traffic to a broken API. See Migrations.

Verify

curl https://api.dev.appmecca.net/api/health

Expected response:

{
    "status": "ok",
    "environment": "dev",
    "version": "4.27.50"
}

Add ?deep=true to include a database round-trip:

{
    "status": "ok",
    "environment": "dev",
    "version": "4.27.50",
    "database": "healthy",
    "tables": 67
}

tables is the raw information_schema count for the public schema, so it includes alembic_version alongside the application tables. A failed database check flips status to degraded and puts the error text in database.

Resources Involved

Resource	Name Pattern
ECR repository	appmecca/{env}/appmecca-api/{container} (one per container, here api)
CodeBuild project	appmecca-{env}-appmecca-api-build
ALB target group	Recorded in the target_groups table
Reserved hostname	api.{env}.appmecca.net
CloudFront distribution	Comment appmecca {env} api cache
IAM user	appmecca-{env}-api-user
Credentials secret	appmecca/{env}/api-aws-creds

There is no CloudFormation stack, no Lambda function, and no API Gateway — the API is an ordinary containerised app on the host pool.