# Tools & Infrastructure

## Deployment Targets

| Environment | Namespace | FQDN |
|-------------|-----------|------|
| Production | `groombook` | `groombook.farh.net` |
| UAT | `groombook-uat` | `groombook.uat.farh.net` |
| Development | `groombook-dev` | `groombook.dev.farh.net` |

## Kubernetes

* Cluster-wide read access is granted; read/write access to `-dev` and `-uat` namespaces.
* `kubectl` is available in the environment; agents operate within the cluster.

## Authentication

* Better-Auth with OAuth2 — no custom authentication, no exceptions.
* Gateway: `istio-external` (namespace `gateway-system`) for externally accessible sites; `istio-internal` for internal-only.
* Authentik is the OIDC/OAuth2 provider (namespace `auth`). UI: `https://auth.farh.net`.
* Authentik credentials available via the `authentik-credentials` secret in your namespace.
* Supported identity providers: Authentik, Auth0, Okta, Entra-ID.

## Secrets

* Bitnami Sealed Secrets Controller (namespace `kube-system`) is the standard — no plain Kubernetes secrets allowed.
* `kubeseal` is available in the environment with access to encrypt via the public key.

## Databases

* CloudNativePG Operator (Postgres) is the standard — no SQLite, MariaDB, or MySQL.

## Cache / Pub-Sub

* DragonflyDB Operator is the standard — no Redis.

## Deployment — 2-Stage Flux GitOps

Deployment is fully GitOps-driven. **Do not use `kubectl apply` to deploy application manifests.**

**Stage 1 — Image build (CI):**
GitHub Actions builds and pushes container images to GHCR (`ghcr.io/groombook/api`, `ghcr.io/groombook/web`) on push/PR. Tag format: `YYYY.MM.DD-shortsha`.

**Stage 2 — Manifest update (GitOps):**
The `groombook/infra` repo holds Kustomize manifests for all environments. To deploy, update image tag(s) in the relevant overlay and commit/merge to `groombook/infra`. Flux (running on the cluster) watches a cluster repo that references `groombook/infra` as a target GitRepository and reconciles automatically.

**Critical rules:**
* `groombook/infra` is a target GitRepository — application manifests only. Do not add `flux-system` resources, do not run `flux bootstrap` against it, do not create GitRepository/Kustomization resources that point to itself.
* To trigger a deployment: update image tags in `groombook/infra` and push/merge a PR.
* Flux owns convergence — do not `kubectl apply` application manifests directly.
* **No Flux Image Automation.** Do not use ImageRepository, ImagePolicy, or ImageUpdateAutomation CRDs. Image tag updates are driven by CI at push time. This is company policy.

## Dependency & Image Updates — Mend Renovate

Mend Renovate is the sole tool for automated dependency and container image updates. Do not configure or use Dependabot.

## Terraform (OpenTofu) — Flux ToFu Controller

* Commit OpenTofu (`.tf`) configuration to `groombook/infra` in a dedicated path. The Flux ToFu Controller watches for `Terraform` CRDs and reconciles automatically.
* Use for: platform-level provisioning (Authentik config, DNS records, object storage buckets). Application manifests remain Kustomize/Helm.
* Do not run `tofu` or `terraform` directly outside the controller workflow.
* Credentials: provide as Sealed Secrets referenced by the `Terraform` resource.