Deployment Runtime

This document describes the live deployment path for capetownmarket-faas as it exists now.

The active deploy is GitHub Actions driven in .github/workflows/deploy-finance-faas.yml and finishes with the server rollout script at scripts/deploy-finance-faas-server.sh. The workflow still uses the fast_dev profile as its default run mode, so the current effective behavior is fast-window, fast-drain deployment rather than a slow maintenance-style rollout.

What A Deploy Does

The deploy pipeline is split into two phases:

1. Validation in GitHub Actions.
2. Server-side rollout and evidence capture in the deploy script.

Validation currently includes:

• Checkout and environment setup.
• Root Node tool installation for shared build tooling such as TypeDoc.
• Python and Node dependency setup.
• documentation-core tests and TypeDoc build validation.
• Portal-web build checks when frontend-relevant files changed.
• Source-level test coverage for deploy and runtime behavior.

The server rollout then:

• Enforces the current deploy boundary rules.
• Waits for or skips the drain window depending on the active profile.
• Refreshes the repo-root Node tooling used by the documentation build.
• Syncs the tracked database-abstraction-core company-map seed JSON into the live .faas-state runtime directory.
• Builds the official TypeDoc documentation site before service restart.
• Preserves portal assets when --skip-portal-build is allowed.
• Refreshes the active service tree and runtime artifacts.
• Captures health and configuration evidence from the live system.

Current Timing Model

The deploy workflow exposes timing knobs, but the active path still resolves to the fast profile:

• deploy_profile = fast_dev
• deploy window waiting is bypassed
• drain waiting is skipped
• the effective drain timeout is set to 0
• the effective drain interval is set to 1

The script still retains baseline fallback values for slower behavior, but those are not the effective values used by the current workflow path.

Operational Checks

The live rollout verifies the active platform surfaces rather than a generic test harness:

• automation-core health and ready checks
• documentation-core health, ready, TypeDoc status, and root-page checks
• capetown-faas-core health checks
• database-abstraction-core health checks
• company lookup and debtors configuration readiness
• nginx public-boundary verification that /dbcore returns 404 instead of proxying to database-abstraction-core
• system write-lock enforcement for mutating queue intents, including running-number allocation through the runningnumbers and debtors routes
• portal 500.html evidence

The rollout also captures queue and work-item state, deployment state, and other evidence so operators can inspect what the system looked like at the time of release.

Current Runtime Assumptions

The live deploy model assumes the current service topology and local host conventions used elsewhere in the repo:

• automation control lives on 50001
• capetown-faas-core lives on 50102
• database-abstraction-core lives on 50103
• documentation service lives on 50101
• production nginx publishes the portal, docs, and capetown-faas-core API routes, but keeps /dbcore closed because database-abstraction-core is an internal adapter service
• database-abstraction-core also reads the capetown runtime-state DB for direct internal write endpoints, so company-map writes, automated-mail mutations, running-number allocation, and cashier day-end execution respect the same system write lock

Those are still hard-coded in several scripts and service entrypoints, so the deployment docs should be read as a snapshot of the active topology rather than a portable, host-agnostic contract.

Documentation content changes are now deploy-relevant because documentation-core is the official published docs server and serves the repo documentation tree.

Rebuild Notes

This is the current doc baseline for deploy operations:

• active deployment flow
• fast-profile timing behavior
• deploy-window and drain semantics
• service health checks
• evidence capture and rollout artifacts

Historical rollout writeups and one-off runbooks now live in the external documentation archive.