Deployment Guide

This guide is the operational deployment runbook for downstream Astro Agency sites. It covers the production deployment procedure and the repeatable redeployment workflow after a core sync.

For first-time downstream site setup, see the Site Setup Guide (DOC-00104).

The project should currently be treated as hybrid for deployment planning. The repository ships with the Node adapter configured in standalone mode, and the implemented feature set includes SSR requirement pages plus API-backed form routes.

Who This Is For

• Developers preparing a first production deployment
• Maintainers redeploying a site after sync:core

Deployment Model

The currently supported and validated deployment path is Node.js hosting using the @astrojs/node adapter in standalone mode. The build still emits static assets under dist/client/, but the production deployment should be treated as a hybrid application because server-rendered requirement pages and API-backed routes are part of the shipped system.

Cloudflare and other providers remain possible future targets, but this guide documents only the Node.js path that is implemented and validated in this repository today.

Pre-Deployment Requirements

Before every production deployment:

• npm run validate passes
• production environment variables are configured; see Site Feature Configuration — Environment Variables (DOC-00090) for the authoritative inventory
• src/site/config/site-url.ts points at the production URL
• local verification confirms the current site state is ready to ship

Build and Runtime Output

Build the project with:

npm run build

For the current standalone Node adapter setup:

• static assets are emitted under dist/client/
• the server entry is emitted under dist/server/
• the production process is started with Node against the generated entrypoint

Current production start command:

node dist/server/entry.mjs

Production Deployment Procedure

Follow these steps in order for the current supported Node.js deployment path.

1. Ensure dependencies are installed:

npm install

2. Run validation:

npm run validate

3. Build the production output:

npm run build

4. Optionally preview the production build locally before deploying:

npm run preview

5. Transfer the built application to the deployment environment using your host’s preferred mechanism.
6. Configure required environment variables in the deployment environment. The @astrojs/node standalone adapter respects HOST (default localhost) and PORT (default 4321) environment variables at runtime. Set these to match your deployment environment — for example, HOST=0.0.0.0 to listen on all interfaces.
7. Start the Node server process:

node dist/server/entry.mjs

8. Put the server behind your normal production web server or reverse proxy as needed for TLS termination, compression, and request routing.
9. Confirm the deployed site is reachable at the production URL.

Post-Deployment Smoke Tests

After each deployment, verify:

• the homepage loads
• a representative content page or article loads
• requirements pages render correctly
• forms and API-backed features work if configured
• search and navigation behave normally
• no obvious browser-console or server-runtime errors are present

Downstream Re-Deployment After Core Sync

When the core theme publishes a new release:

1. Sync to the latest stable release:

npm run sync:core

By default, the sync script auto-detects the latest stable version tag on the core remote (excluding prereleases) and syncs only if it is newer than the last sync recorded in .core-sync. If already up to date, it exits without changes.

To target a specific version:

npm run sync:core -- --ref v0.2.0

To sync from a branch during development (not recommended for production):

npm run sync:core -- --ref main --allow-branch

The --allow-branch flag is required when targeting a non-version ref (branch name or raw SHA) and displays a warning. Files matching .downstream-exclude patterns are automatically filtered from the sync output — they never appear in the working tree after sync.

See the Versioning Standard in .docs/standards/VERSIONING.md and Release Operations (DOC-00079) for how to find the latest stable tag.

2. Review the diff carefully.
3. Re-run validation:

npm run validate

4. Test locally before deploy.
5. Deploy the updated site using the same production procedure documented above.

Browser Support Baseline (REQ-00130)

The project targets the latest two major versions of Chrome, Firefox, Safari/WebKit, and Edge.

Future Targets

Cloudflare remains a planned optional deployment target. Provider-specific deployment instructions should be documented only after that path is implemented and validated in this repository.