diff --git a/SMARTPARK_GITEA_OPERATIONS.md b/SMARTPARK_GITEA_OPERATIONS.md new file mode 100644 index 0000000..cbddfee --- /dev/null +++ b/SMARTPARK_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.