jesus/syntaxis
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
syntaxis/docs/configuration.md
Jesús Pérez 9cef9b8d57 refactor: consolidate configuration directories 
Merge _configs/ into config/ for single configuration directory.
Update all path references.

Changes:
- Move _configs/* to config/
- Update .gitignore for new patterns
- No code references to _configs/ found

Impact: -1 root directory (layout_conventions.md compliance)
2025-12-26 18:36:23 +00:00

456 lines
13 KiB
Markdown
Raw Permalink Blame History

![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
Reference in New Issue View Git Blame Copy Permalink