docs: clarify hydra components in design document

Signed-off-by: NotAShelf <raf@notashelf.dev>
Change-Id: I56a1dee4df5e3898aa7ef6e24ed7342c6a6a6964

docs/DESIGN.md

@@ -46,3 +46,10 @@ Hydra follows a tightly-coupled architecture with three main daemons:
 ```plaintext
 Git Repository -> Evaluator -> Database -> Queue Runner -> Build Hosts -> Results -> Database - Web UI
 ```
+
+1. **hydra-server** (Perl/Catalyst): Web interface and REST API
+2. **hydra-evaluator**: Polls Git repos, evaluates Nix expressions, creates
+   `.drv` files
+3. **hydra-queue-runner**: Dispatches builds to available builders via SSH/Nix
+   remote
+4. **Database (PostgreSQL)**: Central state management for all components

docs/README.md

@@ -186,7 +186,7 @@ development.
 <!--markdownlint-disable MD013 -->
 
 | Section         | Key                    | Default                                       | Description                                           |
-| --------------- | ---------------------- | --------------------------------------------- | ----------------------------------------- |
+| --------------- | ---------------------- | --------------------------------------------- | ----------------------------------------------------- |
 | `database`      | `url`                  | `postgresql://fc_ci:password@localhost/fc_ci` | PostgreSQL connection URL                             |
 | `database`      | `max_connections`      | `20`                                          | Maximum connection pool size                          |
 | `database`      | `min_connections`      | `5`                                           | Minimum idle connections                              |
@@ -200,8 +200,9 @@ development.
 | `server`        | `api_key`              | none                                          | Optional legacy API key (prefer DB keys)              |
 | `server`        | `cors_permissive`      | `false`                                       | Allow all CORS origins                                |
 | `server`        | `allowed_origins`      | `[]`                                          | Allowed CORS origins list                             |
-| `server`        | `rate_limit_rps`       | none                                          | Requests per second limit                 |
+| `server`        | `force_secure_cookies` | `false`                                       | Force Secure flag on cookies (enable for HTTPS proxy) |
-| `server`        | `rate_limit_burst`     | none                                          | Burst size for rate limiting              |
+| `server`        | `rate_limit_rps`       | none                                          | Requests per second limit per IP (DoS protection)     |
+| `server`        | `rate_limit_burst`     | none                                          | Burst size for rate limiting (e.g., 20)               |
 | `evaluator`     | `poll_interval`        | `60`                                          | Seconds between git poll cycles                       |
 | `evaluator`     | `git_timeout`          | `600`                                         | Git operation timeout (seconds)                       |
 | `evaluator`     | `nix_timeout`          | `1800`                                        | Nix evaluation timeout (seconds)                      |
@@ -300,6 +301,11 @@ proxy:
       server.host = "127.0.0.1";
       server.port = 3000;
 
+      # Security: enable when behind HTTPS reverse proxy
+      server.force_secure_cookies = true;
+      server.rate_limit_rps = 100;
+      server.rate_limit_burst = 20;
+
       evaluator.poll_interval = 300;
       evaluator.restrict_eval = true;
       queue_runner.workers = 8;
@@ -369,6 +375,56 @@ Ensure the PostgreSQL server on the head node allows connections from builder
 machines via `pg_hba.conf` (the NixOS `services.postgresql` module handles this
 with `authentication` settings).
 
+#### Remote Builders via SSH
+
+FC supports an alternative deployment model where a single queue-runner
+dispatches builds to remote builder machines via SSH. In this setup:
+
+- **Head node**: runs `fc-server`, `fc-evaluator`, and **one** `fc-queue-runner`
+- **Builder machines**: standard NixOS machines with SSH access and Nix
+  installed (no FC software required)
+
+The queue-runner automatically attempts remote builds using:
+
+```bash
+nix build --store ssh://<builder>
+```
+
+when a build's `system` matches a configured remote builder. If no remote
+builder is available or all fail, it falls back to local execution.
+
+You can configure remote builders via the REST API:
+
+```bash
+# Create a remote builder
+curl -X POST http://localhost:3000/api/v1/admin/builders \
+  -H 'Authorization: Bearer <admin-key>' \
+  -H 'Content-Type: application/json' \
+  -d '{
+    "name": "builder-1",
+    "ssh_uri": "builder-1.example.org",
+    "systems": ["x86_64-linux", "aarch64-linux"],
+    "max_jobs": 4,
+    "speed_factor": 1,
+    "enabled": true
+  }'
+```
+
+Do note that this requires some SSH key setup. Namely.
+
+- The queue-runner machine needs SSH access to each builder (public key in
+  `~/.ssh/authorized_keys` on builders)
+- Use `ssh_key_file` in the builder config if using a non-default key
+- Add known host keys via `public_host_key` to prevent MITM warnings
+
+The queue-runner tracks builder health automatically: consecutive failures
+disable the builder with exponential backoff until it recovers.
+
+## Security
+
+FC implements multiple security layers to protect your CI infrastructure. See
+[the security document](./SECURITY.md) for more details.
+
 ## Authentication
 
 FC supports two authentication methods: