![SYNTAXIS Logo](assets/syntax_logo_a.svg) # 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 ```toml [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 ```toml [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 ```toml [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 ```toml [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 ```toml [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 ```toml [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 ```toml [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 ```toml [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 ```toml [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 ```toml [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 ```toml [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 ```toml [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 ```toml [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 ```toml [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 ```toml [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 ```toml [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: ```bash # 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: ```bash # Check syntax workspace config validate # Show current configuration workspace config show # Test configuration workspace config test ``` ## Best Practices ### Development ```toml [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 ```toml [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 ```toml [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