142 lines
3.7 KiB
Markdown
142 lines
3.7 KiB
Markdown
# Circles WebSocket Server Binary
|
|
|
|
A command-line WebSocket server for hosting Circles with authentication and TLS support.
|
|
|
|
## Binary: Server
|
|
|
|
### Installation
|
|
|
|
Build the binary:
|
|
```bash
|
|
cargo build --release
|
|
```
|
|
|
|
### Usage
|
|
|
|
```bash
|
|
# Basic usage - starts server on localhost:8443
|
|
cargo run
|
|
|
|
# Custom host and port
|
|
cargo run -- --host 0.0.0.0 --port 9000
|
|
|
|
# Enable authentication
|
|
cargo run -- --auth
|
|
|
|
# Enable TLS/WSS with certificates
|
|
cargo run -- --tls --cert /path/to/cert.pem --key /path/to/key.pem
|
|
|
|
# Use separate TLS port
|
|
cargo run -- --tls --cert cert.pem --key key.pem --tls-port 8444
|
|
|
|
# Custom Redis URL
|
|
cargo run -- --redis-url redis://localhost:6379/1
|
|
|
|
# Increase verbosity
|
|
cargo run -- -v # Debug logging
|
|
cargo run -- -vv # Full debug logging
|
|
cargo run -- -vvv # Trace logging
|
|
```
|
|
|
|
### Command-Line Options
|
|
|
|
| Option | Short | Default | Description |
|
|
|--------|-------|---------|-------------|
|
|
| `--host` | `-H` | `127.0.0.1` | Server bind address |
|
|
| `--port` | `-p` | `8443` | Server port |
|
|
| `--redis-url` | | `redis://127.0.0.1/` | Redis connection URL |
|
|
| `--auth` | | `false` | Enable secp256k1 authentication |
|
|
| `--tls` | | `false` | Enable TLS/WSS support |
|
|
| `--cert` | | | Path to TLS certificate file (required with --tls) |
|
|
| `--key` | | | Path to TLS private key file (required with --tls) |
|
|
| `--tls-port` | | | Separate port for TLS connections |
|
|
| `--verbose` | `-v` | | Increase verbosity (stackable) |
|
|
|
|
### Configuration Examples
|
|
|
|
#### Development Server
|
|
```bash
|
|
# Simple development server
|
|
cargo run
|
|
|
|
# Development with authentication
|
|
cargo run -- --auth
|
|
```
|
|
|
|
#### Production Server
|
|
```bash
|
|
# Production with TLS and authentication
|
|
cargo run -- \
|
|
--host 0.0.0.0 \
|
|
--port 8080 \
|
|
--tls \
|
|
--tls-port 8443 \
|
|
--cert /etc/ssl/certs/circles.pem \
|
|
--key /etc/ssl/private/circles.key \
|
|
--auth \
|
|
--redis-url redis://redis-server:6379/0
|
|
```
|
|
|
|
#### Custom Redis Configuration
|
|
```bash
|
|
# Connect to remote Redis with authentication
|
|
cargo run -- --redis-url redis://username:password@redis.example.com:6379/2
|
|
```
|
|
|
|
### Logging Levels
|
|
|
|
The server supports multiple verbosity levels:
|
|
|
|
- **Default** (`cargo run`): Shows only warnings and circle_ws_lib info
|
|
- **Debug** (`-v`): Shows debug info for circle_ws_lib, info for actix
|
|
- **Full Debug** (`-vv`): Shows debug for all components
|
|
- **Trace** (`-vvv+`): Shows trace-level logging for everything
|
|
|
|
### TLS/SSL Configuration
|
|
|
|
When using `--tls`, you must provide both certificate and key files:
|
|
|
|
```bash
|
|
# Generate self-signed certificate for testing
|
|
openssl req -x509 -newkey rsa:4096 -keyout key.pem -out cert.pem -days 365 -nodes
|
|
|
|
# Run server with TLS
|
|
cargo run -- --tls --cert cert.pem --key key.pem
|
|
```
|
|
|
|
### Authentication
|
|
|
|
When `--auth` is enabled, clients must complete secp256k1 authentication:
|
|
1. Client connects to WebSocket
|
|
2. Server sends authentication challenge
|
|
3. Client signs challenge with private key
|
|
4. Server verifies signature and grants access
|
|
|
|
### Redis Integration
|
|
|
|
The server uses Redis for:
|
|
- Session management
|
|
- Message persistence
|
|
- Cross-instance communication (in clustered deployments)
|
|
|
|
Supported Redis URL formats:
|
|
- `redis://localhost/` - Local Redis, default database
|
|
- `redis://localhost:6379/1` - Local Redis, database 1
|
|
- `redis://user:pass@host:port/db` - Authenticated Redis
|
|
- `rediss://host:port/` - Redis with TLS
|
|
|
|
### Error Handling
|
|
|
|
The server provides clear error messages for common configuration issues:
|
|
- Missing TLS certificate or key files
|
|
- Invalid Redis connection URLs
|
|
- Port binding failures
|
|
- Authentication setup problems
|
|
|
|
### Dependencies
|
|
|
|
- `actix-web`: Web server framework
|
|
- `tokio-tungstenite`: WebSocket implementation
|
|
- `redis`: Redis client
|
|
- `rustls`: TLS implementation
|
|
- `clap`: Command-line argument parsing |