# VPS Hosting & Web Editor Setup

This repository contains the configuration and static HTML/CSS/JS files for all hosted client websites, as well as the Caddy configuration for the VPS server itself. 

The server uses **Caddy** to route traffic, automatically provision SSL certificates, and manage a background `opencode` (web mode) instance for browser-based editing.

## Architecture Overview

- **Provider**: Hetzner Cloud (Ubuntu VPS, ~€4/month)
- **Web Server**: Caddy (Custom build with `caddy-exec` module)
- **Editor**: `opencode` (Running in web mode, bound to localhost)
- **Files**: One Git Monorepo (this repo) located at `/srv/sites`

## Adding a New Client Website

1. Create a new folder in this repository with a short slug and **no domain extension** (e.g., `new-client`, not `new-client.ie`). The TLD lives only in the `Caddyfile` site block.
2. Add their static HTML/CSS/JS files into that folder. (Ensure you use **relative paths** in the HTML, e.g., `<link href="css/style.css">`, not `/css/style.css`, so the preview domain works correctly).
3. Open the `Caddyfile` and add a new block for them at the bottom:
   ```caddy
   newclient.ie, www.newclient.ie {
       root * new-client
       file_server
   }
   ```
4. Commit and push your changes to Git.
5. Pull and reload on the server — see [Editing the Caddyfile](#editing-the-caddyfile) below for the full validate/reload/rollback workflow.

### Client DNS Instructions
When a client asks how to point their domain to your server, give them these exact instructions for their domain registrar:
- **A Record**: Host `@` (or blank) -> Point to **[YOUR_VPS_IP]**
- **CNAME**: Host `www` -> Point to **[YOUR_VPS_IP]** (or `sites.damien.ie`)

## Editing the Caddyfile

Any change to the `Caddyfile` — adding a client, tweaking a route, changing auth — needs the same workflow on the server:

1. **Pull the latest Caddyfile** so the server sees your change:
   ```bash
   cd /srv/sites && git pull
   ```

2. **Validate** before reloading. Caddy parses the file and refuses bad configs:
   ```bash
   caddy validate --config /srv/sites/Caddyfile
   ```
   Look for `INFO adapted config to JSON` with no `Error:` line. Warnings about deprecated directives are fine.

3. **Reload with zero downtime**:
   ```bash
   caddy reload --config /srv/sites/Caddyfile
   ```
   Caddy builds the new config in a side process and only swaps once it's healthy, so no request is dropped.

4. **If something looks off**, check the service and recent logs:
   ```bash
   systemctl status caddy --no-pager
   journalctl -xeu caddy.service -n 50 --no-pager
   ```

5. **Roll back** if a reload succeeds but a client reports an issue — the previous Caddyfile is in git, so:
   ```bash
   git checkout HEAD~1 -- Caddyfile
   caddy reload --config /srv/sites/Caddyfile
   ```

## Web Editor Workflow

To keep the server secure and save memory, the web editor does not run 24/7. It is manually started and stopped when you need to make edits.

### 1. Start the Editor
Go to `https://sites.damien.ie/start` in your browser. 
Enter your username (`damien`) and password. Caddy will spin up `opencode` (web mode) in the background.

### 2. Edit the Code
Go to `https://code.sites.damien.ie`. 
You will see the opencode web UI loaded at `/srv/sites`. Make your changes, commit them to Git, and reload Caddy via the terminal inside the editor.

### 3. Preview Your Work
Go to `https://sites.damien.ie/northkerrysaltroom` to preview the site live on the server before the client points their domain to it.

### 4. Stop the Editor
When you are completely finished, go to `https://sites.damien.ie/stop`. Caddy will kill the opencode process, removing it from the internet and freeing up server resources.

### Changing the Editor Password
There is one password, used for both the Caddy basicauth (on `/start` and `/stop`) and the opencode web UI's basic auth. To change it:

```bash
caddy hash-password --plaintext "your_new_password"
```

Edit `/srv/sites/Caddyfile`:
- Replace the hash inside **both** `basic_auth` blocks with the new hash.
- Replace `<OPENCODE_PASSWORD>` (or its current value) in the `/start` exec line with the new plaintext.

Then follow the [Editing the Caddyfile](#editing-the-caddyfile) workflow to validate and reload.

## See also

- [VPS-SETUP.md](VPS-SETUP.md) — first-time server provisioning and migration guide. Only needed when bootstrapping a fresh Hetzner VPS or rebuilding after a failure; not required for day-to-day operations.