syntaxis/docs/configuration.md

Configuration Guide

Complete reference for all syntaxis configuration options.

Configuration Hierarchy

Workspace-ecosystem searches for configuration files in this order:

1. User config - ~/.config/core/syntaxis-api.toml
2. Project config - .project/syntaxis-api.toml
3. VAPORA config - .vapora/syntaxis-api.toml

The first file found is used. Project-specific configs override user configs.

Main Configuration: syntaxis-api.toml

Located at: ~/.config/core/syntaxis-api.toml

Server Settings

[server]
host = "127.0.0.1"           # Server bind address
port = 8080                  # Server port
workers = 4                  # Number of worker threads
timeout_seconds = 300        # Request timeout
shutdown_timeout = 30        # Graceful shutdown timeout

Database Settings

[database]
path = "workspace.db"        # SQLite database file path
pool_size = 5                # Connection pool size
wal_mode = true              # Write-Ahead Logging
cache_size_mb = 64           # Page cache size
journal_mode = "WAL"         # Journal mode (WAL or DELETE)

Logging

[logging]
level = "info"               # Log level: trace, debug, info, warn, error
format = "json"              # Log format: json or plain
output = "stdout"            # Output: stdout, stderr, or file path
max_file_size_mb = 100       # Max log file size (if file output)
max_files = 10               # Max number of log files to keep

Authentication

[auth]
enabled = true               # Enable authentication
provider = "local"           # Auth provider: local, oauth2, ldap
session_timeout_minutes = 60 # Session timeout
require_https = false        # Require HTTPS
jwt_secret = ""              # JWT secret key

CORS

[cors]
enabled = true               # Enable CORS
allowed_origins = ["*"]      # Allowed origins
allowed_methods = ["GET", "POST", "PUT", "DELETE"]
allowed_headers = ["Content-Type", "Authorization"]
expose_headers = ["X-Total-Count"]
max_age_seconds = 3600       # Preflight cache duration

Feature Configurations

Feature configs are located in ~/.config/core/features/

auth.toml - Authentication

[auth]
enabled = true                           # Enable authentication
provider = "local"                       # local, oauth2, ldap, saml
session_timeout_minutes = 60             # Session validity
require_https = false                    # Enforce HTTPS
password_min_length = 8                  # Minimum password length
password_require_uppercase = true        # Require uppercase letters
password_require_numbers = true          # Require numbers
password_require_special = true          # Require special characters
max_login_attempts = 5                   # Failed attempts before lockout
lockout_duration_minutes = 15            # Lockout duration

[auth.providers.oauth2]
client_id = ""                           # OAuth2 client ID
client_secret = ""                       # OAuth2 client secret
authorize_url = ""                       # Authorization endpoint
token_url = ""                           # Token endpoint
user_info_url = ""                       # User info endpoint

[auth.providers.ldap]
server = ""                              # LDAP server address
port = 389                               # LDAP port
bind_dn = ""                             # Bind DN
base_dn = ""                             # Base DN for search
user_search_filter = "uid={}"            # User search filter

cache.toml - Caching

[cache]
enabled = true                           # Enable caching
backend = "memory"                       # memory, redis, memcached
ttl_seconds = 3600                       # Default cache TTL
max_size_mb = 256                        # Max cache size

[cache.memory]
# In-process cache settings
eviction = "lru"                         # lru or lfu
max_entries = 10000                      # Max cache entries

[cache.redis]
# Redis backend settings
host = "localhost"
port = 6379
db = 0
password = ""                            # Redis password
pool_size = 10                           # Connection pool size

database.toml - Database

[database]
type = "sqlite"                          # sqlite, postgres, mysql
path = "workspace.db"                    # SQLite path
pool_size = 5                            # Connection pool size
wal_mode = true                          # Write-Ahead Logging
cache_size_mb = 64                       # Cache size
max_retries = 3                          # Connection retry attempts
retry_delay_ms = 100                     # Retry delay

[database.postgres]
# PostgreSQL settings
host = "localhost"
port = 5432
username = ""
password = ""
database = "workspace"
ssl_mode = "disable"                     # disable, require, prefer

[database.mysql]
# MySQL settings
host = "localhost"
port = 3306
username = ""
password = ""
database = "workspace"
charset = "utf8mb4"

health.toml - Health Checks

[health]
enabled = true                           # Enable health checks
endpoint = "/health"                     # Health check endpoint
check_interval_seconds = 30              # Check interval
readiness_timeout_seconds = 5            # Readiness probe timeout
liveness_timeout_seconds = 5             # Liveness probe timeout

[health.checks.database]
enabled = true                           # Check database connectivity
query = "SELECT 1"                       # Test query

[health.checks.cache]
enabled = true                           # Check cache connectivity
timeout_ms = 1000                        # Check timeout

[health.checks.external_services]
enabled = true                           # Check external service dependencies
timeout_ms = 5000                        # Check timeout

metrics.toml - Monitoring

[metrics]
enabled = true                           # Enable metrics collection
endpoint = "/metrics"                    # Metrics endpoint
retention_days = 30                      # Metrics retention period
sample_interval_seconds = 60             # Sample interval

[metrics.collection]
collect_request_metrics = true           # Collect HTTP request metrics
collect_database_metrics = true          # Collect database metrics
collect_cache_metrics = true             # Collect cache metrics
collect_system_metrics = true            # Collect system metrics

[metrics.export]
format = "prometheus"                    # prometheus or openmetrics
compression = "gzip"                     # gzip, deflate, or none

multi_tenant.toml - Multi-Tenancy

[multi_tenant]
enabled = true                           # Enable multi-tenancy
isolation_level = "database"             # database or row
tenant_header = "X-Tenant-ID"            # Header for tenant ID
default_tenant = "default"               # Default tenant
max_tenants = 1000                       # Max tenants allowed

[multi_tenant.isolation]
# Database isolation settings
separate_connections = false             # Use separate DB connections per tenant

rate_limit.toml - Rate Limiting

[rate_limit]
enabled = true                           # Enable rate limiting
global_limit = 10000                     # Global requests per minute
per_user_limit = 100                     # Per-user requests per minute
per_ip_limit = 50                        # Per-IP requests per minute
burst_size = 10                          # Burst tolerance

[rate_limit.endpoints]
# Per-endpoint limits
"/api/projects" = 100                    # Requests per minute
"/api/tasks" = 200

projects.toml - Project Management

[projects]
max_name_length = 255                    # Maximum project name length
max_description_length = 2000            # Maximum description length
require_templates = false                # Require template selection
enable_auto_archive = true               # Auto-archive old projects
archive_after_days = 365                 # Archive after inactive days
visibility_options = ["public", "private", "internal"]

[projects.templates]
enabled = true                           # Enable templates
template_dir = "templates"               # Template directory
allow_custom = true                      # Allow custom templates

tasks.toml - Task Tracking

[tasks]
max_title_length = 255                   # Maximum task title length
max_description_length = 5000            # Maximum description length
states = ["pending", "in_progress", "completed", "blocked"]
require_assignee = false                 # Require task assignee
enable_subtasks = true                   # Enable task subtasks
max_subtasks = 50                        # Maximum subtasks per task

[tasks.validation]
require_description = false              # Require description
require_priority = true                  # Require priority
priority_levels = [1, 2, 3, 4, 5]       # Available priority levels

phases.toml - Phase Lifecycle

[phases]
states = ["create", "devel", "publish", "archive"]
require_tasks = false                    # Require tasks in phase
require_review = false                   # Require review before transition
enable_automation = true                 # Enable phase automation
auto_transition = false                  # Auto-transition phases

[phases.transitions]
# Define valid transitions
"create" = ["devel", "archive"]          # From create to devel/archive
"devel" = ["publish", "create", "archive"]
"publish" = ["archive"]
"archive" = []                           # Archive is terminal

[phases.validation]
require_tests_pass = false               # Require tests pass
require_code_review = false              # Require code review
require_docs = false                     # Require documentation

audit.toml - Audit Trail

[audit]
enabled = true                           # Enable audit trail
retention_days = 365                     # Keep audit records for days
include_field_changes = true             # Track field-level changes
include_sensitive_data = false           # Include sensitive data in audit
log_level = "info"                       # Log level for audit events

[audit.events]
track_login = true                       # Track login events
track_config_changes = true              # Track config changes
track_data_modifications = true          # Track data modifications
track_deletions = true                   # Track deletions

Environment Variables

You can override configuration using environment variables:

# Server settings
export WORKSPACE_SERVER_HOST="0.0.0.0"
export WORKSPACE_SERVER_PORT="8081"
export WORKSPACE_SERVER_WORKERS="8"

# Database settings
export WORKSPACE_DATABASE_PATH="/var/lib/workspace.db"
export WORKSPACE_DATABASE_POOL_SIZE="10"

# Logging
export WORKSPACE_LOG_LEVEL="debug"
export WORKSPACE_LOG_FORMAT="json"

# Authentication
export WORKSPACE_AUTH_ENABLED="true"
export WORKSPACE_AUTH_JWT_SECRET="your-secret-key"

# Features
export WORKSPACE_CACHE_ENABLED="true"
export WORKSPACE_METRICS_ENABLED="true"

Configuration Validation

Validate your configuration files:

# Check syntax
workspace config validate

# Show current configuration
workspace config show

# Test configuration
workspace config test

Best Practices

Development

[server]
host = "127.0.0.1"
port = 8080

[logging]
level = "debug"
format = "plain"

[auth]
enabled = false                          # Disable auth in development

[database]
path = "dev.db"

[cache]
enabled = false                          # Disable cache in development

Production

[server]
host = "0.0.0.0"
port = 8080
timeout_seconds = 600

[logging]
level = "warn"
format = "json"
output = "/var/log/workspace.log"

[auth]
enabled = true
require_https = true

[database]
pool_size = 20
wal_mode = true
cache_size_mb = 256

[cache]
enabled = true
backend = "redis"
ttl_seconds = 7200

High-Availability

[server]
workers = 16
timeout_seconds = 300

[database]
type = "postgres"                        # Use PostgreSQL for HA
pool_size = 30
max_retries = 5
retry_delay_ms = 200

[cache]
backend = "redis"                        # Use Redis
max_size_mb = 512

[multi_tenant]
isolation_level = "database"
separate_connections = true

[rate_limit]
global_limit = 50000

Troubleshooting Configuration

Configuration not loading

1. Check file permissions: ls -la ~/.config/core/
2. Verify TOML syntax: workspace config validate
3. Check environment variables: env | grep WORKSPACE
4. View current config: workspace config show

Settings not taking effect

1. Restart the application
2. Check config file path: echo $WORKSPACE_CONFIG_PATH
3. Verify feature is enabled in config
4. Check logs: workspace logs show

Performance issues

1. Increase database pool size
2. Enable caching
3. Adjust timeouts based on workload
4. Monitor metrics: curl http://localhost:8080/metrics

Related Documentation

• docs/installation-guide.md - How to install syntaxis
• WRAPPER_DESIGN.md - How wrapper scripts work
• README.md - Project overview