AWS sandbox deployment¶
The App Deploy workflow validates CHART, publishes commit-tagged images to
GitHub Container Registry, and deploys those images to one EC2 host with Docker
Compose. EC2 receives only docker-compose.yml and Caddyfile, beside its
own .env.prod and database backups; it does not clone or build the
repository. Keycloak, its theme and the email-code plugin ship as images too.
The operational setup is documented in
infra/aws/README.md.
GitHub configuration¶
Create a GitHub environment named dev with these connection secrets:
| Secret | Purpose |
|---|---|
AWS_APP_HOST |
EC2 hostname or IP used by SSH. |
AWS_APP_USER |
EC2 deployment user. |
AWS_APP_SSH_KEY |
Private SSH key for that user. |
To post merges to Slack, add a repository secret SLACK_WEBHOOK_URL: an
incoming webhook from the Chart-MVP Slack app (api.slack.com/apps →
Incoming Webhooks → Add New Webhook, then pick the channel). The
Merge notify workflow then posts each pull request merged into dev or
main: its title, a details line, the Summary section of the pull
request template (or the description's first paragraph) and links to the
pull request and deploys. Without the secret it skips the message.
Application settings are written once in the gitignored
infra/aws/.env.prod, then copied unchanged to
~/chart-deploy/aws/.env.prod on EC2. The settings, including the email
server that delivers sign-in codes (sign-in), are listed once in
infra/aws/README.md.
Host setup¶
Install Docker with the Compose plugin and allow the deployment SSH user to run
Docker. The workflow creates ~/chart-deploy and its backup directory without
requiring access to /opt.
Allow inbound ports 80 and 443 and point the public domain at the instance.
Caddy obtains and renews certificates for an HTTPS PUBLIC_ORIGIN. An HTTP
origin is suitable only for an isolated sandbox; Google sign-in requires HTTPS
for a non-local callback.
Create ~/chart-deploy/aws/.env.prod before the first deployment. Preserve the
existing POSTGRES_PASSWORD when retaining an existing database volume.
Model artifacts on S3¶
Load observed climate history once per country after the outlooks are
installed and registered, from ~/chart-deploy/aws. The Dagster code container
holds the Copernicus key and the ERA5 cache volume:
docker compose --env-file .env.prod exec -T chart-dagster-code \
python -m chart.climate.history backfill --country IN --years 20
docker compose --env-file .env.prod exec -T chart-dagster-code \
python -m chart.climate.history verify --country IN --years 20
Repeat for KE. The sandbox keeps 20 years; the command is safe to re-run and
only downloads what is missing. Afterwards a maintainer with bucket write
access can share the retained grids so other installations skip the
Copernicus queue: copy /opt/chart/data/climate/era5-cache from the host and
run make climate-mirror-publish ERA5_CACHE_DIR=<copy>.
For the October 2026 India/Kenya projections, upload the generated outlooks/
tree and register its geography hierarchy after the model sync. Follow the
outlook installation commands.
These JSON publications are separate from the R scoring artifacts below.
Each model release consists of a checked-in manifest under
pipelines/models/<family>/ and its .rds files under the manifest's S3
base_uri. Before starting the scorer, Compose syncs the configured bucket into
the shared chart-lbw-model volume and excludes archive/*.
Set MODEL_BUCKET_PUBLIC=1 for the current anonymous list/read bucket policy.
For a private bucket, set it to 0 and grant the EC2 instance role
s3:ListBucket and s3:GetObject on the bucket. No AWS access keys are stored
in GitHub.
The sync is idempotent. A release fails during startup if a manifest artifact is missing or its SHA-256 does not match.
To add a model release:
- Upload the
.rdsfile beneath the manifest's S3base_uri. - Commit the manifest under
pipelines/models/<family>/. - Merge to
dev; the next deployment syncs and activates it.
Deployment and verification¶
Pull requests run validation and build all deploy images without changing EC2.
A push to dev, or a manually dispatched workflow, publishes and deploys the
exact commit SHA. The workflow then checks that the public web build reports
that SHA and that the API readiness endpoint succeeds.
On failure, the workflow reports Compose status and recent logs. On the host, the current containers can be inspected with:
Database backups are created in ~/chart-deploy/aws/backups before migrations
and kept for 14 days. Postgres, models, climate outputs, Dagster state, and
Caddy certificates use named Docker volumes.
The climate worker sets ERA5_CACHE_DIR=/opt/chart/data/climate/era5-cache on
the existing climate volume. Deploy the updated code and compose configuration
to retain raw downloads across container replacements and reuse them for newly
registered areas. This does not move caches from older ephemeral containers;
missing acquisitions are downloaded on the next pull.