pollux/dist/INSTALL.md

# Installing Pollux Gemini Server

This guide covers installing and configuring the Pollux Gemini server for production use.

## Prerequisites

- Linux system with systemd
- Rust toolchain (for building from source)
- Domain name with DNS configured
- Let's Encrypt account (for certificates)

## Quick Start

```bash
# 1. Build and install
cargo build --release
sudo cp target/release/pollux /usr/local/bin/

# 2. Create directories and user
sudo useradd -r -s /bin/false pollux
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/gemini/

# 6. Install and start service
sudo cp dist/pollux.service /etc/systemd/system/
sudo systemctl daemon-reload
sudo systemctl enable pollux
sudo systemctl start pollux

# 7. Check status
sudo systemctl status pollux
sudo journalctl -u pollux -f
```

## Detailed Installation

### Building from Source

```bash
git clone https://github.com/yourusername/pollux.git
cd pollux
cargo build --release
sudo cp target/release/pollux /usr/local/bin/
```

### Certificate Setup

#### Certificate Setup

**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 - place them under `/etc/letsencrypt/live/` and update your config accordingly.

```bash
# 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"

# 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

```bash
# Create service user
sudo useradd -r -s /bin/false pollux

# Add to certificate group (varies by distro)
sudo usermod -a -G ssl-cert pollux    # Ubuntu/Debian
# OR
sudo usermod -a -G certbot pollux     # Some systems

# Create directories
sudo mkdir -p /etc/pollux/tls /var/gemini
sudo chown -R pollux:pollux /var/gemini
```

### Configuration

Edit `/etc/pollux/config.toml`:

```toml
# Global settings
bind_host = "0.0.0.0"
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/gemini/

# Set permissions
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

```bash
# Install service file
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:
# - /etc/pollux for config and TLS certificates
# - /var/gemini for your content root

# Enable and start
sudo systemctl daemon-reload
sudo systemctl enable pollux
sudo systemctl start pollux
```

### Verification

```bash
# Check service status
sudo systemctl status pollux

# View logs
sudo journalctl -u pollux -f

# Test connection
openssl s_client -connect example.com:1965 -servername example.com <<< "gemini://example.com/\r\n" | head -1
```

## Troubleshooting

### Permission Issues
```bash
# Check certificate access
sudo -u pollux cat /etc/pollux/tls/cert.pem

# Check content access
sudo -u pollux ls -la /var/gemini/
```

### Port Issues
```bash
# Check if port is in use
sudo netstat -tlnp | grep :1965

# Test binding
sudo -u pollux /usr/local/bin/pollux  # Should show startup messages
```

### Certificate Issues
```bash
# Renew certificates
sudo certbot renew

# Reload service after cert renewal
sudo systemctl reload pollux
```

## Configuration Options

See `config.toml` for all available options. Key settings:

- `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

The server uses standard systemd restart for certificate updates. Restart time is less than 1 second.

### Let's Encrypt Integration

For automatic certificate renewal with certbot:

```bash
# Create post-renewal hook
sudo tee /etc/letsencrypt/renewal-hooks/post/restart-pollux.sh > /dev/null << 'EOF'
#!/bin/bash
# Restart Pollux after Let's Encrypt certificate renewal

systemctl restart pollux
logger -t certbot-pollux-restart "Restarted pollux after certificate renewal"
EOF

# Make it executable
sudo chmod +x /etc/letsencrypt/renewal-hooks/post/restart-pollux.sh

# Test the hook
sudo /etc/letsencrypt/renewal-hooks/post/restart-pollux.sh
```

### Manual Certificate Update

```bash
# Restart server to load new certificates
sudo systemctl restart pollux

# Check restart in logs
sudo journalctl -u pollux -f
```

## Upgrading

```bash
# Stop service
sudo systemctl stop pollux

# Install new binary
sudo cp target/release/pollux /usr/local/bin/

# Start service
sudo systemctl start pollux
```

## Security Notes

- Certificates are read-only by the service user
- Content directory is read-only
- No temporary file access
- Systemd security hardening applied
- Private keys have restricted permissions
- URI validation prevents domain confusion attacks