issue-1-gitea-operations

Document Gitea deployment and operations for issue #1
2026-09-29 21:06:51 +00:00
parent 4e2f943de7
commit 9b72a1761d
1 changed files with 89 additions and 0 deletions
@@ -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.