Add docs

docs/config/server.md

@@ -0,0 +1,470 @@
+# Server Configuration
+
+Complete reference for configuring the VaultLink sync server via `config.yml`.
+
+## Configuration File Format
+
+The server is configured using a YAML file passed as a command-line argument:
+
+```bash
+/app/sync_server /path/to/config.yml
+```
+
+## Complete Example
+
+```yaml
+database:
+  databases_directory_path: databases
+  max_connections_per_vault: 12
+  cursor_timeout_seconds: 60
+
+server:
+  host: 0.0.0.0
+  port: 3000
+  max_body_size_mb: 512
+  max_clients_per_vault: 256
+  response_timeout_seconds: 60
+
+users:
+  user_configs:
+  - name: admin
+    token: your-secure-random-token
+    vault_access:
+      type: allow_access_to_all
+  - name: alice
+    token: alice-token
+    vault_access:
+      type: allow_list
+      allowed:
+        - personal
+        - shared
+  - name: bob
+    token: bob-token
+    vault_access:
+      type: deny_list
+      denied:
+        - restricted
+
+logging:
+  log_directory: logs
+  log_rotation: 7days
+```
+
+## Database Section
+
+### `databases_directory_path`
+
+**Type**: String
+**Required**: Yes
+**Default**: None
+
+Directory where SQLite database files are stored. One database file per vault.
+
+```yaml
+database:
+  databases_directory_path: /data/databases
+```
+
+The directory structure:
+```
+databases/
+├── vault-1.db
+├── vault-2.db
+└── personal.db
+```
+
+**Notes**:
+- Path is relative to working directory or absolute
+- Directory must be writable by the server process
+- Ensure adequate disk space for vault data
+- Back up this directory regularly
+
+### `max_connections_per_vault`
+
+**Type**: Integer
+**Required**: Yes
+**Default**: None
+**Recommended**: 12
+
+Maximum concurrent database connections per vault.
+
+```yaml
+database:
+  max_connections_per_vault: 12
+```
+
+**Tuning**:
+- Higher values: Better performance under load
+- Lower values: Less memory usage
+- Typical range: 8-20
+- Consider: Number of concurrent users × average operations per user
+
+### `cursor_timeout_seconds`
+
+**Type**: Integer
+**Required**: Yes
+**Default**: None
+**Recommended**: 60
+
+How long to keep database cursors alive for inactive clients.
+
+```yaml
+database:
+  cursor_timeout_seconds: 60
+```
+
+**Notes**:
+- Cursors track client sync state
+- Timeout too short: Clients may need to re-sync frequently
+- Timeout too long: More memory usage
+- Typical range: 30-300 seconds
+
+## Server Section
+
+### `host`
+
+**Type**: String
+**Required**: Yes
+**Default**: None
+
+Network interface to bind the server to.
+
+```yaml
+server:
+  host: 0.0.0.0  # All interfaces
+  # OR
+  host: 127.0.0.1  # Localhost only
+  # OR
+  host: 192.168.1.100  # Specific interface
+```
+
+**Common values**:
+- `0.0.0.0`: Listen on all network interfaces (production)
+- `127.0.0.1`: Listen on localhost only (development/testing)
+- Specific IP: Listen on specific interface
+
+### `port`
+
+**Type**: Integer
+**Required**: Yes
+**Default**: None
+**Recommended**: 3000
+
+TCP port to listen on.
+
+```yaml
+server:
+  port: 3000
+```
+
+**Notes**:
+- Must be available (not in use)
+- Privileged ports (< 1024) require root
+- Common ports: 3000, 8080, 8888
+- Configure firewall to allow this port
+
+### `max_body_size_mb`
+
+**Type**: Integer
+**Required**: Yes
+**Default**: None
+**Recommended**: 512
+
+Maximum size of HTTP request body in megabytes.
+
+```yaml
+server:
+  max_body_size_mb: 512
+```
+
+**Usage**:
+- Limits file upload size
+- Prevents memory exhaustion attacks
+- Must be larger than largest expected file
+- Consider client `max_file_size_mb` settings
+
+**Tuning**:
+- Small vaults (mostly text): 100 MB
+- Medium vaults (some images): 512 MB
+- Large vaults (many images/PDFs): 1024+ MB
+
+### `max_clients_per_vault`
+
+**Type**: Integer
+**Required**: Yes
+**Default**: None
+**Recommended**: 256
+
+Maximum concurrent clients per vault.
+
+```yaml
+server:
+  max_clients_per_vault: 256
+```
+
+**Notes**:
+- Limits concurrent WebSocket connections
+- Prevents resource exhaustion
+- Consider expected number of users
+- Each client uses memory and file descriptors
+
+**Scaling**:
+- Personal use: 10-50
+- Small team: 50-100
+- Large team: 100-500
+
+### `response_timeout_seconds`
+
+**Type**: Integer
+**Required**: Yes
+**Default**: None
+**Recommended**: 60
+
+Maximum time to wait for client responses.
+
+```yaml
+server:
+  response_timeout_seconds: 60
+```
+
+**Usage**:
+- Timeout for HTTP requests
+- Timeout for WebSocket operations
+- Clients disconnected if unresponsive
+
+**Tuning**:
+- Fast networks: 30 seconds
+- Slow networks: 90-120 seconds
+- Large file uploads: Increase proportionally
+
+## Users Section
+
+See [Authentication Configuration →](/config/authentication) for detailed user configuration.
+
+## Logging Section
+
+### `log_directory`
+
+**Type**: String
+**Required**: Yes
+**Default**: None
+
+Directory where log files are written.
+
+```yaml
+logging:
+  log_directory: /data/logs
+  # OR
+  log_directory: logs  # Relative to working directory
+```
+
+**Notes**:
+- Path is relative to working directory or absolute
+- Directory must be writable
+- Logs are rotated based on `log_rotation`
+- Monitor disk usage
+
+### `log_rotation`
+
+**Type**: String
+**Required**: Yes
+**Default**: None
+
+How often to rotate log files.
+
+```yaml
+logging:
+  log_rotation: 7days
+  # OR
+  log_rotation: 24hours
+  # OR
+  log_rotation: 30days
+```
+
+**Format**: `<number><unit>`
+
+**Units**:
+- `hours`: Hours (e.g., `12hours`, `24hours`)
+- `days`: Days (e.g., `7days`, `30days`)
+
+**Recommendations**:
+- Development: `24hours` or `7days`
+- Production: `7days` or `30days`
+- High traffic: `24hours` (logs can be large)
+
+## Environment-Specific Configurations
+
+### Development
+
+```yaml
+database:
+  databases_directory_path: ./databases
+  max_connections_per_vault: 8
+  cursor_timeout_seconds: 30
+
+server:
+  host: 127.0.0.1
+  port: 3000
+  max_body_size_mb: 100
+  max_clients_per_vault: 10
+  response_timeout_seconds: 30
+
+users:
+  user_configs:
+  - name: dev
+    token: dev-token
+    vault_access:
+      type: allow_access_to_all
+
+logging:
+  log_directory: logs
+  log_rotation: 24hours
+```
+
+### Production
+
+```yaml
+database:
+  databases_directory_path: /data/databases
+  max_connections_per_vault: 16
+  cursor_timeout_seconds: 120
+
+server:
+  host: 0.0.0.0
+  port: 3000
+  max_body_size_mb: 512
+  max_clients_per_vault: 256
+  response_timeout_seconds: 90
+
+users:
+  user_configs:
+  - name: admin
+    token: <strong-random-token>
+    vault_access:
+      type: allow_access_to_all
+  # Additional users...
+
+logging:
+  log_directory: /data/logs
+  log_rotation: 7days
+```
+
+## Validation
+
+The server validates configuration on startup:
+
+```bash
+# Start server
+./sync_server config.yml
+
+# Check for errors in logs
+tail -f logs/latest.log
+```
+
+**Common errors**:
+- Missing required fields
+- Invalid YAML syntax
+- Invalid values (negative numbers, etc.)
+- Directory not writable
+
+## Performance Tuning
+
+### High Concurrency
+
+For many concurrent users:
+
+```yaml
+database:
+  max_connections_per_vault: 20  # Increase
+
+server:
+  max_clients_per_vault: 500  # Increase
+  response_timeout_seconds: 120  # Increase for slow clients
+```
+
+### Large Files
+
+For vaults with large files:
+
+```yaml
+server:
+  max_body_size_mb: 1024  # Allow larger uploads
+  response_timeout_seconds: 180  # More time for uploads
+```
+
+### Resource-Constrained Systems
+
+For limited CPU/memory:
+
+```yaml
+database:
+  max_connections_per_vault: 6  # Reduce
+
+server:
+  max_clients_per_vault: 50  # Reduce
+  max_body_size_mb: 256  # Reduce
+```
+
+## Security Considerations
+
+### Token Security
+
+- Use strong random tokens: `openssl rand -hex 32`
+- Never commit tokens to version control
+- Rotate tokens periodically
+- Use different tokens per user
+
+### Network Security
+
+- Bind to `127.0.0.1` if using reverse proxy on same host
+- Use firewall to restrict access
+- Enable SSL/TLS via reverse proxy
+
+### Resource Limits
+
+- Set `max_clients_per_vault` to prevent DoS
+- Set `max_body_size_mb` to prevent memory exhaustion
+- Configure `response_timeout_seconds` to prevent hanging connections
+
+## Troubleshooting
+
+### Server won't start
+
+**Check YAML syntax**:
+```bash
+# Use a YAML validator
+python -c 'import yaml, sys; yaml.safe_load(open("config.yml"))'
+```
+
+**Check file paths**:
+```bash
+# Ensure directories exist and are writable
+mkdir -p databases logs
+chmod 755 databases logs
+```
+
+**Check port availability**:
+```bash
+# Verify port is not in use
+lsof -i :3000
+```
+
+### High memory usage
+
+- Reduce `max_connections_per_vault`
+- Reduce `max_clients_per_vault`
+- Reduce `max_body_size_mb`
+- Check for large vaults or many concurrent users
+
+### Slow performance
+
+- Increase `max_connections_per_vault`
+- Increase database connection pool
+- Use SSD for database storage
+- Monitor database size (vacuum if needed)
+
+## Next Steps
+
+- [Configure authentication →](/config/authentication)
+- [Advanced configuration options →](/config/advanced)
+- [Deploy the server →](/guide/server-setup)