# Use Cases

## 1. Provision a new server

Set up a fresh Rocky Linux 9 server from scratch.

```bash
dnf install -y git
git clone https://git.timothykim.net/hantim/hantim-server.git /opt/hantim
bash /opt/hantim/setup.sh
```

**What happens:**
- Installs all dependencies (git-crypt, jq, certbot, Node.js 20, Docker, bw CLI)
- Fetches secrets from Bitwarden (git-crypt key, registry token, deploy SSH key)
- Unlocks git-crypt, logs into Docker registry
- Creates deploy user with restricted SSH + sudo
- Issues SSL certs for all domains in `docker/nginx/conf.d/`
- Starts nginx and all app containers

**Prerequisites:**
- DNS for all configured domains must point to the server
- Bitwarden vault must contain: `hantim-git-crypt-key`, `hantim-ci-registry-push`,
  `hantim-server-deploy`
- Docker images must exist in the Gitea registry (or apps will start on next push)

## 2. Restore from backup

Identical to provisioning a new server. Run the same three commands on a
fresh server.

- `setup.sh` is idempotent -- safe to re-run
- SSL certs are re-issued automatically (Let's Encrypt)
- Docker images are pulled from the Gitea registry
- No data migration needed for stateless static sites

## 3. Add a new static site

From your dev machine:

```bash
./scripts/new-app.sh hcsuzuki.net
```

Then on the server, issue the SSL cert **before** pushing:

```bash
docker stop nginx
certbot certonly --standalone --non-interactive --agree-tos \
  --register-unsafely-without-email --cert-name hcsuzuki.net \
  -d hcsuzuki.net -d www.hcsuzuki.net
docker start nginx
```

Then commit and push this repo:

```bash
git add docker/hcsuzuki.net/ .gitea/workflows/deploy-hcsuzuki.net.yml docker/nginx/conf.d/hcsuzuki.net.conf
git commit -m "add hcsuzuki.net"
git push
```

Finally, clone the new app repo, customize it, and push:

```bash
git clone git@git.timothykim.net:hantim/hcsuzuki.net.git
cd hcsuzuki.net
# edit static/index.html, etc.
git add . && git commit -m "initial content" && git push
```

**What the script creates:**
- Gitea repo `hantim/hcsuzuki.net` (from `static-site-template`)
- `docker/hcsuzuki.net/compose.yml` (container name: `hcsuzuki_net`)
- `.gitea/workflows/deploy-hcsuzuki.net.yml`
- `docker/nginx/conf.d/hcsuzuki.net.conf` (HTTP->HTTPS, bare->www, proxy)

## 4. Update app code

Push a change to the app repo (e.g., `timothykim.net`):

```bash
cd timothykim.net
# make changes
git add . && git commit -m "update content" && git push
```

**What happens:**
1. Gitea Actions runs `build.yml`: builds Docker image, pushes to registry
2. SSHes into server, runs `deploy-timothykim.net`
3. `deploy.sh` pulls latest hantim-server, pulls new image, restarts container

No manual steps needed.

## 5. Update Docker Compose config

Edit a compose file in this repo and push:

```bash
vim docker/timothykim.net/compose.yml
git add docker/timothykim.net/compose.yml
git commit -m "update timothykim.net config"
git push
```

**What happens:**
1. `deploy-timothykim.yml` workflow triggers (path match)
2. `deploy.sh` pulls latest code, pulls image, runs `docker compose up -d`

## 6. Update nginx config

Edit an nginx config in this repo and push:

```bash
vim docker/nginx/conf.d/timothykim.net.conf
git add docker/nginx/conf.d/timothykim.net.conf
git commit -m "update nginx config"
git push
```

**What happens:**
1. `deploy-nginx.yml` workflow triggers (path match)
2. `deploy.sh` pulls latest code
3. Tests nginx config with `nginx -t` -- if it fails, deploy aborts and the
   running nginx is untouched
4. Runs `docker compose up -d` and reloads nginx

## 7. Re-run setup on existing server

Safe to do at any time:

```bash
cd /opt/hantim
git pull
bash setup.sh
```

- All steps are idempotent
- Existing certs are skipped
- Brief nginx downtime (seconds) while certbot checks run
- Services are restarted