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.
- build — Buildx builds the image and pushes
latest+sha-<short>toghcr.io/aimorgcode/{aim-api,aim-website,aim-admin,aim-docs}. - deploy — copies the
deploy/(ormonitoring/) configs to/opt/aim-store(git is the source of truth; server copies are overwritten), then over SSH — serialized withflock /tmp/aim-store-deploy.lock,set -efail-fast — logs into GHCR and pulls the image. - Backend only: a verified PostgreSQL dump into
/opt/aim-store/backups(last 14 kept), thendeploy/apply-migrations.shruns pending SQL before the restart. docker compose --env-file .env.production up -d --no-deps --no-build <service> caddyand a Caddy reload. Data-service recreation is a separate controlled step.- 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:
- 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'sworkflow:run --helpfor available ref/upload options. - 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.