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

# 1. Build and install
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
sudo useradd -r -s /bin/false gemini
sudo usermod -a -G ssl-cert gemini
sudo mkdir -p /etc/pollux /var/www/example.com
sudo chown -R gemini:gemini /var/www/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/

# 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

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

Certificate Setup

Let's Encrypt (Recommended)

# Install certbot
sudo apt install certbot  # Ubuntu/Debian
# OR
sudo dnf install certbot  # Fedora/RHEL

# Get certificate
sudo certbot certonly --standalone -d example.com

# Verify permissions
ls -la /etc/letsencrypt/live/example.com/
# Should show fullchain.pem and privkey.pem

Self-Signed (Development Only)

# Generate certificates
openssl req -x509 -newkey rsa:4096 \
  -keyout /etc/pollux/key.pem \
  -out /etc/pollux/cert.pem \
  -days 365 -nodes \
  -subj "/CN=example.com"

# Set permissions
sudo chown gemini:gemini /etc/pollux/*.pem
sudo chmod 644 /etc/pollux/cert.pem
sudo chmod 600 /etc/pollux/key.pem

User and Directory Setup

# Create service user
sudo useradd -r -s /bin/false gemini

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

# Create directories
sudo mkdir -p /etc/pollux /var/www/example.com
sudo chown -R gemini:gemini /var/www/example.com

Configuration

Edit /etc/pollux/config.toml:

root = "/var/www/example.com"
cert = "/etc/letsencrypt/live/example.com/fullchain.pem"
key = "/etc/letsencrypt/live/example.com/privkey.pem"
bind_host = "0.0.0.0"
hostname = "example.com"
port = 1965
max_concurrent_requests = 1000
log_level = "info"

Content Setup

# Copy your Gemini files
sudo cp -r gemini-content/* /var/www/example.com/

# Set permissions
sudo chown -R gemini:gemini /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 {} \;

Service Installation

# 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

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

Verification

# 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

# Check certificate access
sudo -u gemini cat /etc/letsencrypt/live/example.com/fullchain.pem

# Check content access
sudo -u gemini ls -la /var/www/example.com/

Port Issues

# Check if port is in use
sudo netstat -tlnp | grep :1965

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

Certificate Issues

# 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
• 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

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:

# 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

# Restart server to load new certificates
sudo systemctl restart pollux

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

Upgrading

# 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