Jeena
8fa30c2545
- Complete Gemini server implementation with logging - Add comprehensive documentation (README.md, AGENTS.md) - Implement certificate management guidelines - Add .gitignore for security and build artifacts - All unit tests passing (14/14) - Ready for production deployment
91 lines
No EOL
2.1 KiB
Markdown
91 lines
No EOL
2.1 KiB
Markdown
# 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:
|
|
|
|
```bash
|
|
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:
|
|
|
|
```toml
|
|
root = "/path/to/static/files"
|
|
cert = "certs/cert.pem"
|
|
key = "certs/key.pem"
|
|
host = "gemini.jeena.net"
|
|
port = 1965
|
|
log_level = "info"
|
|
```
|
|
|
|
## Certificate Setup
|
|
|
|
### Development
|
|
Generate self-signed certificates for local testing:
|
|
|
|
```bash
|
|
mkdir -p certs
|
|
openssl req -x509 -newkey rsa:2048 -keyout certs/key.pem -out certs/cert.pem -days 365 -nodes -subj "/CN=localhost"
|
|
```
|
|
|
|
Update `config.toml`:
|
|
```toml
|
|
cert = "certs/cert.pem"
|
|
key = "certs/key.pem"
|
|
```
|
|
|
|
### Production
|
|
Use Let's Encrypt for production:
|
|
|
|
```bash
|
|
sudo certbot certonly --standalone -d yourdomain.com
|
|
```
|
|
|
|
Then update config.toml paths to your certificate locations.
|
|
|
|
Run the server:
|
|
|
|
```bash
|
|
./pollux --config /path/to/config.toml
|
|
```
|
|
|
|
Or specify options directly (overrides config):
|
|
|
|
```bash
|
|
./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/`.
|
|
|
|
## 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)
|
|
|
|
## Security
|
|
|
|
Uses path validation to prevent directory traversal. Validate hostnames for production use.
|
|
|
|
### 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 unit tests. Fix warnings before commits. |