Deployment

This page walks you through shipping a change: from merging a PR in volare to the new version running on staging or production. The infrastructure behind it is explained in the Infrastructure section.

The pipeline at a glance

flowchart LR
  M[PR merged to master] --> T[Tag on Merge<br/>creates v1.2.3]
  T --> B[Build & Push to ECR<br/>images tagged v1.2.3]
  B --> D[You run Deploy Infrastructure<br/>in infra-volare]
  D --> S[New servers boot<br/>with v1.2.3]

The first two steps are automatic. Deploying is always a manual step that you trigger in infra-volare, and staging and production are deployed independently (there is no required order).

1. Merge creates a version and images

When a PR that changes code is merged to master, the workflows in the volare Actions tab run:

1. Tag on Merge (tag-on-merge.yml) creates a version tag from the squashed commit title: feat → minor (v1.3.0), everything else → patch (v1.2.4), BREAKING CHANGE → major.
2. Build & Push to ECR (build-images.yml) runs on that tag and pushes php-base, php-fpm, queue-worker, backend (nginx), frontend and analytics-mcp to ECR tagged with the version, latest and sha-<commit>. It also mirrors the Nightwatch agent image.

Wait until both are green. The version is in the repository tags.

Testing images before merging

Add the ready-to-test label to a PR to build its images. They are tagged with the branch name and sha-<commit>, so you can deploy the PR to staging before merging.

Docs-only and test-only changes

A merge that only touches docs/ and/or backend/tests/ creates no tag and builds no images — there is nothing to deploy. Such PRs are also merged automatically without review. See PR Merge Paths.

2. Deploy

1. Open infra-volare › Actions.

2. Choose Deploy Infrastructure → Run workflow (branch main).

3. Fill in:

   Field	Value
   Environment	staging-1 or production-1
   Frontend version	the tag to run on the Web, e.g. v1.3.0
   Backend version	the tag to run on Arkana/API/queues, e.g. v1.3.0
   Deploy Hermes	leave unticked
   Hermes only	leave unticked

4. Run it. The workflow checks the tags exist in ECR, applies the environment and replaces every server with new ones running the requested images. The old servers stop only after the new ones are healthy, so there is no downtime.

Both version fields are required. If you only changed the backend, enter the frontend tag that is already running (and vice versa), or you will also roll the other side.

Fast-lane ASG Deploy takes the same inputs and only touches the servers, skipping network and DNS. Use it when you only ship new tags. Details of both workflows: Deploy Workflows.

Caution

• Never deploy the master tag — it is a stale image from January 2026 without the php-fpm health check. Use vX.Y.Z or sha-<commit>.
• Migrations run automatically when the new ops-runner boots. Make sure they are safe while the previous version is still serving traffic for a few minutes.

3. Verify

• Watch the workflow summary: it waits until every server group is healthy (up to 20 minutes).
• Open the site and Arkana and check the change.
• Check Sentry and Nightwatch for new errors in the first minutes.
• Grafana alerts (production only) will page the team if containers keep restarting or 5xx rates rise — see Monitoring and Alerts.

/health and Telescope are only reachable over Twingate (see Networking and Access).

Rollback

Run Deploy Infrastructure again with the previous version tags. Database migrations are not rolled back — if the bad release changed the schema, write a forward fix or roll back the migration deliberately from the ops-runner.

Frontend: Cloudflare Workers previews

Separately from AWS, the frontend is connected to Cloudflare Workers Builds, which builds every push that touches frontend/:

• Build command DEPLOY_TARGET=cloudflare pnpm build (switches astro.config.mjs to the @astrojs/cloudflare adapter); config in frontend/wrangler.jsonc.
• Branches get a preview URL; master deploys the volare Worker.
• The pnpm version comes from packageManager in frontend/package.json (pnpm@11.28.5).

These Workers are for previews and testing. Production byvolare.com is served by the front servers on AWS using the frontend ECR image you choose in the deploy form.

Related

• Deploy Workflows — every infra-volare workflow
• Servers and Containers — what runs where, and how to change env vars
• Server Access — shells and running Artisan in production
• Health Monitoring — application health checks