glam/.opencode/DEPLOYMENT_RULES.md

# Deployment Rules for AI Agents

**Last Updated**: 2025-12-19  
**Status**: MANDATORY for all deployment operations

---

## 🚨 CRITICAL: Deployment Method

**This project uses LOCAL DEPLOYMENT, NOT GitHub Actions.**

All deployments are executed from the developer's local machine via SSH/rsync to the Hetzner Cloud server.

---

## 🚨 CRITICAL: Monorepo Frontend Structure

**This project contains TWO separate frontend applications:**

| Domain | Local Directory | Server Path |
|--------|-----------------|-------------|
| **bronhouder.nl** | `/frontend/` | `/var/www/glam-frontend/` |
| **archief.support** | `/apps/archief-assistent/` | `/var/www/archief-assistent/` |

**When debugging issues, ALWAYS verify which domain is affected before editing code!**

---

## Server Information

| Property | Value |
|----------|-------|
| **Provider** | Hetzner Cloud |
| **Server Name** | `glam-sparql` |
| **IP Address** | `91.98.224.44` |
| **SSH User** | `root` |
| **Main Frontend Path** | `/var/www/glam-frontend/` |
| **Archief Assistent Path** | `/var/www/archief-assistent/` |
| **Data Path** | `/mnt/data/` |

---

## Deployment Script

**Location**: `infrastructure/deploy.sh`

### Usage

```bash
# Deploy frontend only (most common)
./infrastructure/deploy.sh --frontend

# Deploy schema/ontology data only
./infrastructure/deploy.sh --data

# Check server status
./infrastructure/deploy.sh --status

# Deploy everything (infrastructure + data + frontend + reload)
./infrastructure/deploy.sh --all
```

### Options Reference

| Option | Description |
|--------|-------------|
| `--frontend` | Build and deploy React frontend |
| `--data` | Deploy ontology/schema files |
| `--infra` | Deploy infrastructure via Terraform |
| `--reload` | Reload data into Oxigraph SPARQL server |
| `--status` | Check server and service status |
| `--all` | Execute all deployment steps |

---

## Frontend Deployment Process

When `--frontend` is executed:

1. **Build Step** (`frontend/` directory):
   ```bash
   npm ci              # Install dependencies
   npm run build       # Vite production build
   ```

2. **Schema Sync** (automated in build):
   ```bash
   # Copies LinkML schemas to public directory
   rsync schemas/20251121/linkml/ → frontend/public/schemas/20251121/linkml/
   ```

3. **Manifest Generation** (automated in build):
   ```bash
   node scripts/generate-schema-manifest.cjs
   # Creates: frontend/public/schemas/20251121/linkml/manifest.json
   ```

4. **Deploy to Server**:
   ```bash
   rsync -avz --progress --delete \
     frontend/dist/ \
     root@91.98.224.44:/var/www/glam-frontend/
   ```

---

## Archief Assistent Deployment Process

**NOTE**: The `deploy.sh` script does NOT handle archief-assistent. Use manual commands.

1. **Build Step** (`apps/archief-assistent/` directory):
   ```bash
   cd apps/archief-assistent
   npm ci              # Install dependencies
   npm run build       # Vite production build
   ```

2. **Deploy to Server**:
   ```bash
   rsync -avz --progress --delete \
     dist/ \
     root@91.98.224.44:/var/www/archief-assistent/
   ```

### Quick One-Liner

```bash
cd apps/archief-assistent && npm run build && rsync -avz --delete dist/ root@91.98.224.44:/var/www/archief-assistent/
```

---

## Prerequisites

### Environment Variables

Required in `.env` file at project root:

```bash
# Hetzner Cloud API Token (required for all deployments)
HETZNER_HC_API_TOKEN=your_token_here

# Optional - domain configuration
GLAM_DOMAIN=sparql.glam-ontology.org
ADMIN_EMAIL=admin@glam-ontology.org
```

### SSH Access

- SSH key must be added to Hetzner server
- Test connection: `ssh root@91.98.224.44 "echo connected"`

### Local Dependencies

- `rsync` (file synchronization)
- `jq` (JSON parsing for status checks)
- `npm` (for frontend builds)
- `terraform` (only for `--infra` option)

---

## Common Deployment Scenarios

### 1. After Frontend Code Changes (bronhouder.nl)

```bash
./infrastructure/deploy.sh --frontend
```

**What happens**:
- Builds React app with Vite
- Syncs LinkML schemas to public directory
- Generates schema manifest
- Deploys to `/var/www/glam-frontend/`

### 2. After Archief Assistent Changes (archief.support)

```bash
cd apps/archief-assistent && npm run build && rsync -avz --delete dist/ root@91.98.224.44:/var/www/archief-assistent/
```

**What happens**:
- Builds React app with Vite
- Deploys to `/var/www/archief-assistent/`

### 3. After Schema Changes

```bash
./infrastructure/deploy.sh --data --reload
```

**What happens**:
- Syncs ontology files (`.ttl`, `.rdf`, `.owl`, `.jsonld`)
- Syncs RDF schemas
- Syncs LinkML schemas
- Syncs UML diagrams (`.mmd`)
- Reloads Oxigraph with new data

### 4. Full Deployment

```bash
./infrastructure/deploy.sh --all
```

**Use sparingly** - this runs Terraform and may modify infrastructure.

### 5. Verify Deployment

```bash
./infrastructure/deploy.sh --status
```

**Shows**:
- Server status (IP, type, location)
- Service status (Oxigraph, Caddy)
- SPARQL triple count

---

## AI Agent Deployment Rules

### DO

- ✅ Use `./infrastructure/deploy.sh --frontend` after bronhouder.nl frontend changes
- ✅ Use manual rsync for archief.support changes (see Archief Assistent Deployment section)
- ✅ **Identify which domain is affected BEFORE editing code**
- ✅ Verify build succeeds locally before deploying
- ✅ Run `--status` to confirm deployment success
- ✅ Document what was deployed in session summary

### DO NOT

- ❌ Push to `main` branch expecting CI/CD (there is none)
- ❌ Manually rsync without using the deploy script (for main frontend)
- ❌ Modify server files directly via SSH
- ❌ Use `--all` without explicit user confirmation
- ❌ Deploy without testing locally first
- ❌ **Edit `/frontend/` when issue is on archief.support**
- ❌ **Edit `/apps/archief-assistent/` when issue is on bronhouder.nl**
- ❌ **Deploy to wrong server path**

---

## Troubleshooting

### Build Fails

```bash
cd frontend
rm -rf node_modules
npm ci
npm run build
```

### SSH Connection Refused

```bash
# Check server is running
./infrastructure/deploy.sh --status

# Test SSH directly
ssh -o ConnectTimeout=5 root@91.98.224.44 "echo connected"
```

### Schema Manifest Missing

```bash
cd frontend
node scripts/generate-schema-manifest.cjs
# Should create: public/schemas/20251121/linkml/manifest.json
```

### Deployment Stuck

```bash
# Check if rsync is running
ps aux | grep rsync

# Force kill and retry
pkill rsync
./infrastructure/deploy.sh --frontend
```

---

## Post-Deployment Verification

After any deployment, verify:

1. **Server Status**:
   ```bash
   ./infrastructure/deploy.sh --status
   ```

2. **Main Frontend Accessible** (bronhouder.nl):
   - Open `http://91.98.224.44` in browser
   - Check browser console for errors

3. **Archief Assistent Accessible** (archief.support):
   - Open `https://archief.support` in browser
   - Test map page: `https://archief.support/map`
   - Check browser console for errors (ignore MapLibre GL warnings)

4. **SPARQL Endpoint** (if `--data` deployed):
   ```bash
   curl -X POST -H "Content-Type: application/sparql-query" \
     -d "SELECT (COUNT(*) AS ?c) WHERE { ?s ?p ?o }" \
     http://91.98.224.44:7878/query
   ```

### Harmless Console Warnings

These warnings can be ignored (MapLibre GL cosmetic issues):

| Warning | Cause |
|---------|-------|
| `Error in parsing value for 'user-select'. Declaration dropped.` | MapLibre CSS parsing |
| `WebGL warning: texImage: Alpha-premult and y-flip are deprecated` | WebGL deprecation notice |

---

## Related Documentation

- **Monorepo Frontend Apps**: `.opencode/MONOREPO_FRONTEND_APPS.md`
- **Full Deployment Guide**: `docs/DEPLOYMENT_GUIDE.md`
- **Infrastructure Setup**: `infrastructure/README.md`
- **Terraform Config**: `infrastructure/terraform/`
- **Server Scripts**: `infrastructure/scripts/`

---

## Version History

| Date | Change |
|------|--------|
| 2025-12-19 | Added monorepo structure, archief-assistent deployment, harmless warnings |
| 2025-12-01 | Initial documentation |