Extension: ccache-remote — shared compilation cache via Redis/HTTP

extensions/ccache-remote/README.server-setup.md

@@ -0,0 +1,142 @@
+# ccache-remote: Server Setup Guide
+
+## Redis Server
+
+1. Install packages:
+   ```bash
+   apt install redis-server avahi-daemon avahi-utils
+   ```
+
+2. Configure Redis — merge the settings from `misc/redis/redis-ccache.conf` into
+   `/etc/redis/redis.conf`, or add an `include` directive at the end of your
+   existing config (`include /etc/redis/redis-ccache.conf`), then restart:
+   ```bash
+   sudo systemctl restart redis-server
+   ```
+
+   **Authentication (recommended).** Set a password in the config file — either via
+   `requirepass` (Redis < 6) or ACL user entry (Redis 6+). See comments in
+   `misc/redis/redis-ccache.conf` for both methods. Generate a URL-safe password:
+   ```bash
+   openssl rand -hex 24
+   ```
+   **Important:** Do not use `openssl rand -base64` — base64 passwords contain
+   `/`, `+`, and `=` which break URL parsing in `redis://` connection strings.
+   On the build host, pass the password in the Redis URL:
+   ```bash
+   ./compile.sh ENABLE_EXTENSIONS=ccache-remote \
+     CCACHE_REMOTE_STORAGE="redis://default:YOUR_PASSWORD@192.168.1.65:6379" BOARD=...
+   ```
+
+   **No authentication (trusted network only).** If all machines are on a fully
+   isolated private network and access control is not needed, remove `requirepass`,
+   set `nopass` in the ACL user entry, and set `protected-mode no`. See comments
+   in `misc/redis/redis-ccache.conf`. No password is needed in the URL:
+   ```bash
+   ./compile.sh ENABLE_EXTENSIONS=ccache-remote \
+     CCACHE_REMOTE_STORAGE="redis://192.168.1.65:6379" BOARD=...
+   ```
+
+   For advanced security (TLS, ACL, rename-command), see:
+   https://redis.io/docs/latest/operate/oss_and_stack/management/security/
+
+3. Publish DNS-SD service — copy `misc/avahi/ccache-redis.service` to `/etc/avahi/services/`:
+   ```bash
+   cp misc/avahi/ccache-redis.service /etc/avahi/services/
+   ```
+   Avahi will pick it up automatically. Clients running `avahi-browse -rpt _ccache._tcp`
+   will discover the Redis service.
+
+   Or use a systemd unit that ties the announcement to `redis-server` lifetime
+   (stops advertising when Redis is down):
+   ```bash
+   cp misc/systemd/ccache-avahi-redis.service /etc/systemd/system/
+   systemctl enable --now ccache-avahi-redis
+   ```
+
+   Alternatively, publish legacy mDNS hostname:
+   ```bash
+   avahi-publish-address -R ccache.local <SERVER_IP>
+   ```
+   Or as a systemd service (`/etc/systemd/system/ccache-hostname.service`):
+   ```ini
+   [Unit]
+   Description=Publish ccache.local hostname via Avahi
+   After=avahi-daemon.service redis-server.service
+   BindsTo=redis-server.service
+   [Service]
+   Type=simple
+   ExecStart=/usr/bin/avahi-publish-address -R ccache.local <SERVER_IP>
+   Restart=on-failure
+   [Install]
+   WantedBy=redis-server.service
+   ```
+
+## HTTP/WebDAV Server (nginx)
+
+1. Install nginx with WebDAV support:
+   ```bash
+   apt install nginx-extras avahi-daemon avahi-utils
+   ```
+
+2. Copy `misc/nginx/ccache-webdav.conf` to `/etc/nginx/sites-available/ccache-webdav`,
+   then enable and prepare storage:
+   ```bash
+   cp misc/nginx/ccache-webdav.conf /etc/nginx/sites-available/ccache-webdav
+   ln -s /etc/nginx/sites-available/ccache-webdav /etc/nginx/sites-enabled/
+   mkdir -p /var/cache/ccache-webdav/ccache
+   chown -R www-data:www-data /var/cache/ccache-webdav
+   systemctl reload nginx
+   ```
+
+3. Verify:
+   ```bash
+   curl -X PUT -d "test" http://localhost:8088/ccache/test.txt
+   curl http://localhost:8088/ccache/test.txt
+   ```
+
+   **WARNING:** No authentication configured.
+   Use ONLY in a fully trusted private network.
+
+4. Publish DNS-SD service — copy `misc/avahi/ccache-webdav.service` to `/etc/avahi/services/`:
+   ```bash
+   cp misc/avahi/ccache-webdav.service /etc/avahi/services/
+   ```
+
+   Or use a systemd unit that ties the announcement to `nginx` lifetime:
+   ```bash
+   cp misc/systemd/ccache-avahi-webdav.service /etc/systemd/system/
+   systemctl enable --now ccache-avahi-webdav
+   ```
+
+## DNS SRV Records (for remote/hosted servers)
+
+Set `CCACHE_REMOTE_DOMAIN` on the client, then create DNS records.
+
+Redis backend:
+```text
+_ccache._tcp.example.com.  SRV  0 0 6379 ccache.example.com.
+_ccache._tcp.example.com.  TXT  "type=redis"
+```
+
+HTTP/WebDAV backend:
+```text
+_ccache._tcp.example.com.  SRV  0 0 8088 ccache.example.com.
+_ccache._tcp.example.com.  TXT  "type=http" "path=/ccache/"
+```
+
+## Client Requirements for mDNS
+
+Install one of the following for `.local` hostname resolution:
+
+- **libnss-resolve** (systemd-resolved):
+  ```bash
+  apt install libnss-resolve
+  ```
+  `/etc/nsswitch.conf`: `hosts: files resolve [!UNAVAIL=return] dns myhostname`
+
+- **libnss-mdns** (standalone):
+  ```bash
+  apt install libnss-mdns
+  ```
+  `/etc/nsswitch.conf`: `hosts: files mdns4_minimal [NOTFOUND=return] dns myhostname`