initial commit

README.md

@@ -0,0 +1,89 @@
+# hantim-server
+
+Server provisioning and app management for the hantim webserver. This repo
+lives at `/opt` on the server and contains Docker Compose configs, deploy
+scripts, and Gitea Actions workflows for each app.
+
+## Repo structure
+
+```
+docker/              # One directory per app, each with a compose.yml
+  nginx/             # Nginx Proxy Manager (reverse proxy + TLS)
+  timothykim.net/    # timothykim.net static site
+scripts/
+  deploy-dispatch.sh # SSH command dispatcher (routes to per-app deploy scripts)
+  deploy-nginx.sh    # Deploy script for nginx
+  deploy-timothykim.sh  # Deploy script for timothykim.net
+  new-app.sh         # Scaffolding script to add a new app
+setup.sh             # One-time server provisioning script
+.gitea/workflows/    # Per-app deploy workflows triggered by path changes
+```
+
+## Initial server setup
+
+On a fresh Rocky Linux 9 (or compatible) install:
+
+```bash
+dnf install -y git git-crypt
+git clone <repo-url> /opt
+git-crypt unlock /path/to/git-crypt-key
+/opt/setup.sh
+```
+
+`setup.sh` installs Docker, creates a `deploy` user, sets up the shared Docker
+network, and starts all services. See the script for the full list of post-setup
+steps (registry login, Nginx Proxy Manager config, etc.).
+
+## How deploys work
+
+Each app has three components:
+
+1. **Deploy script** (`scripts/deploy-<app>.sh`) -- pulls the latest repo
+   changes, then runs `docker compose pull && up -d` for that app.
+2. **Gitea Actions workflow** (`.gitea/workflows/deploy-<app>.yml`) -- triggers
+   on pushes to `main` when files under `docker/<app>/` change. SSHes into the
+   server as the `deploy` user to trigger the deploy.
+3. **SSH dispatcher** (`scripts/deploy-dispatch.sh`) -- the `deploy` user's
+   `authorized_keys` is locked to this script via a `command=` directive. It
+   reads `SSH_ORIGINAL_COMMAND` to route to the correct per-app deploy script.
+
+This means:
+
+- Pushing a change to `docker/nginx/compose.yml` only deploys nginx.
+- Pushing a change to `scripts/` or `setup.sh` does not trigger any deploy.
+- Each app deploys independently.
+
+## Adding a new app
+
+Run the scaffolding script:
+
+```bash
+./scripts/new-app.sh <app-name>
+```
+
+This creates:
+
+- `docker/<app-name>/compose.yml` -- a starter compose file on the `shared`
+  network
+- `scripts/deploy-<app-name>.sh` -- the deploy script
+- `.gitea/workflows/deploy-<app-name>.yml` -- the Gitea Actions workflow
+- A new case in `scripts/deploy-dispatch.sh`
+
+After running the script:
+
+1. Edit `docker/<app-name>/compose.yml` to fit your app (image, ports,
+   volumes, environment variables, etc.).
+2. Commit and push to `main`.
+3. Configure the proxy host in Nginx Proxy Manager to route traffic to the new
+   service.
+
+## Secrets
+
+Nginx Proxy Manager certs and Let's Encrypt account keys are encrypted with
+git-crypt (see `.gitattributes`). You need the git-crypt key to unlock them.
+
+The following secrets must be configured in the Gitea repo settings for
+deploys to work:
+
+- `DEPLOY_HOST` -- the server's IP or hostname
+- `DEPLOY_KEY` -- the SSH private key for the `deploy` user