From 6ccfc1c50616524c180cc4560c4d03baabe816a3 Mon Sep 17 00:00:00 2001
From: Adam Moussa <166072409+amoussa1229@users.noreply.github.com>
Date: Mon, 11 May 2026 19:03:42 -0400
Subject: [PATCH] Update README with backup, autodiscovery, and token
 management docs (#1)

Add documentation for S3 backups with Glacier lifecycle, hourly
autodiscovery of new GitHub org repos, daily PAT token refresh,
PAT rotation procedure, and Secrets Manager secret inventory.
---
 README.md | 70 +++++++++++++++++++++++++++++++++++++++++++++++++++----
 1 file changed, 65 insertions(+), 5 deletions(-)

diff --git a/README.md b/README.md
index a4dfb9e..0e82e68 100644
--- a/README.md
+++ b/README.md
@@ -4,12 +4,13 @@ Self-hosted Forgejo git server for archiving GitHub repos and mirroring active o
 
 ## Architecture
 
-- **EC2**: t4g.small (arm64), Amazon Linux 2023, 50GB gp3 EBS
+- **EC2**: t4g.small (arm64), Amazon Linux 2023, 50GB gp3 EBS — instance `i-0d3005fb3c36124cd`
 - **Network**: Private subnet (us-east-1a), behind `seahaven-com` ALB for SSL termination
-- **DNS**: `forgejo.seahaven.com` (Route53 alias → ALB)
+- **DNS**: `forgejo.seahaven.com` — Route53 alias record pointing to the `seahaven-com` ALB (not a direct A record)
 - **TLS**: Wildcard cert on ALB, HTTP internally on port 3000
-- **Backup**: Nightly EBS snapshots via DLM, 7-day retention
+- **Backup**: Nightly `forgejo dump` to S3 + EBS snapshots via DLM (see [S3 Backups](#s3-backups))
 - **Admin access**: SSM Session Manager (no SSH port exposed)
+- **CI/CD**: GitHub Actions with OIDC role `githubdeploy-forgejo`
 
 ### Ports
 
@@ -19,12 +20,71 @@ Self-hosted Forgejo git server for archiving GitHub repos and mirroring active o
 | 3000 | HTTP | ALB → instance | Internal traffic from ALB |
 | 2222 | SSH | VPC + VPN | Git SSH operations |
 
+## S3 Backups
+
+A nightly `forgejo dump` runs at 5:00 UTC and uploads the archive to `s3://forgejo-backups-328440206208`.
+
+**S3 lifecycle policy:**
+
+| Phase | Duration |
+|-------|----------|
+| Standard | First 30 days |
+| Glacier | Days 31–365 |
+| Expired | After 365 days |
+
+EBS snapshots are managed separately by DLM and run nightly at 6:00 UTC with a 7-day retention window.
+
+To test the backup manually:
+
+```bash
+sudo /usr/local/bin/forgejo-backup.sh
+```
+
+## Autodiscovery
+
+An hourly cron job checks the `Sea-Haven-Industries` GitHub org for new repositories and mirrors them into Forgejo automatically.
+
+- **Active repos** are created as mirrors (ongoing sync).
+- **Archived repos** are created as static one-time imports.
+- **Script**: `/usr/local/bin/forgejo-autodiscover.sh`
+- **Log**: `/var/log/forgejo-autodiscover.log`
+
+## Token Refresh
+
+A daily cron at 4:30 UTC reads the GitHub PAT from Secrets Manager (`forgejo/github-pat`) and updates the git remote URL on every mirror repository so credentials stay current.
+
+- **Script**: `/usr/local/bin/forgejo-refresh-tokens.sh`
+
+## PAT Rotation
+
+The GitHub personal access token used for mirroring is a fine-grained PAT scoped to `Sea-Haven-Industries` with **Contents: Read-only** permissions and a 1-year expiration. It is stored in Secrets Manager at `forgejo/github-pat`.
+
+To rotate:
+
+1. Create a new fine-grained PAT on GitHub with the same scope.
+2. Update the secret value in Secrets Manager (`forgejo/github-pat`).
+3. The daily token-refresh cron will pick it up automatically.
+
+To force immediate propagation:
+
+```bash
+sudo /usr/local/bin/forgejo-refresh-tokens.sh
+```
+
+## Secrets Manager
+
+| Secret | Purpose |
+|--------|---------|
+| `forgejo/admin-password` | Forgejo admin user password |
+| `forgejo/api-token` | Forgejo API token (used by autodiscovery and token refresh scripts) |
+| `forgejo/github-pat` | GitHub fine-grained PAT for mirroring |
+
 ## First-time setup
 
 After the stack deploys, connect via SSM and create the admin user:
 
 ```bash
-aws ssm start-session --target <instance-id>
+aws ssm start-session --target i-0d3005fb3c36124cd
 
 sudo -u forgejo /usr/local/bin/forgejo admin user create \
   --admin \
@@ -62,7 +122,7 @@ CI/CD is handled by GitHub Actions — PRs run CI, merges to `main` deploy via t
 Update the `FORGEJO_VERSION` constant in `lib/forgejo-stack.ts` and deploy. This replaces the instance, so ensure the latest EBS snapshot is available for data recovery if needed. Alternatively, update in-place via SSM:
 
 ```bash
-aws ssm start-session --target <instance-id>
+aws ssm start-session --target i-0d3005fb3c36124cd
 
 sudo systemctl stop forgejo
 sudo curl -Lo /usr/local/bin/forgejo "https://codeberg.org/forgejo/forgejo/releases/download/v<NEW_VERSION>/forgejo-<NEW_VERSION>-linux-arm64"