Jeena
55fe47b172
- Remove custom logging module and init_logging function - Update main.rs to use tracing_subscriber with EnvFilter - Remove log_level from global config structure - Update documentation and tests to use RUST_LOG - Format long lines in config.rs and test files for better readability
270 lines
No EOL
6.2 KiB
Markdown
270 lines
No EOL
6.2 KiB
Markdown
# 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
|
|
|
|
```bash
|
|
# 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
|
|
|
|
```bash
|
|
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.
|
|
|
|
```bash
|
|
# 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
|
|
|
|
```bash
|
|
# 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`:
|
|
|
|
```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:
|
|
|
|
```bash
|
|
# 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
|
|
|
|
```bash
|
|
# 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
|
|
|
|
```bash
|
|
# 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
|
|
|
|
```bash
|
|
# 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
|
|
```bash
|
|
# Check certificate access
|
|
sudo -u pollux cat /etc/pollux/tls/cert.pem
|
|
|
|
# Check content access
|
|
sudo -u pollux ls -la /var/gemini/
|
|
```
|
|
|
|
### Port Issues
|
|
```bash
|
|
# 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
|
|
```bash
|
|
# 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:
|
|
|
|
```bash
|
|
# 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
|
|
|
|
```bash
|
|
# Restart server to load new certificates
|
|
sudo systemctl restart pollux
|
|
|
|
# Check restart in logs
|
|
sudo journalctl -u pollux -f
|
|
```
|
|
|
|
## Upgrading
|
|
|
|
```bash
|
|
# 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 |