Deployment

Step-by-step guide for deploying the Volāre backend and frontend to staging and production environments.

The backend ships as Docker images to AWS ECR, then deployed onto servers via the infra-volare repository. The frontend deploys separately through git-connected Cloudflare Workers Builds — see Frontend (Cloudflare Workers).

Overview (backend)

Deploying the backend requires two sequential steps:

1. Build — Docker images are built and uploaded to AWS ECR. This does not deploy anything — it only prepares the images. Builds trigger on PRs labeled ready-to-test, on workflow_dispatch, and on the new version tag created after a merge (see below).
2. Deploy (manual) — A developer triggers the deploy workflow from the infra-volare repository to put those images on a server.

The deploy process is the same for both staging and production — the only difference is the environment selected in the workflow.

Prerequisites

• Access to the infra-volare GitHub repository
• A merged PR in the volare repository (or a known image tag to deploy)

Automated Pipeline (after merge)

When a PR is merged to master, the workflows in the volare Actions tab chain like this:

1. Tag on Merge (tag-on-merge.yml) — Creates a semantic version tag (e.g., v1.3.0) from conventional commit messages, then dispatches the build workflow on that new tag.
2. Build & Push to ECR (build-images.yml) — Builds the Docker images and pushes them to AWS ECR, tagged with the version. Images built: php-fpm, queue-worker, backend (nginx), and frontend, plus php-base, analytics-mcp, and the Nightwatch agent. (The build workflow also runs directly on PRs labeled ready-to-test, so images can be tested before merge.)

Before deploying, verify both workflows completed successfully in the Actions tab. The version tag created (e.g., v1.3.0) is the value you will use as the image tag when deploying. You can find it in the repository tags.

Deploying

Once images are built and available in ECR, trigger the deploy:

1. Go to infra-volare Actions
2. Select the Deploy infrastructure workflow
3. Click Run workflow
4. Fill in the form:

Field	Description	Example
Environment to deploy	Target environment	staging-1 or production-1
Frontend image tag	Version tag for the frontend image	v1.3.0
Backend image tag	Version tag for the backend image	v1.3.0

5. (Optional) Check “Only run plan, do not apply” to preview infrastructure changes without deploying
6. Click Run workflow

Tips

• There is no required order between staging and production. You can deploy directly to production if needed.
• Use the sha-<commit> tag format if you need to deploy a specific commit that is not a release.
• The Frontend image tag field may be vestigial: the frontend now deploys through Cloudflare Workers Builds, not the ECR image (though a frontend ECR image is still built). Confirm current behavior in the infra-volare deploy workflow before relying on it.

Frontend (Cloudflare Workers)

The Astro frontend deploys via git-connected Cloudflare Workers Builds — no manual image tag step (introduced in PR #2221).

• Adapter: @astrojs/cloudflare is selected at build time when DEPLOY_TARGET=cloudflare (Node adapter otherwise). See frontend/astro.config.mjs.
• Worker config: frontend/wrangler.jsonc — declares the SESSION_KV KV binding, nodejs_compat, and observability. There is no custom domain / route; the Worker is reachable only via workers.dev URLs.
• Package manager: pinned to pnpm@11.0.8 via packageManager in frontend/package.json.
• Branch behavior:
  • master → production deploy
  • other branches → per-branch workers.dev preview URLs (no staging custom domain, keeping staging off any indexable hostname)
• Secrets/variables (API_URL, GTM_ID, INTERNAL_API_TOKEN) are managed via wrangler secret put or the Cloudflare dashboard — not committed.

Post-deploy Verification

After the workflow completes, verify the deployment is healthy:

Health Endpoint

# Replace with the actual environment URL
curl https://<environment-url>/health

A 200 response with all checks ok confirms the deployment is healthy. See Health Monitoring for details on available checks.

Monitoring Dashboards

• Telescope (/telescope) — Look for new exceptions or errors after the deploy
• Sentry — Error and performance tracking (sentry/sentry-laravel)
• Nightwatch — Application performance monitoring via the agent container

Rollback

To roll back a deployment, run the deploy workflow again with the previous version tag. The containers will be replaced with the earlier image.

Related Documentation

• Docker Health Monitoring — Container runtime and health checks
• Health Monitoring — Application health endpoints and dashboards