Skip to content

Deployment Documentation

This directory contains operational documentation for deploying SyRF services using GitOps with ArgoCD.

Documentation Philosophy

"Documentation lives where the action happens."

This repo contains documentation for deployment operations - tasks that involve updating Helm values, promoting services between environments, and managing ArgoCD applications in the cluster-gitops repository.

What's Documented Here

Deployment Operations

  • Service Deployment: How to deploy and update SyRF services
  • Promotion Workflow: How to promote services from staging to production
  • Environment Management: Managing staging and production configurations
  • ArgoCD Operations: Working with ArgoCD Applications and ApplicationSets
  • Troubleshooting: Common deployment issues and solutions

NOT Documented Here

Documentation Index

Guides

Troubleshooting

Multi-Repository Documentation Strategy

The SyRF platform spans three repositories:

Repository Purpose Documentation
syrf Application code syrf/docs/
cluster-gitops Deployment config cluster-gitops/docs/ ← You are here
camarades-infrastructure Infrastructure IaC camarades-infrastructure/docs/

Architecture & Decisions: - ADR-003: Cluster Architecture - GitOps Architecture - System Architecture

Infrastructure Operations: - Terraform Guide - Cluster Configuration - Cost Optimization

Application Code: - API Service - Web Service - Project Management Service

Documentation Decision Flow

Question: "Where do I document deployment changes?"

Is it about...
├─ How to deploy applications or update image tags?
│  └─ cluster-gitops/docs/ (this repo)
├─ Terraform usage, state management, infrastructure procedures?
│  └─ camarades-infrastructure/docs/
├─ GKE cluster design decisions or architecture?
│  └─ syrf/docs/decisions/ (ADRs in main repo)
└─ Application code or service-specific configuration?
   └─ syrf/src/services/{service}/README.md

Repository Structure

cluster-gitops/
├── apps/                       # ArgoCD Application manifests (multi-source)
│   ├── api.yaml               # API service ArgoCD app
│   ├── web.yaml               # Web service ArgoCD app
│   ├── project-management.yaml # PM service ArgoCD app
│   ├── quartz.yaml            # Quartz service ArgoCD app
│   ├── docs.yaml              # Team docs ArgoCD app
│   ├── user-guide.yaml        # User guide ArgoCD app
│   ├── project-staging.yaml   # AppProject for staging
│   ├── project-production.yaml # AppProject for production
│   └── preview-applicationset.yaml # PR preview generator
├── environments/              # Environment-specific values
│   ├── staging/
│   │   ├── api.values.yaml
│   │   ├── web.values.yaml
│   │   ├── project-management.values.yaml
│   │   ├── quartz.values.yaml
│   │   ├── docs.values.yaml
│   │   └── user-guide.values.yaml
│   ├── production/
│   │   ├── api.values.yaml
│   │   ├── web.values.yaml
│   │   ├── project-management.values.yaml
│   │   ├── quartz.values.yaml
│   │   ├── docs.values.yaml
│   │   └── user-guide.values.yaml
│   └── preview/
│       └── common.values.yaml
└── docs/                      # Deployment operations documentation
    ├── README.md             # This file
    ├── deploying-services.md
    └── promotion-workflow.md

Note: Helm charts are in syrf-monorepo at src/services/{service}/charts/
Applications use multi-source pattern (chart from monorepo + values from here)

Contributing

To add or update deployment documentation:

  1. Create or update markdown files in this directory
  2. Follow the naming convention: kebab-case.md
  3. Include clear headings and examples
  4. Link to related documentation in other repos using full GitHub URLs
  5. Update this README's index when adding new docs

Unified Documentation Site

All documentation from across the three repositories is aggregated into a single MkDocs site published at docs.syrf.org.uk. Changes to this directory automatically appear in the "GitOps Operations" section of that site.