Developer Docs

Staging Environment Architecture

The Ngwenya platform features a production-parity staging environment orchestrated entirely via Docker Compose. It encapsulates all 5 platform repositories into a 34-container topology that mirrors production exactly, including routing, data services, and Error Tracking (GlitchTip).

This environment is designed for pre-production QA, load testing, and beta verification without risking production data.

Architecture Overview

The staging environment is defined in docker-compose-staging.yaml within the ngwenya-federation repository. Unlike the Local Development Environment (which mounts source code and runs dev servers), staging uses production-built artifacts.

1. NestJS & Rust Subgraphs

All 19 NestJS backend services are built using multi-stage production targets (using dist/ and NODE_ENV=production). The 4 Rust services (auth, uchat, intelligence, tower) are compiled as release binaries.

2. Frontend & Portals

  • Frontend (ngwenya-front): Swaps @sveltejs/adapter-auto for @sveltejs/adapter-node, producing a standalone Node server running on port 4173.
  • Portals (ngwenya-dev, ngwenya-support): The Astro static sites are built and copied into an nginx:alpine container with optimized caching headers and gzip compression.

3. Native Mobile Integration

The iOS and Android shells connect to staging via build-time configurations:

  • iOS (Swift): Uses an #if STAGING conditional in NgwenyaViewModel.swift.
  • Android (Kotlin): Uses a staging build flavor exposing BuildConfig.GATEWAY_URL.

When running mobile simulators, they connect to the internal gateway exposed by the Docker stack (e.g., http://10.0.2.2:30000 for Android).

Resource Requirements

Running 34 containers requires significant host resources. A standard M1 Max or a dedicated VPS with 8+ cores and 16GB RAM is recommended.

Category Container Count Estimated RAM
Infrastructure (Postgres, Mongo, etc.) 5 ~1.2 GB
NestJS Subgraphs 19 ~1.6 GB
Rust Subgraphs 4 ~120 MB
Frontend & Portals 3 ~120 MB
Observability & Matrix 3 ~450 MB
Total 34 ~3.5 GB

TIP

Staging Lite: For smaller machines, you can boot only the critical path using make staging-up-lite. This starts the gateway, auth, malets, products, ucart, nodes, frontend, and core databases, consuming only ~2.0 GB of RAM.

Operations & Lifecycle

The staging lifecycle is managed via the root Makefile in ngwenya-federation.

Booting and Monitoring

# Boot the full stack
make staging-up

# Boot the critical path only
make staging-up-lite

# Monitor health and memory usage across all 34 containers
make staging-health

The staging-health command utilizes scripts/staging-healthcheck.sh to poll all services and display a real-time status matrix.

Seeding and Testing

Once booted, you can populate the environment using the Seed Infrastructure:

# Injects 22 vertical archetypes into staging databases
make staging-seed

You can then run the end-to-end (E2E) suites against the staging stack:

# Runs backend Playwright tests against the staging gateway
make staging-test

Configuration and Tuning

Configuration is managed entirely via the .env.staging file (see Environment Variables Reference). Key differences from local dev:

  • NODE_ENV=production and DEV_MODE=false.
  • Uses internal Docker DNS for service discovery (e.g., http://auth:3008/graphql).
  • Connects directly to infrastructure containers (postgres:5432, mongo:27017, redis:6379).