Skip to content

Deployment Documentation

This folder contains deployment and operations guides for Forma3D.Connect.

Contents

Document Description
pipeline-reference.md Technical reference for the Azure DevOps pipeline (stages, caching, signing, diagrams)
self-hosted-build-agent.md Self-hosted DO build agent setup, maintenance, and hybrid strategy
staging-deployment-guide.md Complete guide for deploying to staging environment (includes all environment variables)
cosign-setup-guide.md Container image signing with Cosign
operational-tooling.md Overview of all operator/developer tools (Uptime Kuma, Dozzle, pgAdmin, Grafana, Zensical, EventCatalog)

Configuration Reference

All environment variables are documented in the staging-deployment-guide.md, including:

  • Core variables: Database, Shopify, SimplyPrint, Sendcloud
  • Operational configuration (Phase 5k): Retry queue settings, API timeouts, webhook idempotency

Infrastructure Overview

Forma3D.Connect is deployed on DigitalOcean:

  • Staging Droplet - Docker Compose hosting microservices (Gateway, Order, Print, Shipping, GridFlock, Slicer, Web, Docs)
  • Build Agent Droplet - Self-hosted Azure DevOps build agent (4 vCPU / 8 GB) for Docker builds
  • Container Registry - DigitalOcean Container Registry for Docker images
  • Managed PostgreSQL - Database with TLS encryption
  • Traefik - Reverse proxy with automatic Let's Encrypt TLS

CI/CD Pipeline

The project uses Azure DevOps Pipelines with a hybrid agent strategy (MS-hosted + self-hosted DigitalOcean agents). See ADR-057.

  1. Validate & Test - Lint, type check, and unit tests (3 agents in parallel)
  2. Build & Package - Detect affected, compile, Docker image builds on self-hosted agents
  3. Deploy Staging - SSH to droplet, pull images, run migrations, restart containers
  4. Acceptance Test - Playwright tests against staging
  5. Load Test (optional) - K6 performance testing against staging
  6. Deploy Production - Deploy to production with manual approval gate
  7. Smoke Test - Verify production health

Automatic Infrastructure Hardening

The deployment pipeline automatically ensures infrastructure health:

Feature Description
Docker Log Rotation Configures daemon.json with max-size: 10m and max-file: 3 per container
Resource Cleanup Prunes unused images, volumes, and networks after each deployment
Separate Image Tags API and Web use independent API_IMAGE_TAG and WEB_IMAGE_TAG variables

This prevents disk exhaustion from unbounded log growth and accumulated Docker images.

See ADR-034: Docker Infrastructure Hardening for details.

Pipeline Parameters

Parameter Default Description
runLoadTests false Enable K6 load tests against staging
loadTestBaselineMode false Collect data without failing on thresholds
breakingMigration false Stop API before running migrations
enableSigning true Enable cosign image signing and attestations

Load Testing in Pipeline

To run load tests as part of the deployment:

  1. Navigate to Pipelines in Azure DevOps
  2. Click Run pipeline
  3. Check "Run Load Tests (optional)"
  4. (Optional) Check "Load Test Baseline Mode" for data collection without threshold enforcement
  5. Click Run

Load test results are published as pipeline artifacts including HTML reports.

Staging URLs

  • API: https://staging-connect-api.forma3d.be
  • Web: https://staging-connect.forma3d.be
  • API Docs: https://staging-connect-api.forma3d.be/api/docs

Monitoring Configuration

Alerting rules for production monitoring are defined in:

  • deployment/monitoring/alerting-rules.yml - Alert definitions for errors, latency, and infrastructure

See the runbook for operational procedures and incident response.

Document Description
Architecture Infrastructure diagrams
Development Development workflow
Runbook Operations runbook
Troubleshooting Common issues and resolutions