Jeena ad84bf187d Document Python dependency and make integration tests conditional

- Update README.md to mention Python 3 requirement for integration tests
- Make rate limiting test skip gracefully if Python 3 is not available
- Move and rename test helper script to tests/gemini_test_client.py
- Update test to use new script path
- Improve test documentation and error handling

2026-01-16 22:55:34 +00:00

2.2 KiB

Raw Blame History

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.

2.2 KiB Raw Blame History