vault-link/docs/config/server.md

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:

/app/sync_server /path/to/config.yml

Complete Example

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.

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.

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.

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.

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.

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.

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.

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.

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 → for detailed user configuration.

Logging Section

log_directory

Type: String Required: Yes Default: None

Directory where log files are written.

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.

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

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

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:

# 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:

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:

server:
  max_body_size_mb: 1024  # Allow larger uploads
  response_timeout_seconds: 180  # More time for uploads

Resource-Constrained Systems

For limited CPU/memory:

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:

# Use a YAML validator
python -c 'import yaml, sys; yaml.safe_load(open("config.yml"))'

Check file paths:

# Ensure directories exist and are writable
mkdir -p databases logs
chmod 755 databases logs

Check port availability:

# 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 →
• Advanced configuration options →
• Deploy the server →