Pollux - A Simple Gemini Server

Pollux is a lightweight Gemini server for serving static files securely. It supports TLS, hostname validation, and basic directory serving.

Requirements

Rust 1.70+ and Cargo.

Building

Clone or download the source, then run:

cargo build --release

This produces the target/release/pollux binary.

Running

Create a config file at /etc/pollux/config.toml or use --config to specify a path:

root = "/path/to/static/files"
cert = "/path/to/cert.pem"
key = "/path/to/key.pem"
bind_host = "0.0.0.0"
hostname = "gemini.example.com"
port = 1965
log_level = "info"
max_concurrent_requests = 1000

Development Setup

Quick Start with Self-Signed Certs

mkdir -p tmp
openssl req -x509 -newkey rsa:2048 \
  -keyout tmp/key.pem \
  -out tmp/cert.pem \
  -days 365 \
  -nodes \
  -subj "/CN=localhost"

Update config.toml:

cert = "tmp/cert.pem"
key = "tmp/key.pem"

Run the server:

./pollux --config /path/to/config.toml

Access with a Gemini client like Lagrange at gemini://yourdomain.com/.

Development Notes

• These certificates are for local testing only
• Browsers will show security warnings with self-signed certs
• Certificates in the dev/ directory are gitignored for security

Options

• --config (-C): Path to config file (default /etc/pollux/config.toml)
• --test-processing-delay (debug builds only): Add delay before processing requests (seconds) - for testing rate limiting

Certificate Management

• Never commit certificate files to version control
• Use development certificates only for local testing
• Production certificates should be obtained via Let's Encrypt or your CA

Testing

Run cargo test for the full test suite, which includes integration tests that require Python 3.

Note: Integration tests use Python 3 for Gemini protocol validation. If Python 3 is not available, integration tests will be skipped automatically.