restructure docs: eliminate duplication across md files
This commit is contained in:
+129
-100
@@ -1,99 +1,38 @@
|
||||
# Architecture
|
||||
|
||||
Technical details for the hantim infrastructure. See README.md for usage
|
||||
instructions, USECASES.md for expected behaviors.
|
||||
|
||||
## Servers
|
||||
|
||||
### Hantim server (hantim)
|
||||
### Hantim (Vultr, Rocky Linux 9)
|
||||
|
||||
The production application server. Runs Rocky Linux 9 on Vultr.
|
||||
Production web server. This repo is cloned to `/opt/hantim`.
|
||||
|
||||
- Hosts all app containers and the nginx reverse proxy via Docker Compose
|
||||
- Provisioned by `bootstrap.sh` + `configure.sh` in this repo
|
||||
- This repo is cloned to `/opt/hantim`
|
||||
- The `deploy` user receives SSH commands from CI to trigger deploys
|
||||
- Runs nginx reverse proxy + all app containers via Docker Compose
|
||||
- Certbot runs on the host (not in Docker) and manages Let's Encrypt certs
|
||||
- The `deploy` user receives SSH commands from CI to trigger deploys
|
||||
- Garage storage node for media replication
|
||||
|
||||
### Gitea server (git.timothykim.net)
|
||||
### Argento (home server)
|
||||
|
||||
A separate server running the Gitea instance. Provides:
|
||||
|
||||
- Git hosting for all repos
|
||||
- Gitea instance at `git.timothykim.net`
|
||||
- Docker container registry (`git.timothykim.net/hantim/<app>`)
|
||||
- Gitea Actions CI/CD (runner registered at site level)
|
||||
- Organization-level secrets and variables shared across repos
|
||||
- Gitea Actions CI runner (registered at site level)
|
||||
- Second Garage storage node (replication partner)
|
||||
- Garage web UI for administration
|
||||
|
||||
### Bitwarden Secrets Manager (cloud)
|
||||
|
||||
Secrets are stored in Bitwarden Secrets Manager (free tier, project: `hantim`).
|
||||
The `bws` CLI fetches secrets using machine account access tokens.
|
||||
|
||||
- `hantim-ci-registry-push` -- Gitea API token for registry access
|
||||
- `hantim-deploy-ssh-private-key` -- deploy user SSH private key
|
||||
- `hantim-deploy-ssh-public-key` -- deploy user SSH public key
|
||||
- `hantim-new-app-script` -- Gitea API token for creating repos
|
||||
- `hantim-vultr-api-key` -- Vultr API key for DNS management
|
||||
- `hantim-garage-rpc-secret` -- Garage cluster RPC secret
|
||||
- `hantim-garage-argento-node-id` -- Argento's Garage node ID + address
|
||||
- `hantim-garage-admin-token` -- Garage admin API token
|
||||
- `hantim-garage-media-key-id` -- S3 access key ID for media uploads
|
||||
- `hantim-garage-media-secret-key` -- S3 secret key for media uploads
|
||||
All secrets stored in project `hantim`, fetched via `bws` CLI.
|
||||
|
||||
Machine accounts:
|
||||
- `hantim-server` -- used by `bootstrap.sh` and `configure.sh` on the server
|
||||
(access token at `/etc/bws-token`)
|
||||
- `hantim-ci` -- reserved for future CI use
|
||||
- `hantim-server` — used by `bootstrap.sh` and `configure.sh` (token at `/etc/bws-token`)
|
||||
- `hantim-ci` — reserved for future CI use
|
||||
|
||||
### Gitea secrets
|
||||
|
||||
Workflow secrets stored in the `hantim` Gitea org. These duplicate some
|
||||
Bitwarden secrets for direct use in CI workflows without installing `bws`:
|
||||
|
||||
- `DEPLOY_SSH_KEY` -- deploy SSH private key
|
||||
- `CI_REGISTRY_TOKEN` -- Gitea registry token
|
||||
- `DEPLOY_HOST` -- server IP (variable, not secret)
|
||||
|
||||
## Repos
|
||||
|
||||
All repos live under the `hantim` organization on Gitea.
|
||||
|
||||
### hantim-server
|
||||
|
||||
This repo. Contains server provisioning, Docker Compose configs, nginx
|
||||
configs, deploy scripts, and Gitea Actions workflows.
|
||||
|
||||
```
|
||||
scripts/bootstrap.sh # First-time server setup (manual, uses Bitwarden)
|
||||
scripts/configure.sh # Idempotent server config (CI-safe)
|
||||
scripts/deploy.sh # Receives deploy + cert + provision commands via SSH
|
||||
tools/new-app.sh # Scaffolds + deploys a new static site (run from dev machine)
|
||||
tools/new-service.sh # Scaffolds a new Docker Compose service (run from dev machine)
|
||||
tools/remove-app.sh # Removes a static site (run from dev machine)
|
||||
docker/nginx/ # nginx reverse proxy
|
||||
compose.yml # nginx:alpine container
|
||||
nginx.conf # Main nginx config
|
||||
conf.d/<domain>.conf # Per-app server blocks
|
||||
docker/<domain>/compose.yml # Per-app compose files
|
||||
docker/garage/ # Garage S3-compatible object storage
|
||||
compose.yml
|
||||
Dockerfile
|
||||
garage.toml
|
||||
.env.keys
|
||||
.gitea/workflows/deploy-<app>.yml # Per-app deploy workflows
|
||||
.gitea/workflows/provision.yml # Triggers configure.sh on setup changes
|
||||
```
|
||||
|
||||
### static-site-template
|
||||
|
||||
A Gitea template repo used by `new-app.sh` to scaffold new static sites.
|
||||
Contains a Dockerfile, nginx config, placeholder HTML, and a `build.yml`
|
||||
workflow that builds/pushes a Docker image and triggers a deploy.
|
||||
|
||||
Uses Gitea template variables (`${REPO_NAME}`) so the image tag and deploy
|
||||
command are automatically set to the repo name.
|
||||
|
||||
### App repos (e.g., example.com)
|
||||
|
||||
Each app is its own repo created from `static-site-template`. Contains the
|
||||
app source code and a `build.yml` workflow.
|
||||
Gitea org-level secrets (`hantim`) duplicate some bws secrets for direct
|
||||
CI use without installing `bws`: `DEPLOY_SSH_KEY`, `CI_REGISTRY_TOKEN`,
|
||||
`DEPLOY_HOST` (variable).
|
||||
|
||||
## Network topology
|
||||
|
||||
@@ -103,16 +42,16 @@ app source code and a `build.yml` workflow.
|
||||
[Hantim Server]
|
||||
|
|
||||
nginx (port 80/443)
|
||||
| |
|
||||
example_com example_org ...
|
||||
(shared Docker network)
|
||||
/ | | \
|
||||
example_com app_two garage ...
|
||||
(shared Docker network)
|
||||
```
|
||||
|
||||
- nginx is the only container with host port bindings (80, 443)
|
||||
- All app containers are on the `shared` Docker network
|
||||
- nginx proxies `https://www.<domain>` to the app's container by name
|
||||
- nginx proxies `https://www.<domain>` to the app container by name
|
||||
- The `shared` network is created by the nginx compose file and referenced
|
||||
as `external: true` by app compose files
|
||||
as `external: true` by all other compose files
|
||||
|
||||
## Deploy flow
|
||||
|
||||
@@ -120,21 +59,20 @@ app source code and a `build.yml` workflow.
|
||||
|
||||
```
|
||||
Developer pushes to app repo (e.g., example.com)
|
||||
-> build.yml workflow runs on Gitea runner
|
||||
-> docker build + push to git.timothykim.net registry
|
||||
-> build.yml runs on Gitea runner
|
||||
-> docker build + push to registry
|
||||
-> SSH to deploy@hantim as deploy-<domain>
|
||||
-> deploy.sh: git pull, docker compose pull, docker compose up -d
|
||||
-> (if image not yet in registry, skips gracefully)
|
||||
```
|
||||
|
||||
### Infrastructure change (push to hantim-server)
|
||||
|
||||
```
|
||||
Developer pushes to hantim-server
|
||||
-> deploy-<app>.yml triggers (based on changed paths under docker/<app>/)
|
||||
-> deploy-<app>.yml triggers (path match on docker/<app>/)
|
||||
-> SSH to deploy@hantim as deploy-<app>
|
||||
-> deploy.sh: git pull, docker compose pull, docker compose up -d
|
||||
-> (nginx only): auto-issues certs for new domains, then tests config with nginx -t
|
||||
-> nginx: auto-issues certs for new domains, tests config with nginx -t
|
||||
```
|
||||
|
||||
### Setup change (push to hantim-server)
|
||||
@@ -143,18 +81,109 @@ Developer pushes to hantim-server
|
||||
Developer pushes change to scripts/configure.sh
|
||||
-> provision.yml triggers
|
||||
-> SSH to deploy@hantim as provision
|
||||
-> deploy.sh: git pull, configure.sh (firewall, certbot, start services)
|
||||
-> deploy.sh: git pull, runs configure.sh
|
||||
```
|
||||
|
||||
## Conventions
|
||||
## SSH deploy protocol
|
||||
|
||||
The `deploy` user's `authorized_keys` uses `command=` restrictions. The SSH
|
||||
client sends a command string (e.g., `deploy-example.com`), and `deploy.sh`
|
||||
parses it to determine the action:
|
||||
|
||||
- `deploy-<app>` — deploy a specific app
|
||||
- `deploy-nginx` — deploy nginx (with cert handling)
|
||||
- `cert-<domain>` — issue a cert only
|
||||
- `provision` — run `configure.sh`
|
||||
|
||||
## SSL certificate handling
|
||||
|
||||
Cert names are derived from nginx conf filenames (e.g., `example.com.conf` →
|
||||
cert `example.com`). All `server_name` values in the conf are included in the
|
||||
cert as SANs.
|
||||
|
||||
**New domain (nginx not yet running):**
|
||||
1. `deploy.sh` detects missing cert files
|
||||
2. Stops nginx temporarily
|
||||
3. Issues cert via `certbot --standalone`
|
||||
4. Starts nginx
|
||||
5. On error, cleans up the temp conf file (trap)
|
||||
|
||||
**New domain (nginx already running):**
|
||||
1. Issues cert via `certbot --webroot` using the ACME challenge directory
|
||||
2. Zero downtime
|
||||
|
||||
**Renewal:** certbot timer/cron runs daily, deploy hook reloads nginx.
|
||||
|
||||
## `.env.keys` mechanism
|
||||
|
||||
Services needing secrets declare them in `.env.keys`:
|
||||
|
||||
```
|
||||
ENV_VAR=bws-secret-name
|
||||
```
|
||||
|
||||
During deploy, `deploy.sh`:
|
||||
1. Reads each line from `.env.keys`
|
||||
2. Fetches the secret value from bws: `bws secret get <uuid> --access-token ...`
|
||||
3. Writes `ENV_VAR=value` to `.env`
|
||||
4. Docker Compose reads `.env` on startup
|
||||
|
||||
If any secret is missing, deploy fails with an error (not a warning).
|
||||
|
||||
## Naming conventions
|
||||
|
||||
- **App name = domain** (e.g., `example.com`)
|
||||
- **Container name** = domain with dots replaced by underscores (e.g.,
|
||||
`example_com`)
|
||||
- **Cert name** = config filename without `.conf` (stored at `/etc/letsencrypt/live/<name>/`)
|
||||
- **One domain per conf file** -- `deploy.sh` derives the cert name from the conf
|
||||
filename and collects all `server_name` values for that cert. Putting unrelated
|
||||
domains in the same conf file will bundle them into one cert incorrectly.
|
||||
- **Container name** = domain with dots → underscores (e.g., `example_com`)
|
||||
- **Image name** = `git.timothykim.net/hantim/<domain>:latest`
|
||||
- All HTTP traffic redirects to `https://www.<domain>`
|
||||
- Bare domain HTTPS redirects to `https://www.<domain>`
|
||||
- **Cert name** = nginx conf filename without `.conf`
|
||||
- **One domain per conf file** — `deploy.sh` derives the cert name from the
|
||||
filename and collects all `server_name` values for that cert
|
||||
|
||||
## URL routing
|
||||
|
||||
- All HTTP → HTTPS redirect
|
||||
- Bare domain HTTPS → `https://www.<domain>` redirect
|
||||
- Each domain gets its own conf file (even redirect-only domains)
|
||||
|
||||
## Garage (S3-compatible storage)
|
||||
|
||||
Two-node cluster: hantim + argento, `replication_factor = 2`.
|
||||
|
||||
**Components:**
|
||||
- Garage v2.2.0 (`dxflrs/garage:v2.2.0`)
|
||||
- Port 3900: S3 API (proxied via `s3.hantim.net`)
|
||||
- Port 3901: RPC (inter-node, firewall opened)
|
||||
- Port 3902: Web endpoint (serves files via `Host: <bucket>.web.garage`)
|
||||
- Port 3903: Admin API (proxied via `garage.hantim.net`)
|
||||
|
||||
**Media serving path:**
|
||||
```
|
||||
Client -> nginx (443) -> /media/ location -> garage:3902
|
||||
(proxy_set_header Host <domain>.web.garage)
|
||||
```
|
||||
|
||||
**Config generation:** `garage.toml` uses `envsubst` placeholders (`${RPC_SECRET}`,
|
||||
`${ARGENTO_NODE_ID}`, `${ADMIN_TOKEN}`). The Dockerfile copies the template and
|
||||
runs envsubst at container start. Values come from `.env` generated by the
|
||||
`.env.keys` mechanism.
|
||||
|
||||
**Bucket setup** (done by `new-app.sh` via admin API v2):
|
||||
1. `POST /v2/CreateBucket` with `globalAlias: <domain>`
|
||||
2. `POST /v2/AllowBucketKey` to grant media-key read/write access
|
||||
3. `POST /v2/UpdateBucket` to enable website access
|
||||
|
||||
## App repos
|
||||
|
||||
Every site repo follows the same pattern (created from `static-site-template`):
|
||||
|
||||
```
|
||||
Dockerfile # Copies static/ into nginx:alpine, applies nginx.conf
|
||||
nginx.conf # Per-app HTTP config (port 80, routing, cache headers)
|
||||
static/ # HTML/CSS/JS content
|
||||
static/media/ # Local media files (gitignored)
|
||||
.gitea/workflows/build.yml # Build image, push to registry, SSH deploy
|
||||
```
|
||||
|
||||
The template uses Gitea template variables (`${REPO_NAME}`) so the image tag
|
||||
and deploy command match the repo name automatically. Workflow files must
|
||||
escape `$$` to prevent template variable consumption.
|
||||
|
||||
@@ -1,93 +1,44 @@
|
||||
# CLAUDE.md
|
||||
|
||||
## Project overview
|
||||
|
||||
Server provisioning and app management for the hantim webserver. This repo
|
||||
lives at `/opt/hantim` on the production server (Rocky Linux 9 on Vultr) and
|
||||
manages Docker Compose configs, deploy scripts, nginx configs, and Gitea
|
||||
Actions workflows.
|
||||
Quick context for Claude Code. See README.md for full details, ARCHITECTURE.md
|
||||
for technical deep-dives, USECASES.md for expected behaviors.
|
||||
|
||||
## Key files
|
||||
|
||||
- `scripts/bootstrap.sh` -- First-time server setup (manual, uses Bitwarden)
|
||||
- `scripts/configure.sh` -- Idempotent server config (firewall, certbot, start services; CI-safe)
|
||||
- `scripts/deploy.sh` -- SSH-triggered deploy + cert issuance + provision (deploy-*, cert-*, provision commands)
|
||||
- `tools/new-app.sh` -- Single-command new static site (DNS + Gitea repo + cert + deploy + verify)
|
||||
- `tools/new-app.sh` -- Single-command new static site (DNS + Gitea repo + cert + bucket + deploy + verify)
|
||||
- `tools/new-service.sh` -- Scaffold a new Docker Compose service (compose + workflow)
|
||||
- `tools/remove-app.sh` -- Remove a static site (local files + Gitea repo)
|
||||
- `docker/nginx/` -- Reverse proxy (nginx:alpine + certbot on host)
|
||||
- `docker/nginx/conf.d/` -- Per-app nginx server blocks
|
||||
- `docker/<domain>/compose.yml` -- Per-app compose files
|
||||
- `.gitea/workflows/deploy-<app>.yml` -- Per-app deploy workflows
|
||||
- `.gitea/workflows/provision.yml` -- Triggers configure.sh on setup changes
|
||||
- `docker/garage/` -- Garage S3 object storage (Dockerfile, garage.toml, .env.keys)
|
||||
- `.gitea/workflows/` -- Per-app deploy workflows + provision.yml
|
||||
|
||||
## Conventions
|
||||
|
||||
- **App name = domain** (e.g., `example.com`)
|
||||
- **Container name** = domain with dots replaced by underscores (e.g., `example_com`)
|
||||
- **Image** = `git.timothykim.net/hantim/<domain>:latest`
|
||||
- **Cert name** = config filename without `.conf` (at `/etc/letsencrypt/live/<name>/`)
|
||||
- **Container name** = dots → underscores (e.g., `example_com`)
|
||||
- **One domain per conf file** -- deploy.sh derives cert name from filename
|
||||
- All HTTP redirects to HTTPS; bare domain redirects to `www.<domain>`
|
||||
- All HTTP → HTTPS; bare domain → `www.<domain>`
|
||||
- All shell scripts use `set -euo pipefail` and must be idempotent
|
||||
- The `shared` Docker network is created by nginx compose and used by all apps
|
||||
- Secrets are in Bitwarden Secrets Manager (see README.md for full list)
|
||||
- Service secrets use `.env.keys` files (see README.md)
|
||||
|
||||
## Secrets
|
||||
## Deploy flow
|
||||
|
||||
Bitwarden Secrets Manager (project: `hantim`, fetched via `bws` CLI):
|
||||
- `hantim-ci-registry-push` -- Gitea registry token (used by bootstrap.sh)
|
||||
- `hantim-deploy-ssh-private-key` -- deploy user SSH private key (used by new-app.sh)
|
||||
- `hantim-deploy-ssh-public-key` -- deploy user SSH public key (used by bootstrap.sh)
|
||||
- `hantim-new-app-script` -- Gitea API token for creating repos (used by new-app.sh)
|
||||
- `hantim-vultr-api-key` -- Vultr API key for DNS management (used by new-app.sh)
|
||||
- `hantim-garage-rpc-secret` -- Garage cluster RPC secret (used by deploy.sh)
|
||||
- `hantim-garage-argento-node-id` -- Argento's Garage node ID + address (used by deploy.sh)
|
||||
- `hantim-garage-admin-token` -- Garage admin API token (used by deploy.sh, new-app.sh)
|
||||
- `hantim-garage-media-key-id` -- S3 access key ID for media uploads (used by new-app.sh)
|
||||
- `hantim-garage-media-secret-key` -- S3 secret key for media uploads (used by aws CLI)
|
||||
|
||||
Machine accounts:
|
||||
- `hantim-server` -- access token stored at `/etc/bws-token` on hantim
|
||||
- `hantim-ci` -- access token stored as Gitea secret (reserved for future use)
|
||||
|
||||
Gitea org-level (`hantim`) secrets/variables:
|
||||
- `DEPLOY_HOST` -- Variable (server IP)
|
||||
- `DEPLOY_SSH_KEY` -- Secret (deploy SSH private key)
|
||||
- `CI_REGISTRY_TOKEN` -- Secret (registry token)
|
||||
|
||||
## Working with this repo
|
||||
|
||||
### Adding a new static site
|
||||
|
||||
Run `./tools/new-app.sh <domain>` from dev machine. Handles everything:
|
||||
DNS, Gitea repo, SSL cert, commit/push, build trigger, and verification.
|
||||
See USECASES.md for full details.
|
||||
|
||||
### Adding a new Docker service
|
||||
|
||||
Run `./tools/new-service.sh <name>` to scaffold the compose file and deploy
|
||||
workflow, then edit the compose file and commit.
|
||||
|
||||
### Editing scripts
|
||||
|
||||
All shell scripts use `set -euo pipefail`. Keep all steps idempotent.
|
||||
`configure.sh` must be safe to re-run from CI.
|
||||
|
||||
### Deploy flow
|
||||
|
||||
App repo push -> `build.yml` builds image, pushes to registry, SSHes to server
|
||||
-> `deploy.sh` pulls repo, pulls image, restarts container.
|
||||
|
||||
Infrastructure push (this repo) -> `deploy-<app>.yml` triggers on path match
|
||||
-> same `deploy.sh` flow. nginx deploys test config with `nginx -t` first.
|
||||
|
||||
Setup change push -> `provision.yml` triggers -> `deploy.sh provision`
|
||||
-> `configure.sh` (firewall, certbot, start services).
|
||||
- App repo push → `build.yml` → build/push image → SSH `deploy-<domain>` → deploy.sh
|
||||
- This repo push → `deploy-<app>.yml` (path match) → SSH `deploy-<app>` → deploy.sh
|
||||
- Setup change → `provision.yml` → SSH `provision` → configure.sh
|
||||
|
||||
## Build and test
|
||||
|
||||
No build step. No tests. Verify changes by:
|
||||
1. Reading scripts and checking idempotency
|
||||
2. Walking through each use case in USECASES.md
|
||||
3. Cross-checking documentation (README.md, ARCHITECTURE.md, USECASES.md) against scripts
|
||||
3. Cross-checking docs against scripts
|
||||
|
||||
## Commit style
|
||||
|
||||
|
||||
@@ -4,21 +4,25 @@ Server provisioning and app management for the hantim webserver. This repo
|
||||
lives at `/opt/hantim` on the server and contains Docker Compose configs, deploy
|
||||
scripts, nginx configs, and Gitea Actions workflows for each app.
|
||||
|
||||
See ARCHITECTURE.md for technical deep-dives, USECASES.md for expected behaviors.
|
||||
|
||||
## Infrastructure overview
|
||||
|
||||
Two servers and a cloud secrets service:
|
||||
|
||||
- **Hantim** (Vultr, Rocky Linux 9) — production web server running nginx,
|
||||
app containers, and a Garage storage node via Docker Compose
|
||||
- **Argento** (home server) — Gitea instance (`git.timothykim.net`) with
|
||||
Docker registry, CI runner, and a second Garage storage node (with web UI)
|
||||
- **Bitwarden Secrets Manager** (cloud) — all secrets, fetched via the `bws` CLI
|
||||
|
||||
All app containers share a `shared` Docker network. Only nginx binds host ports
|
||||
(80/443). Garage provides S3-compatible media storage replicated across both
|
||||
nodes.
|
||||
|
||||
## Repo structure
|
||||
|
||||
```
|
||||
docker/
|
||||
nginx/ # Reverse proxy (nginx:alpine) + SSL config
|
||||
nginx.conf # Main nginx config
|
||||
conf.d/ # Per-app server blocks (e.g. example.com.conf)
|
||||
compose.yml
|
||||
<domain>/ # Per-app static site (e.g. example.com)
|
||||
compose.yml
|
||||
garage/ # Garage S3-compatible object storage
|
||||
compose.yml
|
||||
Dockerfile
|
||||
garage.toml
|
||||
.env.keys
|
||||
scripts/
|
||||
bootstrap.sh # First-time server setup (manual, uses Bitwarden)
|
||||
configure.sh # Idempotent server config (CI-safe)
|
||||
@@ -27,7 +31,19 @@ tools/
|
||||
new-app.sh # Add a new static site (run from dev machine)
|
||||
new-service.sh # Add a new Docker service (run from dev machine)
|
||||
remove-app.sh # Remove a static site (run from dev machine)
|
||||
.gitea/workflows/ # Per-app deploy workflows triggered by path changes
|
||||
docker/
|
||||
nginx/ # Reverse proxy (nginx:alpine) + SSL config
|
||||
nginx.conf # Main nginx config
|
||||
conf.d/ # Per-app server blocks (e.g. example.com.conf)
|
||||
compose.yml
|
||||
<domain>/ # Per-app compose files (e.g. example.com)
|
||||
compose.yml
|
||||
garage/ # Garage S3-compatible object storage
|
||||
compose.yml
|
||||
Dockerfile
|
||||
garage.toml
|
||||
.env.keys
|
||||
.gitea/workflows/ # Per-app deploy workflows + provision.yml
|
||||
```
|
||||
|
||||
## Provisioning a new server
|
||||
@@ -40,50 +56,33 @@ git clone https://git.timothykim.net/hantim/hantim-server.git /opt/hantim
|
||||
bash /opt/hantim/scripts/bootstrap.sh
|
||||
```
|
||||
|
||||
`bootstrap.sh` runs once manually. It:
|
||||
`bootstrap.sh` runs once manually. It installs dependencies, sets up the `bws`
|
||||
CLI, creates the `deploy` user, and calls `configure.sh`.
|
||||
|
||||
1. Installs system dependencies (jq, certbot, unzip, Docker)
|
||||
2. Installs the `bws` CLI (Bitwarden Secrets Manager)
|
||||
3. Prompts for a Bitwarden Secrets Manager access token (saved to `/etc/bws-token`)
|
||||
4. Fetches the Docker registry token and deploy SSH public key via `bws`
|
||||
5. Logs into the Gitea Docker registry
|
||||
6. Creates the `deploy` user with restricted SSH access and sudo
|
||||
7. Runs `configure.sh` (firewall, certbot, start services)
|
||||
`configure.sh` is idempotent and CI-safe. It opens firewall ports, sets up
|
||||
certbot renewal, and deploys all services (nginx first, then apps).
|
||||
|
||||
`configure.sh` is idempotent and CI-safe. It:
|
||||
|
||||
1. Opens firewall ports (HTTP, HTTPS, Garage RPC)
|
||||
2. Sets up certbot renewal hooks and timer
|
||||
3. Deploys all services via `deploy.sh` (nginx first, then all apps)
|
||||
- Generates `.env` files from bws for services with `.env.keys`
|
||||
- Issues SSL certs for new domains (nginx only)
|
||||
- Builds or pulls images, starts containers
|
||||
|
||||
**Prerequisites**:
|
||||
**Prerequisites:**
|
||||
- DNS for all configured domains must point to the server
|
||||
- Bitwarden Secrets Manager access token for the `hantim-server` machine account
|
||||
|
||||
## Adding a new app
|
||||
Restoring from backup is identical — run the same three commands on a fresh
|
||||
server. Everything is idempotent.
|
||||
|
||||
## Adding a new static site
|
||||
|
||||
```bash
|
||||
./tools/new-app.sh <domain>
|
||||
```
|
||||
|
||||
Example: `./tools/new-app.sh example.com`
|
||||
|
||||
This single command handles everything: creates DNS records on Vultr, creates
|
||||
the Gitea repo from `static-site-template`, generates all config files, issues
|
||||
the SSL cert (zero downtime), commits and pushes, triggers the first build,
|
||||
and verifies the site is live.
|
||||
This single command handles everything: DNS records (Vultr), Gitea repo
|
||||
(from `static-site-template`), nginx/compose/workflow configs, SSL cert,
|
||||
Garage media bucket, first build, and verification.
|
||||
|
||||
**Prerequisites:** domain nameservers pointed to Vultr, `bws`/`jq`/`dig`
|
||||
installed. Uses the deploy SSH key from Bitwarden Secrets Manager -- no
|
||||
personal server access needed. See USECASES.md for full details.
|
||||
installed, `BWS_ACCESS_TOKEN` env var or token at `~/.config/hantim/bws-token`.
|
||||
|
||||
`new-app.sh` also creates a Garage media bucket for the domain, allowing
|
||||
media files to be served at `https://www.<domain>/media/`.
|
||||
|
||||
After the site is live, clone the app repo and customize it:
|
||||
After the site is live, clone the app repo and customize:
|
||||
|
||||
```bash
|
||||
git clone git@git.timothykim.net:hantim/<domain>.git
|
||||
@@ -94,58 +93,40 @@ git add . && git commit -m "initial content" && git push
|
||||
|
||||
## Deploying changes
|
||||
|
||||
**App code change** (push to an app repo like `example.com`):
|
||||
- The app's `build.yml` builds the Docker image, pushes to the registry, and
|
||||
SSHes into the server to trigger a deploy
|
||||
**App code change** — push to an app repo (e.g., `example.com`):
|
||||
- `build.yml` builds the image, pushes to registry, SSHes to server to deploy
|
||||
|
||||
**Compose or nginx config change** (push to this repo):
|
||||
- Gitea Actions workflows trigger based on which `docker/<app>/` paths changed
|
||||
- `deploy.sh` pulls the latest code and runs `docker compose up -d`
|
||||
- For nginx deploys, the config is tested before applying to prevent downtime
|
||||
**Compose/nginx config change** — push to this repo:
|
||||
- Path-matched workflows trigger and SSH to server
|
||||
- nginx deploys test config before applying (`nginx -t`)
|
||||
|
||||
## Garage cluster initialization
|
||||
|
||||
After provisioning a fresh server, Garage starts and connects to argento
|
||||
automatically via `bootstrap_peers`. However, the cluster layout must be
|
||||
assigned manually (node IDs change on fresh installs):
|
||||
|
||||
```bash
|
||||
# Check both nodes are connected
|
||||
docker exec garage /garage status
|
||||
|
||||
# Assign roles (use the node IDs from status output)
|
||||
docker exec garage /garage layout assign <hantim-node-id> -z hantim -c 1G
|
||||
docker exec garage /garage layout assign <argento-node-id> -z argento -c 1G
|
||||
docker exec garage /garage layout apply --version 1
|
||||
```
|
||||
|
||||
This only needs to be done once. If only hantim is reprovisioned, argento
|
||||
retains the layout and hantim reconnects automatically.
|
||||
**Setup change** — push changes to `scripts/configure.sh`:
|
||||
- `provision.yml` triggers and re-runs `configure.sh`
|
||||
|
||||
## Media hosting
|
||||
|
||||
Media files (images, videos) are stored in Garage and served via nginx at
|
||||
`/media/` on each domain. This keeps large files out of git repos.
|
||||
Media files are stored in Garage and served via nginx at `/media/` on each
|
||||
domain. This keeps large files out of git repos.
|
||||
|
||||
**Endpoints:**
|
||||
- `s3.hantim.net` — S3 API for uploads (authenticated with `media-key`)
|
||||
- `s3.hantim.net` — S3 API for uploads (authenticated)
|
||||
- `garage.hantim.net` — Admin API for bucket management
|
||||
- `https://www.<domain>/media/<path>` — public file access
|
||||
|
||||
**Uploading media:**
|
||||
**Uploading:**
|
||||
|
||||
```bash
|
||||
# Configure AWS CLI (one-time)
|
||||
aws configure # key ID, secret key from bws, region: garage, output: json
|
||||
# One-time AWS CLI setup
|
||||
aws configure # key ID + secret from bws, region: garage, output: json
|
||||
# Then add to ~/.aws/config under [default]:
|
||||
# endpoint_url = https://s3.hantim.net
|
||||
|
||||
# Upload files
|
||||
# Upload
|
||||
aws s3 cp photo.jpg s3://example.com/photo.jpg
|
||||
aws s3 sync static/media/ s3://example.com/
|
||||
```
|
||||
|
||||
**Local development:** Store media in `static/media/` (gitignored) so files
|
||||
**Local development:** store media in `static/media/` (gitignored) so files
|
||||
are accessible at `/media/` when serving locally.
|
||||
|
||||
**Creating buckets manually** (for existing domains without buckets):
|
||||
@@ -164,16 +145,26 @@ curl -X POST -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/jso
|
||||
"https://garage.hantim.net/v2/UpdateBucket?id=BUCKET_ID"
|
||||
```
|
||||
|
||||
## Restoring from backup
|
||||
## Garage cluster initialization
|
||||
|
||||
Run the same three commands as provisioning. `bootstrap.sh` is idempotent:
|
||||
- Existing packages are skipped
|
||||
- Existing certs are skipped (or re-issued if the server is new)
|
||||
- All services are started
|
||||
After provisioning a fresh server, Garage connects to argento automatically.
|
||||
The cluster layout must be assigned manually once (node IDs change per install):
|
||||
|
||||
```bash
|
||||
docker exec garage /garage status
|
||||
docker exec garage /garage layout assign <hantim-node-id> -z hantim -c 1G
|
||||
docker exec garage /garage layout assign <argento-node-id> -z argento -c 1G
|
||||
docker exec garage /garage layout apply --version 1
|
||||
```
|
||||
|
||||
If only hantim is reprovisioned, argento retains the layout and hantim
|
||||
reconnects automatically.
|
||||
|
||||
## Secrets
|
||||
|
||||
Bitwarden Secrets Manager (project: `hantim`, fetched via `bws` CLI on the server):
|
||||
### Bitwarden Secrets Manager
|
||||
|
||||
Project: `hantim`. Fetched via `bws` CLI on the server.
|
||||
|
||||
| Secret | Purpose | Used by |
|
||||
|---|---|---|
|
||||
@@ -192,12 +183,13 @@ Machine accounts: `hantim-server` (token at `/etc/bws-token`), `hantim-ci` (rese
|
||||
|
||||
### Service secrets (`.env.keys`)
|
||||
|
||||
Services that need secrets declare them in a `.env.keys` file (format:
|
||||
`ENV_VAR=bws-secret-name`, one per line). `deploy.sh` reads this file,
|
||||
fetches each secret from bws, and generates a `.env` file before starting
|
||||
the service. See `docker/garage/.env.keys` for an example.
|
||||
Services that need secrets declare them in `.env.keys` (format:
|
||||
`ENV_VAR=bws-secret-name`, one per line). `deploy.sh` fetches each secret
|
||||
from bws and generates `.env` before starting the service.
|
||||
|
||||
Gitea org-level (`hantim`) secrets/variables:
|
||||
### Gitea org-level secrets
|
||||
|
||||
Stored in the `hantim` Gitea org for direct use in CI workflows:
|
||||
|
||||
| Name | Type | Purpose |
|
||||
|---|---|---|
|
||||
|
||||
+61
-155
@@ -1,193 +1,99 @@
|
||||
# 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
|
||||
|
||||
One-time setup before anything else works. Create the secrets project and
|
||||
machine accounts in Bitwarden Secrets Manager.
|
||||
**Trigger:** one-time, before anything else works.
|
||||
|
||||
1. Create a Bitwarden organization (free tier)
|
||||
2. Enable Secrets Manager for the organization
|
||||
3. Create a project named `hantim`
|
||||
4. Create all required secrets (see README.md Secrets table for the full list)
|
||||
5. Create machine accounts:
|
||||
- `hantim-server` — grant access to the `hantim` project
|
||||
- `hantim-ci` — reserved for future CI use
|
||||
6. Generate access tokens for each machine account
|
||||
**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
|
||||
|
||||
Set up a fresh Rocky Linux 9 server from scratch.
|
||||
**Trigger:** run `bootstrap.sh` on a fresh Rocky Linux 9 install.
|
||||
|
||||
```bash
|
||||
dnf install -y git
|
||||
git clone https://git.timothykim.net/hantim/hantim-server.git /opt/hantim
|
||||
bash /opt/hantim/scripts/bootstrap.sh
|
||||
```
|
||||
**Prerequisites:** DNS pointed to server, bws access token ready.
|
||||
|
||||
**What happens:**
|
||||
- Installs all dependencies (jq, certbot, unzip, Docker)
|
||||
- Installs `bws` CLI, prompts for Bitwarden Secrets Manager access token
|
||||
- Fetches registry token and deploy SSH public key via `bws`
|
||||
- Logs into Docker registry
|
||||
- Creates deploy user with restricted SSH + sudo
|
||||
- Runs `configure.sh`:
|
||||
- Opens firewall ports (HTTP, HTTPS, Garage RPC)
|
||||
- Sets up certbot renewal
|
||||
- Deploys all services via `deploy.sh` (generates `.env` files, issues certs, starts containers)
|
||||
|
||||
**Prerequisites:**
|
||||
- DNS for all configured domains must point to the server
|
||||
- Bitwarden Secrets Manager access token for the `hantim-server` machine account
|
||||
- Docker images must exist in the Gitea registry (or apps will start on next push)
|
||||
**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
|
||||
|
||||
Identical to provisioning a new server. Run the same three commands on a
|
||||
fresh server.
|
||||
**Trigger:** same three commands as provisioning on a fresh server.
|
||||
|
||||
- `bootstrap.sh` and `configure.sh` are 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
|
||||
**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
|
||||
|
||||
From your dev machine (single command):
|
||||
**Trigger:** `./tools/new-app.sh example.com` from dev machine.
|
||||
|
||||
```bash
|
||||
./tools/new-app.sh example.com
|
||||
```
|
||||
**Prerequisites:** domain nameservers on Vultr, `bws`/`jq`/`dig` installed.
|
||||
|
||||
**Prerequisites:**
|
||||
- Bitwarden Secrets Manager must contain `hantim-new-app-script`,
|
||||
`hantim-vultr-api-key`, and `hantim-deploy-ssh-private-key`
|
||||
- Domain nameservers must be pointed to Vultr (configured on directnic.com)
|
||||
- Dependencies: `bws`, `jq`, `dig`
|
||||
- `BWS_ACCESS_TOKEN` env var or token saved at `~/.config/hantim/bws-token`
|
||||
|
||||
**What happens (fully automated):**
|
||||
1. Resolves server IP from `hantim.net`
|
||||
2. Fetches Gitea API token, Vultr API key, and deploy SSH key from Bitwarden Secrets Manager
|
||||
3. Creates DNS zone on Vultr (if needed) and A records for bare + www
|
||||
4. Waits for DNS to propagate
|
||||
5. Creates Gitea repo `hantim/example.com` from `static-site-template`
|
||||
6. Creates local files:
|
||||
- `docker/example.com/compose.yml` (container name: `example_com`)
|
||||
- `.gitea/workflows/deploy-example.com.yml`
|
||||
- `docker/nginx/conf.d/example.com.conf` (HTTP->HTTPS, bare->www, proxy)
|
||||
7. SSHes to server as deploy user, issues SSL cert via webroot (zero downtime)
|
||||
8. Creates Garage media bucket via admin API (create, allow media-key, enable website)
|
||||
9. Commits and pushes hantim-server (triggers deploy)
|
||||
10. Triggers initial build of the app repo via Gitea API
|
||||
11. Polls `https://www.example.com` until it responds (up to 3 minutes)
|
||||
|
||||
After the site is live, clone the app repo and customize:
|
||||
|
||||
```bash
|
||||
git clone git@git.timothykim.net:hantim/example.com.git
|
||||
cd example.com
|
||||
# edit static/index.html, etc.
|
||||
git add . && git commit -m "initial content" && git push
|
||||
```
|
||||
**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
|
||||
|
||||
Push a change to the app repo (e.g., `example.com`):
|
||||
**Trigger:** push to an app repo.
|
||||
|
||||
```bash
|
||||
cd example.com
|
||||
# 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-example.com`
|
||||
3. `deploy.sh` pulls latest hantim-server, pulls new image, restarts container
|
||||
|
||||
No manual steps needed.
|
||||
**Expected outcome:**
|
||||
- Docker image built and pushed to registry
|
||||
- Container restarted on server with new image
|
||||
- No manual steps
|
||||
|
||||
## 5. Update Docker Compose config
|
||||
|
||||
Edit a compose file in this repo and push:
|
||||
**Trigger:** push compose file change to this repo.
|
||||
|
||||
```bash
|
||||
vim docker/example.com/compose.yml
|
||||
git add docker/example.com/compose.yml
|
||||
git commit -m "update example.com config"
|
||||
git push
|
||||
```
|
||||
|
||||
**What happens:**
|
||||
1. `deploy-example.com.yml` workflow triggers (path match)
|
||||
2. `deploy.sh` pulls latest code, pulls image, runs `docker compose up -d`
|
||||
**Expected outcome:**
|
||||
- Path-matched workflow triggers
|
||||
- Container restarted with updated config
|
||||
|
||||
## 6. Update nginx config
|
||||
|
||||
Edit an nginx config in this repo and push:
|
||||
**Trigger:** push nginx conf change to this repo.
|
||||
|
||||
```bash
|
||||
vim docker/nginx/conf.d/example.com.conf
|
||||
git add docker/nginx/conf.d/example.com.conf
|
||||
git commit -m "update nginx config"
|
||||
git push
|
||||
```
|
||||
**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
|
||||
|
||||
**What happens:**
|
||||
1. `deploy-nginx.yml` workflow triggers (path match)
|
||||
2. `deploy.sh` pulls latest code
|
||||
3. If any conf files reference certs that don't exist yet, nginx is briefly
|
||||
stopped and certs are issued via standalone certbot (auto-restarts on failure)
|
||||
4. Tests nginx config with `nginx -t` -- if it fails, deploy aborts and the
|
||||
running nginx is untouched
|
||||
5. Runs `docker compose up -d` and reloads nginx
|
||||
## 7. Re-run configure
|
||||
|
||||
**Note:** Each conf file must contain server blocks for only one domain. The
|
||||
cert name is derived from the filename (e.g. `example.com.conf` -> cert
|
||||
`example.com`). Redirect-only domains get their own conf file.
|
||||
**Trigger:** push change to `scripts/configure.sh`, or run manually.
|
||||
|
||||
## 7. Re-run configure on existing server
|
||||
|
||||
Safe to do at any time, manually or via CI:
|
||||
|
||||
```bash
|
||||
cd /opt/hantim
|
||||
git pull
|
||||
bash scripts/configure.sh
|
||||
```
|
||||
|
||||
Or push a change to `scripts/configure.sh` — the `provision.yml` workflow
|
||||
triggers automatically.
|
||||
|
||||
- All steps are idempotent
|
||||
- Existing certs are skipped
|
||||
- Brief nginx downtime (seconds) while certbot checks run
|
||||
- Services are restarted
|
||||
**Expected outcome:**
|
||||
- All steps idempotent — safe to run anytime
|
||||
- Existing certs skipped
|
||||
- Services restarted
|
||||
|
||||
## 8. Upload media files
|
||||
|
||||
Media files (images, videos) are stored in Garage and served at `/media/`
|
||||
on each domain.
|
||||
**Trigger:** `aws s3 cp` or `aws s3 sync` to `s3://example.com/`.
|
||||
|
||||
```bash
|
||||
# One-time setup
|
||||
aws configure # key ID + secret from bws, region: garage, output: json
|
||||
# Then add to ~/.aws/config under [default]:
|
||||
# endpoint_url = https://s3.hantim.net
|
||||
|
||||
# Upload a single file
|
||||
aws s3 cp photo.jpg s3://example.com/photo.jpg
|
||||
|
||||
# Sync a directory
|
||||
aws s3 sync static/media/ s3://example.com/
|
||||
```
|
||||
|
||||
**What happens:**
|
||||
1. File is uploaded to the Garage S3 API via `s3.hantim.net`
|
||||
2. Garage replicates the file to both nodes (hantim + argento)
|
||||
3. File is accessible at `https://www.example.com/media/photo.jpg`
|
||||
|
||||
**Local development:** Store media in `static/media/` (gitignored). The app's
|
||||
nginx serves these locally, matching the `/media/` path used in production.
|
||||
|
||||
**Reference in HTML:** Use absolute paths like `/media/photo.jpg`.
|
||||
**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/`
|
||||
|
||||
Reference in New Issue
Block a user