# LuckDB Server CLI
A comprehensive command-line interface for running LuckDB servers with configuration options, logging, and signal handling.
## Installation
The CLI tool is included as part of the LuckDB crate. After building LuckDB, you can find the binary at:
```bash
# Build the project
cargo build --release
# The CLI binary will be at:
# Linux/macOS: target/release/luckdb-server-cli
# Windows: target/release/luckdb-server-cli.exe
```
## Quick Start
### Basic Usage
```bash
# Start server with default settings
luckdb-server-cli
# Start server on custom address and port
luckdb-server-cli --address 127.0.0.1 --port 27017
# Start server with encryption
luckdb-server-cli --encrypt --password "your_secure_password"
# Start server with authentication
luckdb-server-cli --auth --username admin --password "auth_password"
# Start server with data persistence
luckdb-server-cli --storage ./data
```
### Using Configuration Files
```bash
# Create a sample configuration file
luckdb-server-cli config --output config.toml --config-type prod
# Start server using configuration file
luckdb-server-cli --config config.toml
# Override config file settings with command line arguments
luckdb-server-cli --config config.toml --port 27018 --log-level debug
```
## Command Line Options
### Global Options
| `--config` | `-c` | Path to TOML configuration file | None |
| `--address` | `-a` | Server bind address | 127.0.0.1 |
| `--port` | `-p` | Server port | 27017 |
| `--storage` | `-s` | Storage path for database files | In-memory |
| `--help` | `-h` | Print help information | - |
| `--version` | `-V` | Print version information | - |
### Security Options
| `--encrypt` | Enable AES-256 encryption for data at rest |
| `--password` | Encryption password (required with --encrypt) |
| `--auth` | Enable username/password authentication |
| `--username` | Authentication username (required with --auth) |
| `--auth-password` | Authentication password (required with --auth) |
### Performance and Operations Options
| `--auto-save` | Auto-save interval in seconds |
| `--max-backup-files` | Maximum number of backup files to keep |
| `--dev` | Enable development mode (in-memory storage, debug logging) |
### Logging Options
| `--log-level` | Log level (error, warn, info, debug, trace) | info |
| `--log-file` | Log file path (default: stdout/stderr) | - |
## Subcommands
### config
Create a sample configuration file for different environments.
```bash
# Create development configuration
luckdb-server-cli config --output dev-config.toml --config-type dev
# Create production configuration
luckdb-server-cli config --output prod-config.toml --config-type prod
# Create test configuration
luckdb-server-cli config --output test-config.toml --config-type test
```
#### Configuration Types
- **dev**: Development configuration with in-memory storage, debug logging, and relaxed security
- **prod**: Production configuration with encryption, authentication, file logging, and enhanced security
- **test**: Test configuration with minimal logging, no encryption, and no authentication
### version
Print version information.
```bash
luckdb-server-cli version
```
## Configuration Files
Configuration files use TOML format with a `[luckdb]` section:
```toml
[luckdb]
# Storage path for database files (comment out for in-memory)
storage_path = "./data"
# Enable encryption (false for development)
encryption_enabled = true
encryption_password = "your_secure_password"
# Authentication
auth_username = "admin"
auth_password = "your_auth_password"
# Server address
server_address = "127.0.0.1:27017"
# Auto-save interval (seconds)
auto_save_interval_seconds = 300
# Maximum backup files to keep
max_backup_files = 10
# Logging
log_level = "info"
log_file = "./luckdb.log"
```
### Environment Variables
Configuration values can be overridden with environment variables:
- `LUCKDB_STORAGE_PATH`
- `LUCKDB_ENCRYPTION_ENABLED`
- `LUCKDB_ENCRYPTION_PASSWORD`
- `LUCKDB_AUTH_USERNAME`
- `LUCKDB_AUTH_PASSWORD`
- `LUCKDB_SERVER_ADDRESS`
- `LUCKDB_AUTO_SAVE_INTERVAL_SECONDS`
- `LUCKDB_MAX_BACKUP_FILES`
```bash
export LUCKDB_ENCRYPTION_PASSWORD="secure_password"
export LUCKDB_LOG_LEVEL="debug"
luckdb-server-cli
```
## Usage Examples
### Development Environment
```bash
# Quick development server
luckdb-server-cli --dev
# Development with file persistence
luckdb-server-cli --storage ./dev_data --log-level debug
# Development with encryption
luckdb-server-cli --dev --encrypt --password "dev_password"
```
### Production Environment
```bash
# Using configuration file (recommended)
luckdb-server-cli --config production.toml
# Manual production setup
luckdb-server-cli \
--storage /var/lib/luckdb/data \
--encrypt \
--password "secure_encryption_password" \
--auth \
--username admin \
--auth-password "secure_auth_password" \
--log-file /var/log/luckdb/server.log \
--auto-save 300 \
--max-backup-files 30
```
### Testing Environment
```bash
# Test server with in-memory storage
luckdb-server-cli --dev --log-level error
# Test server with temporary storage
luckdb-server-cli --storage ./test_data --log-level error
```
## Signal Handling
The CLI tool supports graceful shutdown via interrupt signals:
- **SIGINT (Ctrl+C)**: Graceful shutdown
- **Double SIGINT**: Force shutdown
## Logging
The CLI uses structured logging with multiple output options:
### Log Levels
- `error`: Only error messages
- `warn`: Warning messages and above
- `info`: General information (default)
- `debug`: Debug information for development
- `trace`: Detailed trace information
### Log Output
- **Default**: stdout/stderr with colored output
- **File**: Write logs to specified file when `--log-file` is provided
- **Format**: Timestamp, level, target, and message
## Security Best Practices
### Production Deployment
1. **Use Configuration Files**: Store configuration in secure files, not command line arguments
2. **Environment Variables**: Use environment variables for sensitive values
3. **File Permissions**: Ensure proper file permissions on config files and log files
4. **Network Security**: Use firewall rules to restrict access to server ports
5. **Strong Passwords**: Use unique, strong passwords for encryption and authentication
### Example Secure Production Setup
```bash
# Create production config
luckdb-server-cli config --output /etc/luckdb/config.toml --config-type prod
# Edit the config file with secure passwords
vim /etc/luckdb/config.toml
# Set proper file permissions
chmod 600 /etc/luckdb/config.toml
chmod 755 /var/lib/luckdb
chmod 755 /var/log/luckdb
# Start server with configuration
sudo -u luckdb luckdb-server-cli --config /etc/luckdb/config.toml
```
## Troubleshooting
### Common Issues
1. **Port Already in Use**: Use `--port` to specify a different port
2. **Permission Denied**: Check file permissions for storage path and config file
3. **Invalid Configuration**: Use `luckdb-server-cli config --config-type dev` to create a valid template
4. **Encryption Password Lost**: Data cannot be recovered without encryption password
### Debug Mode
Use development mode for troubleshooting:
```bash
luckdb-server-cli --dev --log-level debug
```
### Configuration Validation
The CLI validates configuration and provides helpful error messages:
```bash
# This will show specific error about missing password
luckdb-server-cli --encrypt --config invalid.toml
```
## Integration Examples
### Docker
```dockerfile
FROM rust:1.70 as builder
WORKDIR /app
COPY . .
RUN cargo build --release
FROM debian:bookworm-slim
RUN apt-get update && apt-get install -y ca-certificates && rm -rf /var/lib/apt/lists/*
COPY --from=builder /app/target/release/luckdb-server-cli /usr/local/bin/
EXPOSE 27017
CMD ["luckdb-server-cli", "--config", "/etc/luckdb/config.toml"]
```
### Systemd Service
```ini
[Unit]
Description=LuckDB Server
After=network.target
[Service]
Type=simple
User=luckdb
Group=luckdb
ExecStart=/usr/local/bin/luckdb-server-cli --config /etc/luckdb/config.toml
Restart=always
RestartSec=5
[Install]
WantedBy=multi-user.target
```
## Contributing
To contribute to the CLI tool:
1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Test the CLI thoroughly
5. Submit a pull request
## License
This CLI tool is part of LuckDB and is licensed under the same MIT License.