feat: Implement virtual hosting for multi-domain Gemini server

- Add hostname-based request routing for multiple capsules per server
- Parse virtual host configs from TOML sections ([hostname])
- Implement per-host certificate and content isolation
- Add comprehensive virtual host testing and validation
- Update docs and examples for multi-host deployments

This enables Pollux to serve multiple Gemini domains from one instance,
providing the foundation for multi-tenant Gemini hosting.

dist/INSTALL.md

@@ -16,20 +16,23 @@ This guide covers installing and configuring the Pollux Gemini server for produc
 cargo build --release
 sudo cp target/release/pollux /usr/local/bin/
 
-# 2. Get certificates
-sudo certbot certonly --standalone -d example.com
-
-# 3. Create directories and user
+# 2. Create directories and user
 sudo useradd -r -s /bin/false pollux
-sudo usermod -a -G ssl-cert pollux
-sudo mkdir -p /etc/pollux /var/www/example.com
-sudo chown -R pollux:pollux /var/www/example.com
+sudo mkdir -p /etc/pollux/tls /var/gemini
+sudo chown -R pollux:pollux /var/gemini
+
+# 3. Generate certificates
+sudo -u pollux openssl req -x509 -newkey rsa:4096 \
+  -keyout /etc/pollux/tls/key.pem \
+  -out /etc/pollux/tls/cert.pem \
+  -days 365 -nodes \
+  -subj "/CN=example.com"
 
 # 4. Install config
 sudo cp dist/config.toml /etc/pollux/
 
 # 5. Add your Gemini content
-sudo cp -r your-content/* /var/www/example.com/
+sudo cp -r your-content/* /var/gemini/
 
 # 6. Install and start service
 sudo cp dist/pollux.service /etc/systemd/system/
@@ -57,24 +60,23 @@ sudo cp target/release/pollux /usr/local/bin/
 
 #### Certificate Setup
 
-**For Production:** Obtain certificates from your preferred Certificate Authority and place them in `/etc/pollux/`. Ensure they are readable by the pollux user.
+**For Production:** Obtain certificates from your preferred Certificate Authority and place them in `/etc/pollux/tls/`. Ensure they are readable by the pollux user.
 
 **For Development/Testing:** Generate self-signed certificates (see Quick Start section).
 
-**Note:** Let's Encrypt certificates can be used but their installation and permission setup is beyond the scope of this documentation.
+**Note:** Let's Encrypt certificates can be used - place them under `/etc/letsencrypt/live/` and update your config accordingly.
 
 ```bash
 # Generate certificates
-openssl req -x509 -newkey rsa:4096 \
-  -keyout /etc/pollux/key.pem \
-  -out /etc/pollux/cert.pem \
+sudo -u pollux openssl req -x509 -newkey rsa:4096 \
+  -keyout /etc/pollux/tls/key.pem \
+  -out /etc/pollux/tls/cert.pem \
   -days 365 -nodes \
   -subj "/CN=example.com"
 
-# Set permissions
-sudo chown pollux:pollux /etc/pollux/*.pem
-sudo chmod 644 /etc/pollux/cert.pem
-sudo chmod 600 /etc/pollux/key.pem
+# Set permissions (already correct when run as pollux user)
+sudo chmod 644 /etc/pollux/tls/cert.pem
+sudo chmod 600 /etc/pollux/tls/key.pem
 ```
 
 ### User and Directory Setup
@@ -89,8 +91,8 @@ sudo usermod -a -G ssl-cert pollux    # Ubuntu/Debian
 sudo usermod -a -G certbot pollux     # Some systems
 
 # Create directories
-sudo mkdir -p /etc/pollux /var/www/example.com
-sudo chown -R pollux:pollux /var/www/example.com
+sudo mkdir -p /etc/pollux/tls /var/gemini
+sudo chown -R pollux:pollux /var/gemini
 ```
 
 ### Configuration
@@ -98,26 +100,29 @@ sudo chown -R pollux:pollux /var/www/example.com
 Edit `/etc/pollux/config.toml`:
 
 ```toml
-root = "/var/www/example.com"
-cert = "/etc/pollux/cert.pem"
-key = "/etc/pollux/key.pem"
+# Global settings
 bind_host = "0.0.0.0"
-hostname = "example.com"
 port = 1965
 max_concurrent_requests = 1000
 log_level = "info"
+
+# Host configuration
+["example.com"]
+root = "/var/gemini"
+cert = "/etc/pollux/tls/cert.pem"
+key = "/etc/pollux/tls/key.pem"
 ```
 
 ### Content Setup
 
 ```bash
 # Copy your Gemini files
-sudo cp -r gemini-content/* /var/www/example.com/
+sudo cp -r gemini-content/* /var/gemini/
 
 # Set permissions
-sudo chown -R pollux:pollux /var/www/example.com
-sudo find /var/www/example.com -type f -exec chmod 644 {} \;
-sudo find /var/www/example.com -type d -exec chmod 755 {} \;
+sudo chown -R pollux:pollux /var/gemini
+sudo find /var/gemini -type f -exec chmod 644 {} \;
+sudo find /var/gemini -type d -exec chmod 755 {} \;
 ```
 
 ### Service Installation
@@ -128,7 +133,9 @@ sudo cp dist/pollux.service /etc/systemd/system/
 
 # If your paths differ, edit the service file
 sudo editor /etc/systemd/system/pollux.service
-# Update ReadOnlyPaths to match your config
+# Update ReadOnlyPaths to match your config:
+# - /etc/pollux for config and TLS certificates
+# - /var/gemini for your content root
 
 # Enable and start
 sudo systemctl daemon-reload
@@ -154,10 +161,10 @@ openssl s_client -connect example.com:1965 -servername example.com <<< "gemini:/
 ### Permission Issues
 ```bash
 # Check certificate access
-sudo -u pollux cat /etc/pollux/cert.pem
+sudo -u pollux cat /etc/pollux/tls/cert.pem
 
 # Check content access
-sudo -u pollux ls -la /var/www/example.com/
+sudo -u pollux ls -la /var/gemini/
 ```
 
 ### Port Issues
@@ -182,13 +189,12 @@ sudo systemctl reload pollux
 
 See `config.toml` for all available options. Key settings:
 
-- `root`: Directory containing your .gmi files
-- `cert`/`key`: TLS certificate paths
-- `bind_host`: IP/interface to bind to
-- `hostname`: Domain name for URI validation
-- `port`: Listen port (1965 is standard)
-- `max_concurrent_requests`: Connection limit
-- `log_level`: Logging verbosity
+- `root`: Directory containing your .gmi files (per host section)
+- `cert`/`key`: TLS certificate paths (per host section)
+- `bind_host`: IP/interface to bind to (global)
+- `port`: Listen port (1965 is standard, per host override possible)
+- `max_concurrent_requests`: Connection limit (global)
+- `log_level`: Logging verbosity (global, per host override possible)
 
 ## Certificate Management