Skip to content

Deployment Documentation

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

Contents

Document Description
staging-deployment-guide.md Complete guide for deploying to staging environment (includes all environment variables)
cosign-setup-guide.md Container image signing with Cosign

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:

  • Droplets - Docker Compose hosting API and Web containers
  • 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:

  1. Build - TypeScript compilation, linting, testing
  2. Docker - Build and push images to registry
  3. Deploy - SSH to droplet, pull images, restart containers
  4. Infrastructure Hardening - Automatic log rotation setup and resource cleanup
  5. Acceptance - Run acceptance tests against staging
  6. Load Test (optional) - K6 performance testing against staging
  7. Production - Deploy to production (pending infrastructure)

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