Post-Tyranny-Tech-Infrastructure/clients/README.md

# Client Registry

This directory contains the client registry system for tracking all deployed infrastructure.

## Files

- **[registry.yml](registry.yml)** - Single source of truth for all clients
  - Deployment status and lifecycle
  - Server specifications
  - Application versions
  - Maintenance history
  - Access URLs

## Management Scripts

All scripts are located in [`../scripts/`](../scripts/):

### View Clients

View the registry directly:
```bash
# View full registry
cat registry.yml

# View specific client (requires yq)
yq eval '.clients.dev' registry.yml
```

### View Client Details

```bash
# Show detailed status with live health checks
../scripts/client-status.sh <client_name>
```

### Update Registry

The registry is **automatically updated** by deployment scripts:
- `deploy-client.sh` - Creates/updates entry on deployment
- `rebuild-client.sh` - Updates entry on rebuild
- `destroy-client.sh` - Marks as destroyed

For manual updates, edit `registry.yml` directly.

## Registry Structure

Each client entry tracks:
- **Status**: `pending` → `deployed` → `maintenance` → `offboarding` → `destroyed`
- **Role**: `canary` (testing) or `production` (live)
- **Server**: Type, location, IP, Hetzner ID
- **Apps**: Installed applications
- **Versions**: Application and OS versions
- **Maintenance**: Update and backup history
- **URLs**: Access endpoints
- **Notes**: Operational documentation

## Canary Deployment

The `dev` client has role `canary` and is used for testing:

```bash
# 1. Test on canary first
../scripts/deploy-client.sh dev

# 2. Verify it works
../scripts/client-status.sh dev

# 3. Roll out to production clients manually
# Review registry.yml for production clients, then rebuild each one
```

## Registry Structure Details

The `registry.yml` file uses YAML format with the following structure:
- Complete registry structure reference in the file itself
- Client lifecycle states and metadata
- Server specifications and IP addresses
- Deployment timestamps and version tracking

## Requirements

- **yq**: YAML processor (`brew install yq`)
- **jq**: JSON processor (`brew install jq`)