Skip to content

Deployment

This page is the condensed runbook. The authoritative, step-by-step ops document is deploy/README.md — fresh-server bootstrap, backups, migrations, and recovery live there.

Where production runs

One VPS at 200.141.2.84, Docker Compose, Caddy as the only container with published ports (80/443, automatic Let's Encrypt).

Domain Service Container
aimstoreorg.com, www.aimstoreorg.com website SPA + payment API aim_website (:3001)
api.aimstoreorg.com Go backend API aim_api (:8080)
admin.aimstoreorg.com admin portal aim_admin_portal (:3002)
accounts.aimstoreorg.com accounting portal aim_account_admin_portal (:3003)
support.aimstoreorg.com support portal (ADR 0018) aim_support_portal (:3004)
docs.aimstoreorg.com this documentation aim_docs (:80)
monitor.aimstoreorg.com Grafana mon_grafana

Data stores (aim_postgres, aim_mongo, aim_redis) sit on the internal aim_data network and are never published. /metrics is 404'd at Caddy.

Server layout: /opt/aim-store/deploy (compose stack + Caddyfile + env), /opt/aim-store/monitoring, /opt/aim-store/backups, /opt/aim-store/static (bind-mounted into aim_api at /root/static for uploaded/team/player/KYC images).

How a deploy happens

Application releases use manual dispatch in .github/workflows/, including deploy-backend.yml (with its confirmation input) and deploy-website.yml. The documentation deploy has a path-filtered main-push trigger. Merging application code does not itself deploy the backend or website.

  1. build — Buildx builds the image and pushes latest + sha-<short> to ghcr.io/aimorgcode/{aim-api,aim-website,aim-admin,aim-docs}.
  2. deploy — copies the deploy/ (or monitoring/) configs to /opt/aim-store (git is the source of truth; server copies are overwritten), then over SSH — serialized with flock /tmp/aim-store-deploy.lock, set -e fail-fast — logs into GHCR and pulls the image.
  3. Backend only: a verified PostgreSQL dump into /opt/aim-store/backups (last 14 kept), then deploy/apply-migrations.sh runs pending SQL before the restart.
  4. docker compose --env-file .env.production up -d --no-deps --no-build <service> caddy and a Caddy reload. Data-service recreation is a separate controlled step.
  5. verify — curl --resolve <domain>:443:200.141.2.84 https://<domain>/… health checks, retried. A failed verification requires investigation and, when necessary, rollback to the recorded previous image.

GitHub CI checks

Pull requests and pushes to main use the full Git diff to select the affected projects. Website and mobile source changes also run the backend compatibility tests that read those clients. Manual CI dispatch runs all source suites.

Backend integration tests run in four jobs, each with its own PostgreSQL and Redis. Accounting portal tests run in three jobs while its API-mode bundle builds in parallel. The backend and account-admin checks report the combined results.

Pull requests run Docker smoke tests when image packaging or startup inputs change. Database migration and backup changes run a synthetic restore drill. The manual release-validation workflow runs all image and restore checks.

The Cloudflare hub preview watches aim-store-website/* and the root .nvmrc.

Mobile app releases (EAS Workflows)

Production Expo builds and submissions use EAS Workflows, which run on Expo's infrastructure and live in aim-store-app/.eas/workflows/ (beside eas.json, which is the EAS project root):

Workflow Trigger What it does
build-and-submit-android.yml manual only Builds the Android app bundle, then submits it to Google Play
submit-android.yml manual only Submits one named build to a chosen track (internal / alpha / production)

Merging app source runs validation and does not start a mobile build or store submission. Dispatching the production EAS workflow explicitly builds and submits: the existing production profile uses releaseStatus: completed, with no staged rollout fraction. A server-only release can leave the mobile changes committed for a later binary release.

.github/workflows/ci.yml runs the app's source checks when app files or the shared CI workflow change. The internal staging Android APK uses the manual build-staging-app workflow in GitHub Actions. Bring this workflow change into the staging branch before pushing further app changes there.

Release prerequisites live outside this repository:

  1. An authenticated Expo CLI with access to @aimstoreorg/aim-store-app. Run the manual workflow from the app directory using the reviewed Git ref; inspect the CLI's workflow:run --help for available ref/upload options.
  2. A Google Service Account Key must be registered in EAS credentials for com.aimstore.app. Without it every run fails at the submit job.

versionCode is allocated by EAS (appVersionSource: remote + autoIncrement), and signing uses the upload keystore in EAS credentials — neither is bumped or stored in this repo. Add [eas skip] to a commit message to skip a run.

Secrets

Names only — values are never committed (see ADR 0009):

  • GitHub repo secrets: VPS_HOST, VPS_USER, VPS_SSH_KEY, GHCR_PULL_USER, GHCR_PULL_TOKEN.
  • Server env files (chmod 600, generated by deploy/gen-env.sh): /opt/aim-store/deploy/.env, /opt/aim-store/deploy/portal.env.production, /opt/aim-store/monitoring/.env.

Rollback

Images are tagged sha-<short> on every build. Pin the affected service to a known-good tag in /opt/aim-store/deploy/.env and re-up:

# on the VPS
cd /opt/aim-store/deploy
echo 'API_IMAGE_TAG=sha-a1b2c3d' >> .env    # or WEBSITE_IMAGE_TAG /
                                            # ADMIN_PORTAL_IMAGE_TAG / DOCS_IMAGE_TAG
docker compose up -d --no-build api

Database restores come from /opt/aim-store/backups (pg_dump + mongodump, 14 most recent of each) — procedure in deploy/README.md.