Tomoda DevOps

Production infrastructure and operations for the tomoda platform.

This site is the architectural bible for how tomoda runs in production — the Terraform-managed cloud resources, the Kubernetes manifests Argo CD reconciles, and the operational runbooks the team uses day-to-day.

How to read these docs

• Overview

  Big-picture topology, dev vs prod, multi-cloud split, architectural decisions.

• Infrastructure

  Terraform for GCP (GKE, VPC, OAuth, Cloud Build, Artifact Registry, GCS) and AWS (S3, CloudFront, ACM, IAM). Cloudflare DNS.

• Kubernetes

  Argo CD GitOps. Apps (tomoda, photon, photon-indexer), middleware (Postgres, Redis, pgAdmin, Redis Insight), system services (Traefik, cert-manager, External-DNS, External Secrets, oauth2-proxy, Monitoring, Loki).

• Operations

  Day-to-day cookbook: deploy, rollback, scale, debug, disaster recovery, Postgres operations, Photon rollout, access control.

• Security

  Secrets management, IAM, network policies, TLS.

• Reference

  Glossary, script catalog, dev-vs-prod environments matrix.

Quick links

• New to the stack? → Architecture overview
• Need to deploy a fix? → Deploy runbook
• Production is on fire? → Debugging and Disaster recovery
• Adding a new secret? → Secrets management
• Working in the tomoda app repo? → app-side docs live at tomoda/docs/

Editing these docs

The docs source lives in this repo's docs/ directory. Serve locally with hot reload:

task docs:install   # one-time
task docs           # http://localhost:8000

Strict-build check before committing:

task docs:build     # mkdocs build --strict

The same docs are also federated into the tomoda repo's combined docs site via mkdocs-monorepo-plugin — when you run task docs from inside the tomoda repo, you get both sites stitched together.

When in doubt about what to update: see this project's CLAUDE.md under "Updating docs as you change infra".