Update docs/gitea-operations.md

docs/gitea-operations.md

@@ -0,0 +1,89 @@
+# Stevens SmartPark Gitea operations
+
+Status: deployed and checked on 2026-09-29. This document describes the Gitea
+work hub, not a deployed SmartPark parking application. The earlier Two Buttons
+site remains on the same Droplet as a separate exercise.
+
+## Service and architecture
+
+- Public work hub: https://git.137-184-97-250.nip.io/
+- Product repository: https://git.137-184-97-250.nip.io/stevens-smartpark/smartpark-app
+- Host: one DigitalOcean Ubuntu 22.04 Droplet, 1 vCPU, 1 GiB RAM, 25 GiB disk.
+- Gitea image: `docker.gitea.com/gitea:1.27.3`, configured with Docker Compose.
+- Caddy is the public reverse proxy. The Cloud Firewall admits TCP 443 and TCP
+  80 for HTTPS and HTTP-to-HTTPS redirect. SSH/TCP 22 is restricted to the
+  approved administrator IPv4 source. Gitea publishes no host port.
+- Caddy terminates TLS and forwards privately to `gitea:3000` on Docker network
+  `color-net`. Gitea uses SQLite at `/data/gitea/gitea.db`; its `/data` directory
+  is backed by the named volume `gitea-foundation_gitea_data`.
+- The `caddy_data` and `caddy_config` named volumes persist Caddy certificate
+  and configuration state. The live Caddyfile is mounted read-only from the
+  Droplet's `/root/color-buttons-app/Caddyfile`.
+- The current `nip.io` hostname is a temporary address. It is **not** the
+  required GitHub Student Developer Pack domain offer; that requirement remains
+  outstanding for the team manual.
+
+## Start and inspect
+
+Sign in to the Droplet with the administrator's SSH key. Do not share the key,
+passwords, tokens, or the Gitea database in the repository or report.
+
+```bash
+cd /root/gitea-foundation
+docker compose config --quiet
+docker compose up -d
+docker compose ps
+docker logs --tail 50 gitea-foundation-gitea-1
+```
+
+The expected Gitea container status is `Up`; its port listing should contain
+only internal `22/tcp` and `3000/tcp`, without a host address mapping. Git over
+SSH is disabled; HTTPS is the intended public access path. Check the public
+repository URL in a browser and verify that the certificate is trusted.
+
+## Restart and troubleshoot
+
+```bash
+cd /root/gitea-foundation
+docker compose restart gitea
+docker compose ps
+docker logs --tail 100 gitea-foundation-gitea-1
+docker exec color-buttons-caddy wget -S -O /dev/null http://gitea:3000/
+docker exec color-buttons-caddy caddy validate --config /etc/caddy/Caddyfile
+```
+
+If the private `wget` check fails, inspect the Gitea logs, container status,
+and `color-net` membership. If private access works but public HTTPS fails,
+inspect Caddy's status and logs, its Caddyfile, the DNS lookup, and the Cloud
+Firewall rules. Validate the Caddyfile before reloading it. Preserve the named
+volumes when replacing containers; do not use `docker compose down -v` for a
+routine restart or persistence test.
+
+## Verification performed
+
+On 2026-09-29, the team recorded the SmartPark repository and first issue,
+recreated only the Gitea container with
+`docker compose up -d --force-recreate gitea`, and verified that the same
+repository and issue remained available over valid HTTPS afterward. This
+demonstrates container-replacement persistence, **not** backup or restore.
+
+After moving public TCP 80 from the old app container to Caddy, independent
+external checks confirmed that both Gitea and the Two Buttons site redirect
+HTTP to trusted HTTPS pages. Gitea's backend TCP 3000, database TCP 5432, and
+remote Docker management TCP 2375/2376 were unreachable from the test source.
+An SSH connection from the approved administrator source succeeded; a separate
+external check could not reach SSH. Record test source and time in the manual.
+
+The Gitea certificate was issued by Let's Encrypt for the temporary hostname
+and was valid through 2026-12-28 UTC when checked. Caddy manages renewal and
+its `/data` state persists, but a renewal test or dry run still needs to be
+recorded before claiming that rubric item is complete.
+
+## Recovery and records
+
+This deployment has not yet passed a backup-and-restore test. A container
+replacement leaves the data volume in place but cannot recover deleted or
+corrupt volume contents. Keep a separate consistent backup of both the Gitea
+application data and SQLite database, then test restoration in an isolated
+instance before claiming recovery. Maintain dated, sanitized evidence in the
+team manual and update this page after infrastructure changes.