Use local Terraform state; drop unworkable Forgejo HTTP backend (R10b)

Forgejo's /raw/ API is read-only so it cannot serve as a Terraform HTTP state
backend. Switch both envs to local state on the control node (ADR-006); remove
the dead TF_HTTP_* credential hints.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

docs/decisions/006-terraform.md

@@ -44,16 +44,18 @@ Terraform manages its own provider dependencies via `required_providers` and
 
 ## State backend
 
-**Choice**: Forgejo HTTP backend (self-hosted at forgejo.nyumbani.baobab.band)
+**Choice**: Local state on the control node.
 
-Keeps all state on the same self-hosted stack without additional services.
+Forgejo (Gitea-based) has no usable Terraform HTTP state backend — its API `/raw/`
-Authentication uses a Forgejo personal access token via `TF_HTTP_USERNAME` and
+endpoint is read-only, so state cannot be written there. State therefore lives
-`TF_HTTP_PASSWORD` environment variables.
+locally as `terraform.tfstate` (gitignored) on the control node, which is persistent
+and backed up with the rest of the node.
 
-**Note**: The backend URL in `backend.tf` is a placeholder — confirm the exact
+At this scale (solo operator, a handful of VMs) local state is sufficient: no
-endpoint path against your running Forgejo instance's API documentation before
+concurrent applies, so no remote locking is needed. If a remote backend with locking
-running `terraform init`. If Forgejo's HTTP state is unavailable, remove the
+becomes worthwhile later, add a `backend` block to `backend.tf` pointing at a real
-`backend` block from `backend.tf` to fall back to local state on the control node.
+backend such as MinIO/S3 — Forgejo is not an option. See ADR-010 for the Forgejo
+integration boundary.
 
 ---
 

terraform/environments/production/backend.tf

@@ -1,17 +1,9 @@
-terraform {
+# Terraform state: LOCAL, on the control node.
-  backend "http" {
+#
-    # Forgejo HTTP state backend.
+# Forgejo (Gitea-based) has no usable Terraform HTTP state backend — its API
-    # Replace <owner> and <repo> with your Forgejo organisation and repository name.
+# `/raw/` endpoint is read-only, so state cannot be written there. State therefore
-    # Verify the exact path format against your running Forgejo instance's API docs.
+# lives locally as `terraform.tfstate` (gitignored); back it up with the control
-    # Authentication: set TF_HTTP_USERNAME (Forgejo username) and
+# node. See ADR-006.
-    # TF_HTTP_PASSWORD (Forgejo personal access token) as environment variables.
+#
-    #
+# To adopt a real remote backend later (e.g. MinIO/S3), add a
-    # If Forgejo's HTTP state endpoint is unavailable, remove this block entirely
+# `terraform { backend "..." {} }` block here.
-    # to fall back to local state on the control node.
-    address        = "https://forgejo.nyumbani.baobab.band/api/v1/repos/<owner>/<repo>/raw/terraform/state/production.tfstate"
-    lock_address   = "https://forgejo.nyumbani.baobab.band/api/v1/repos/<owner>/<repo>/raw/terraform/state/production.tfstate/lock"
-    unlock_address = "https://forgejo.nyumbani.baobab.band/api/v1/repos/<owner>/<repo>/raw/terraform/state/production.tfstate/lock"
-    lock_method    = "POST"
-    unlock_method  = "DELETE"
-  }
-}

terraform/environments/production/terraform.tfvars.example

@@ -4,9 +4,7 @@
 # Secrets must be exported as environment variables before running Terraform:
 #   export TF_VAR_proxmox_api_token="terraform@pve!tokenid=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
 #
-# Forgejo backend credentials:
+# State is local (see backend.tf) — no Forgejo backend credentials needed.
-#   export TF_HTTP_USERNAME="your-forgejo-username"
-#   export TF_HTTP_PASSWORD="your-forgejo-personal-access-token"
 
 proxmox_endpoint   = "https://pve01.baobab.band:8006/"
 proxmox_insecure   = false

terraform/environments/staging/backend.tf

@@ -1,17 +1,9 @@
-terraform {
+# Terraform state: LOCAL, on the control node.
-  backend "http" {
+#
-    # Forgejo HTTP state backend.
+# Forgejo (Gitea-based) has no usable Terraform HTTP state backend — its API
-    # Replace <owner> and <repo> with your Forgejo organisation and repository name.
+# `/raw/` endpoint is read-only, so state cannot be written there. State therefore
-    # Verify the exact path format against your running Forgejo instance's API docs.
+# lives locally as `terraform.tfstate` (gitignored); back it up with the control
-    # Authentication: set TF_HTTP_USERNAME (Forgejo username) and
+# node. See ADR-006.
-    # TF_HTTP_PASSWORD (Forgejo personal access token) as environment variables.
+#
-    #
+# To adopt a real remote backend later (e.g. MinIO/S3), add a
-    # If Forgejo's HTTP state endpoint is unavailable, remove this block entirely
+# `terraform { backend "..." {} }` block here.
-    # to fall back to local state on the control node.
-    address        = "https://forgejo.nyumbani.baobab.band/api/v1/repos/<owner>/<repo>/raw/terraform/state/staging.tfstate"
-    lock_address   = "https://forgejo.nyumbani.baobab.band/api/v1/repos/<owner>/<repo>/raw/terraform/state/staging.tfstate/lock"
-    unlock_address = "https://forgejo.nyumbani.baobab.band/api/v1/repos/<owner>/<repo>/raw/terraform/state/staging.tfstate/lock"
-    lock_method    = "POST"
-    unlock_method  = "DELETE"
-  }
-}

terraform/environments/staging/terraform.tfvars.example

@@ -4,9 +4,7 @@
 # Secrets must be exported as environment variables before running Terraform:
 #   export TF_VAR_proxmox_api_token="terraform@pve!tokenid=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
 #
-# Forgejo backend credentials:
+# State is local (see backend.tf) — no Forgejo backend credentials needed.
-#   export TF_HTTP_USERNAME="your-forgejo-username"
-#   export TF_HTTP_PASSWORD="your-forgejo-personal-access-token"
 
 proxmox_endpoint   = "https://pve01.baobab.band:8006/"
 proxmox_insecure   = true  # set false once a valid TLS cert is in place