Static file server for the gemini protocol

Find a file

Jeena 3e490d85ef Implement integration tests using system temp directory - Move tests to use std::env::temp_dir() instead of ./tmp - Generate test certificates on-demand with openssl - Create isolated test environments with automatic cleanup - Add comprehensive config validation integration tests - Temporarily simplify rate limiting test (complex TLS testing deferred) - Tests now work out-of-the-box for fresh repository clones - Run tests sequentially to avoid stderr mixing in parallel execution		2026-01-16 23:26:26 +00:00
dist	Remove complex SIGHUP reload feature, use simple restart instead	2026-01-16 22:09:51 +00:00
src	Implement comprehensive config validation with graceful error handling	2026-01-16 22:21:50 +00:00
tests	Implement integration tests using system temp directory	2026-01-16 23:26:26 +00:00
.gitignore	Refine repository structure	2026-01-15 08:31:43 +09:00
AGENTS.md	Implement rate limiting with 41 responses and comprehensive logging	2026-01-16 06:00:18 +00:00
BACKLOG.md	Mark graceful config validation as completed in BACKLOG.md	2026-01-16 22:22:03 +00:00
Cargo.toml	Fix logging format: use request path instead of file path, clean timestamp	2026-01-16 11:34:38 +00:00
README.md	Document Python dependency and make integration tests conditional	2026-01-16 22:55:34 +00:00

README.md

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"
host = "gemini.example.com"
port = 1965
log_level = "info"

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

Or specify options directly (overrides config):

./pollux --root /path/to/static/files --cert cert.pem --key key.pem --host yourdomain.com --port 1965

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: Path to config file (default /etc/pollux/config.toml)
--root: Directory to serve files from (required)
--cert: Path to certificate file (required)
--key: Path to private key file (required)
--host: Hostname for validation (required)
--port: Port to listen on (default 1965)

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.