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

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.

# 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

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

# Global settings
bind_host = "0.0.0.0"
port = 1965
max_concurrent_requests = 1000

# Host configuration
["example.com"]
root = "/var/gemini"
cert = "/etc/pollux/tls/cert.pem"
key = "/etc/pollux/tls/key.pem"

Logging Configuration

Pollux uses structured logging with the tracing crate. Configure log levels using the RUST_LOG environment variable:

# Set log level before starting the service
export RUST_LOG=info
sudo systemctl start pollux

# Or for debugging
export RUST_LOG=pollux=debug
sudo systemctl restart pollux

# Available levels: error, warn, info, debug, trace

Content Setup

# 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

# 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

# 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 pollux cat /etc/pollux/tls/cert.pem

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

Port Issues

# 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

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

Logging is configured via the RUST_LOG environment variable (see Logging Configuration section).

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