# Use Cases

Expected behaviors for each operation this repo supports. See README.md for
instructions, ARCHITECTURE.md for technical details.

## 0. Initial Bitwarden Secrets Manager setup

**Trigger:** one-time, before anything else works.

**Expected outcome:**
- Bitwarden organization with Secrets Manager enabled
- Project `hantim` with all secrets listed in README.md
- Machine accounts `hantim-server` and `hantim-ci` with project access
- Access tokens generated for each machine account

## 1. Provision a new server

**Trigger:** run `bootstrap.sh` on a fresh Rocky Linux 9 install.

**Prerequisites:** DNS pointed to server, bws access token ready.

**Expected outcome:**
- All dependencies installed (Docker, certbot, bws, etc.)
- `deploy` user exists with restricted SSH and sudo
- Firewall allows HTTP, HTTPS, Garage RPC
- Certbot renewal configured
- All services running (nginx, apps, Garage)
- SSL certs issued for all configured domains
- `.env` files generated from bws for services with `.env.keys`

## 2. Restore from backup

**Trigger:** same three commands as provisioning on a fresh server.

**Expected outcome:** identical to provisioning. All scripts are idempotent.
Certs are re-issued, images pulled from registry. No data migration needed
for stateless static sites.

## 3. Add a new static site

**Trigger:** `./tools/app.sh all example.com` from dev machine.

**Prerequisites:** domain nameservers on Vultr, `bws`/`jq`/`dig` installed.

**Expected outcome:**
- DNS A records created for bare + www
- Gitea repo `hantim/example.com` created from template
- Config files added: compose, nginx conf, deploy workflow
- SSL cert issued (zero downtime)
- Garage media bucket created with media-key access
- First build triggered
- `https://www.example.com` responds within 3 minutes
- Site ready for customization via git clone + push

## 4. Update app code

**Trigger:** push to an app repo.

**Expected outcome:**
- Docker image built and pushed to registry
- Container restarted on server with new image
- No manual steps

## 5. Update Docker Compose config

**Trigger:** push compose file change to this repo.

**Expected outcome:**
- Path-matched workflow triggers
- Container restarted with updated config

## 6. Update nginx config

**Trigger:** push nginx conf change to this repo.

**Expected outcome:**
- Config tested with `nginx -t` before applying
- If test fails, running nginx is untouched
- If new certs needed, issued before applying config
- nginx reloaded with new config

## 7. Re-run configure

**Trigger:** push change to `scripts/configure.sh`, or run manually.

**Expected outcome:**
- All steps idempotent — safe to run anytime
- Existing certs skipped
- Services restarted

## 8. Upload media files

**Trigger:** `aws s3 cp` or `aws s3 sync` to `s3://example.com/`.

**Expected outcome:**
- File uploaded via S3 API (`s3.hantim.net`)
- Replicated to both Garage nodes (hantim + argento)
- Accessible at `https://www.example.com/media/<path>`
- Local development: `static/media/` (gitignored) serves at `/media/`