# Configuration Guide
Complete guide to configuring V-Queue server.
## Configuration Methods
V-Queue server can be configured through:
1. **Configuration file** (TOML format)
2. **Command-line arguments** (override file settings)
3. **Environment variables** (future enhancement)
### Priority Order
Settings are applied in this order (highest to lowest priority):
1. Command-line arguments
2. Configuration file
3. Default values
## Configuration File
### File Location
By default, the server looks for `v-queue-server.toml` in:
1. Current working directory
2. Path specified with `--config` flag
### File Format
Configuration uses TOML format:
```toml
# v-queue-server.toml
# Server bind address and port
bind_address = "127.0.0.1:9093"
# Directory for queue data storage
data_directory = "./queues"
# Logging level: debug, info, warn, error
log_level = "info"
# Maximum message size in bytes (default: 1MB)
max_message_size = 1048576
# Default batch size for consumers
default_batch_size = 100
# Enable authentication
auth_enabled = true
# User accounts (username = "password")
[users]
admin = "changeme"
consumer1 = "password123"
readonly = "readonly_pass"
```
### Configuration Options
#### bind_address
Network address and port to listen on.
- **Type**: String
- **Default**: `"127.0.0.1:9093"`
- **Examples**:
- `"0.0.0.0:9093"` - Listen on all interfaces
- `"127.0.0.1:8080"` - Localhost only, port 8080
- `"192.168.1.100:9093"` - Specific IP
**Security Note**: Binding to `0.0.0.0` exposes the server to all network interfaces. Use with caution and ensure authentication is enabled.
#### data_directory
Path where queue data files are stored.
- **Type**: String
- **Default**: `"./queues"`
- **Examples**:
- `"./queues"` - Relative path
- `"/var/lib/vqueue/data"` - Absolute path
- `"/mnt/ssd/queues"` - Custom mount point
**Requirements**:
- Directory must be writable
- Sufficient disk space
- Fast storage recommended (SSD preferred)
#### log_level
Logging verbosity level.
- **Type**: String
- **Default**: `"info"`
- **Options**: `"debug"`, `"info"`, `"warn"`, `"error"`
**Levels**:
- `debug` - Detailed debugging information
- `info` - Normal operational messages
- `warn` - Warning messages
- `error` - Error messages only
#### max_message_size
Maximum allowed message size in bytes.
- **Type**: Integer
- **Default**: `1048576` (1MB)
- **Range**: 1 to 2,147,483,647
- **Note**: Currently not enforced by the server (validation happens in the core v_queue library).
#### default_batch_size
Default number of messages to return in consumer requests.
- **Type**: Integer
- **Default**: `100`
- **Range**: 1 to 10,000
- **Note**: Currently not used by the server (default is 1). Can be overridden per request with `max_messages` parameter.
#### auth_enabled
Enable or disable authentication.
- **Type**: Boolean
- **Default**: `true`
- **Values**: `true`, `false`
When enabled, all API endpoints except `/health` require authentication.
#### users
User accounts for authentication (when `auth_enabled = true`).
- **Type**: TOML table
- **Format**: `username = "password"`
- **Example**:
```toml
[users]
admin = "strong_password_123"
app1 = "app1_secret"
readonly = "readonly_pass"
```
**Security Notes**:
- Passwords stored in plain text (use file permissions)
- Use strong passwords
- Limit file access: `chmod 600 v-queue-server.toml`
- Consider using HTTPS proxy for production
## Command-Line Arguments
Override configuration file settings:
```bash
v-queue-server [OPTIONS]
```
### Available Options
#### --config, -c
Path to configuration file.
```bash
v-queue-server --config /etc/vqueue/server.toml
```
Default: `v-queue-server.toml`
#### --bind, -b
Override bind address.
```bash
v-queue-server --bind 0.0.0.0:8080
```
Overrides `bind_address` from config file.
#### --data-dir, -d
Override data directory.
```bash
v-queue-server --data-dir /var/lib/vqueue/data
```
Overrides `data_directory` from config file.
#### --log-level, -l
Override log level.
```bash
v-queue-server --log-level debug
```
Overrides `log_level` from config file.
#### --no-auth
Disable authentication.
```bash
v-queue-server --no-auth
```
Overrides `auth_enabled` from config file (sets to `false`).
Useful for development and testing.
### Combining Options
You can combine multiple options:
```bash
v-queue-server \
--config /etc/vqueue/production.toml \
--bind 0.0.0.0:9093 \
--log-level info
```
## Configuration Examples
### Development Configuration
```toml
# dev-config.toml
bind_address = "127.0.0.1:9093"
data_directory = "./dev-queues"
log_level = "debug"
auth_enabled = false
max_message_size = 1048576
default_batch_size = 10
```
Run:
```bash
v-queue-server --config dev-config.toml
```
### Production Configuration
```toml
# production.toml
bind_address = "0.0.0.0:9093"
data_directory = "/var/lib/vqueue/data"
log_level = "warn"
auth_enabled = true
max_message_size = 10485760 # 10MB
default_batch_size = 100
[users]
admin = "strong_random_password_here"
service1 = "another_strong_password"
service2 = "yet_another_password"
```
Secure the file:
```bash
sudo chown vqueue:vqueue /etc/vqueue/production.toml
sudo chmod 600 /etc/vqueue/production.toml
```
Run:
```bash
v-queue-server --config /etc/vqueue/production.toml
```
### High-Throughput Configuration
```toml
# high-throughput.toml
bind_address = "0.0.0.0:9093"
data_directory = "/mnt/nvme/vqueue" # Fast SSD
log_level = "error" # Minimal logging overhead
auth_enabled = false # No auth overhead (use network isolation)
max_message_size = 524288 # 512KB
default_batch_size = 500 # Large batches
```
### Testing Configuration
```toml
# test-config.toml
bind_address = "127.0.0.1:9999"
data_directory = "/tmp/vqueue-test"
log_level = "debug"
auth_enabled = true
max_message_size = 1024
default_batch_size = 5
[users]
test_user = "test_password"
```
## Authentication Configuration
### Enabling Authentication
Set `auth_enabled = true` and define users:
```toml
auth_enabled = true
[users]
admin = "admin_password"
producer = "producer_password"
consumer = "consumer_password"
```
### Disabling Authentication
Option 1 - In config file:
```toml
auth_enabled = false
```
Option 2 - Command line:
```bash
v-queue-server --no-auth
```
### User Management
#### Adding Users
Edit config file and add to `[users]` section:
```toml
[users]
newuser = "newpassword"
```
Restart server to apply changes.
#### Removing Users
Remove line from config file and restart.
#### Changing Passwords
Update password in config file and restart:
```toml
[users]
admin = "new_password_here"
```
### Security Recommendations
1. **File Permissions**:
```bash
chmod 600 v-queue-server.toml
chown vqueue:vqueue v-queue-server.toml
```
2. **Strong Passwords**:
- Minimum 16 characters
- Mix of letters, numbers, symbols
- Use password generator
3. **Network Security**:
- Use firewall to restrict access
- Consider HTTPS reverse proxy (nginx, caddy)
- VPN for remote access
4. **Principle of Least Privilege**:
- Separate accounts for different services
- Read-only accounts for consumers if possible
## Environment-Specific Configurations
### Development
```toml
bind_address = "127.0.0.1:9093"
data_directory = "./queues"
log_level = "debug"
auth_enabled = false
```
### Staging
```toml
bind_address = "0.0.0.0:9093"
data_directory = "/var/lib/vqueue/staging"
log_level = "info"
auth_enabled = true
[users]
staging_app = "staging_password"
```
### Production
```toml
bind_address = "0.0.0.0:9093"
data_directory = "/var/lib/vqueue/production"
log_level = "warn"
auth_enabled = true
[users]
prod_service1 = "strong_password_1"
prod_service2 = "strong_password_2"
```
## Monitoring Configuration
### Logging Output
Logs go to stderr by default. Redirect for persistent logging:
```bash
With systemd:
```ini
[Service]
StandardOutput=append:/var/log/vqueue/server.log
StandardError=append:/var/log/vqueue/server.log
```
### Log Rotation
Use logrotate:
```
# /etc/logrotate.d/vqueue
/var/log/vqueue/server.log {
daily
rotate 7
compress
delaycompress
missingok
notifempty
postrotate
systemctl reload v-queue-server
endscript
}
```
## Validation
### Testing Configuration
Test config without starting server:
```bash
v-queue-server --config test.toml --help
```
If config file has errors, they'll be displayed.
### Configuration Checklist
- [ ] Bind address accessible from clients
- [ ] Data directory exists and is writable
- [ ] Sufficient disk space available
- [ ] Log level appropriate for environment
- [ ] Authentication enabled for production
- [ ] Strong passwords used
- [ ] Config file permissions secured (600)
- [ ] Firewall rules configured
- [ ] Backup strategy in place
## Next Steps
- [API Reference](05-api-reference.md)
- [Authentication Details](06-authentication.md)
- [Performance Tuning](08-performance.md)