Skip to content

Configuration Reference

Jump to bottom
Eric Fitzgerald edited this page Jan 27, 2026 · 5 revisions

Configuration Reference

This page documents all server and web application configuration options for TMI.

Server Configuration (Go Backend)

The TMI server can be configured via environment variables, YAML configuration files, or .env files.

Quick Start

# Copy and customize the example configuration
cp config-example.yml config-development.yml

# Start the server with custom config
./bin/tmiserver --env=/path/to/config.yml

Environment Variable Conventions

All TMI environment variables use the TMI_ prefix:

Pattern Example
TMI_* prefix TMI_DATABASE_URL, TMI_JWT_SECRET

Database Configuration

DATABASE_URL (Required)

TMI uses the 12-factor app pattern with a single connection URL:

Variable Default Description
TMI_DATABASE_URL Connection URL (required)
TMI_ORACLE_WALLET_LOCATION Path to Oracle wallet directory (Oracle ADB only)

Supported URL Formats:

# PostgreSQL
postgres://user:pass@host:5432/db?sslmode=require

# MySQL
mysql://user:pass@host:3306/db

# SQL Server
sqlserver://user:pass@host:1433?database=db

# SQLite
sqlite:///path/to/file.db

# Oracle
oracle://user:pass@host:1521/service_name

Connection Pool Settings

Variable Default Description
TMI_DB_MAX_OPEN_CONNS 10 Maximum open connections
TMI_DB_MAX_IDLE_CONNS 2 Maximum idle connections
TMI_DB_CONN_MAX_LIFETIME 240 Max connection lifetime in seconds
TMI_DB_CONN_MAX_IDLE_TIME 30 Max idle time in seconds

Redis

Variable Default Description
TMI_REDIS_URL Connection URL (takes precedence over individual fields)
TMI_REDIS_HOST localhost Redis server host
TMI_REDIS_PORT 6379 Redis server port
TMI_REDIS_PASSWORD Redis password
TMI_REDIS_DB 0 Redis database number

Server Settings

Variable Default Description
TMI_SERVER_PORT 8080 HTTP/HTTPS server port
TMI_SERVER_INTERFACE 0.0.0.0 Network interface
TMI_SERVER_BASE_URL Public base URL for callbacks (auto-inferred if empty)
TMI_SERVER_READ_TIMEOUT 5s HTTP read timeout
TMI_SERVER_WRITE_TIMEOUT 10s HTTP write timeout
TMI_SERVER_IDLE_TIMEOUT 60s HTTP idle timeout

TLS/HTTPS Configuration

Variable Default Description
TMI_SERVER_TLS_ENABLED false Enable HTTPS/TLS
TMI_SERVER_TLS_CERT_FILE Path to TLS certificate
TMI_SERVER_TLS_KEY_FILE Path to TLS private key
TMI_SERVER_TLS_SUBJECT_NAME hostname Certificate subject name
TMI_SERVER_HTTP_TO_HTTPS_REDIRECT true Redirect HTTP to HTTPS

JWT Authentication

Variable Default Description
TMI_JWT_SECRET JWT signing secret (required, change for production!)
TMI_JWT_EXPIRATION_SECONDS 3600 JWT expiration in seconds
TMI_JWT_SIGNING_METHOD HS256 JWT signing method

OAuth Configuration

Variable Description
TMI_OAUTH_CALLBACK_URL OAuth callback URL
OAUTH_PROVIDERS_GITHUB_CLIENT_ID GitHub OAuth client ID
OAUTH_PROVIDERS_GITHUB_CLIENT_SECRET GitHub OAuth client secret
OAUTH_PROVIDERS_GOOGLE_CLIENT_ID Google OAuth client ID
OAUTH_PROVIDERS_GOOGLE_CLIENT_SECRET Google OAuth client secret
OAUTH_PROVIDERS_MICROSOFT_CLIENT_ID Microsoft/Azure OAuth client ID
OAUTH_PROVIDERS_MICROSOFT_CLIENT_SECRET Microsoft/Azure OAuth client secret

See Setting-Up-Authentication for detailed OAuth setup instructions.

SAML Configuration

TMI supports SAML 2.0 authentication with dynamic provider discovery. SAML providers are configured via environment variables with the pattern SAML_PROVIDERS_{PROVIDER_ID}_{FIELD}.

Global SAML Settings

Variable Default Description
TMI_SAML_ENABLED false Enable SAML authentication globally

Per-Provider Settings

For each SAML provider, replace {ID} with your provider identifier (e.g., ENTRA, OKTA):

Variable Pattern Description
SAML_PROVIDERS_{ID}_ID Provider ID (e.g., "entra-saml")
SAML_PROVIDERS_{ID}_NAME Display name
SAML_PROVIDERS_{ID}_ENABLED Whether provider is enabled
SAML_PROVIDERS_{ID}_ENTITY_ID Service Provider entity ID
SAML_PROVIDERS_{ID}_ACS_URL Assertion Consumer Service URL
SAML_PROVIDERS_{ID}_SLO_URL Single Logout URL
SAML_PROVIDERS_{ID}_IDP_METADATA_URL IdP metadata URL (preferred)
SAML_PROVIDERS_{ID}_IDP_METADATA_B64XML Base64-encoded IdP metadata XML (fallback)
SAML_PROVIDERS_{ID}_SP_CERTIFICATE SP certificate (PEM format)
SAML_PROVIDERS_{ID}_SP_PRIVATE_KEY SP private key (PEM format)
SAML_PROVIDERS_{ID}_ALLOW_IDP_INITIATED Allow IdP-initiated SSO
SAML_PROVIDERS_{ID}_SIGN_REQUESTS Sign authentication requests
SAML_PROVIDERS_{ID}_EMAIL_ATTRIBUTE SAML attribute for email
SAML_PROVIDERS_{ID}_NAME_ATTRIBUTE SAML attribute for display name
SAML_PROVIDERS_{ID}_GROUPS_ATTRIBUTE SAML attribute for groups

IdP Metadata Options

TMI supports two methods for providing IdP metadata:

  1. Metadata URL (Recommended): Set IDP_METADATA_URL to the IdP's metadata endpoint. The server fetches fresh metadata at startup, automatically handling certificate rotation.

  2. Base64-encoded XML: For IdPs without metadata URLs, base64-encode the XML to avoid shell escaping issues with XML namespace prefixes:

    # Linux
IDP_METADATA_B64XML=$(base64 -w0 < idp-metadata.xml)

# macOS
IDP_METADATA_B64XML=$(base64 < idp-metadata.xml)

Note: If both IDP_METADATA_URL and IDP_METADATA_B64XML are set, the URL takes precedence.

Logging Configuration

Variable Default Description
TMI_LOG_LEVEL info Log level (debug/info/warn/error)
TMI_LOG_IS_DEV true Development mode logging
TMI_LOG_IS_TEST false Test mode logging
TMI_LOG_DIR logs Log directory
TMI_LOG_MAX_AGE_DAYS 7 Max log file age in days
TMI_LOG_MAX_SIZE_MB 100 Max log file size in MB
TMI_LOG_MAX_BACKUPS 10 Max log file backups
TMI_LOG_ALSO_LOG_TO_CONSOLE true Also log to console
TMI_LOG_API_REQUESTS false Log API requests
TMI_LOG_API_RESPONSES false Log API responses
TMI_LOG_WEBSOCKET_MESSAGES false Log WebSocket messages
TMI_LOG_REDACT_AUTH_TOKENS false Redact tokens in logs
TMI_LOG_SUPPRESS_UNAUTH_LOGS true Suppress unauthenticated request logs

Operator Information

Variable Description
TMI_OPERATOR_NAME Operator/maintainer name
TMI_OPERATOR_CONTACT Contact email or URL

WebSocket Configuration

Variable Default Description
TMI_WEBSOCKET_INACTIVITY_TIMEOUT_SECONDS 300 Inactivity timeout in seconds (minimum 15)

When TLS is enabled, clients must use secure WebSocket URLs:

  • Use wss:// instead of ws:// for WebSocket connections
  • Example: wss://your-server.com:8080/ws/diagrams/123

Secret Management

TMI supports external secret providers for production deployments where secrets should not be stored in environment variables.

Configuration

Variable Default Description
TMI_SECRETS_PROVIDER env Provider: env, aws, oci

AWS Secrets Manager

Store secrets as a JSON object in AWS Secrets Manager:

{
  "JWT_SECRET": "your-secret",
  "DATABASE_PASSWORD": "db-password"
}
Variable Description
TMI_AWS_REGION AWS region (e.g., us-west-2)
TMI_AWS_SECRET_NAME Secret name in AWS Secrets Manager

Uses AWS SDK default credential chain (environment variables, IAM role, ~/.aws/credentials).

OCI Vault Secrets

Supports both single JSON secret (like AWS) and multiple individual secrets.

Variable Description
TMI_OCI_COMPARTMENT_ID OCI compartment OCID
TMI_OCI_VAULT_ID OCI vault OCID
TMI_OCI_SECRET_NAME Single JSON secret name (optional)

If TMI_OCI_SECRET_NAME is empty, retrieves individual secrets by key name.

Uses OCI SDK default config (~/.oci/config or instance principal).

System Settings (Database-Stored)

Some configuration can be stored in the database for runtime modification without restarts.

Admin Settings API

Endpoints (Admin Only):

  • GET /admin/settings - List all settings
  • GET /admin/settings/{key} - Get a specific setting
  • PUT /admin/settings/{key} - Update a setting
  • DELETE /admin/settings/{key} - Delete a setting

Example:

# List all settings
curl -H "Authorization: Bearer $TOKEN" https://api.example.com/admin/settings

# Update a setting
curl -X PUT -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"value": "true", "type": "bool"}' \
  https://api.example.com/admin/settings/features.webhooks_enabled

Available Settings

Key Type Description
features.saml_enabled bool Enable SAML authentication
features.webhooks_enabled bool Enable webhook notifications
upload.max_file_size_mb int Maximum file upload size
websocket.max_participants int Max participants per session
ui.default_theme string Default UI theme (auto/light/dark)

Client Configuration Endpoint

The GET /config endpoint provides configuration for client applications (public, no auth required):

{
  "features": {
    "websocket_enabled": true,
    "saml_enabled": false,
    "webhooks_enabled": true
  },
  "operator": {
    "name": "TMI Project",
    "contact": "https://github.com/ericfitz/tmi"
  },
  "limits": {
    "max_file_upload_mb": 10,
    "max_diagram_participants": 10
  },
  "ui": {
    "default_theme": "auto"
  }
}

Web Application Configuration (Angular Frontend)

The TMI UX web application is configured through environment files located in src/environments/.

Environment Files

  • environment.ts - Default development environment
  • environment.dev.ts - Development configuration (used by ng serve)
  • environment.prod.ts - Production environment
  • environment.staging.ts - Staging environment
  • environment.test.ts - Test environment
  • environment.local.ts - Local development (git-ignored)
  • environment.hosted-container.ts - Containerized deployment
  • environment.example.ts - Template with documentation
  • environment.interface.ts - TypeScript interface definition

Environment Settings

Setting Default Description
production false Enable production mode
logLevel ERROR Logging verbosity (DEBUG, INFO, WARN, ERROR)
debugComponents [] Component-specific debug logging
apiUrl https://api.example.com/v1 API server URL
authTokenExpiryMinutes 60 Token validity in minutes
operatorName TMI Operator Name of service operator
operatorContact contact@example.com Contact information
serverPort 4200 Server listening port
serverInterface 0.0.0.0 Server listening interface
enableTLS false Enable HTTPS
defaultAuthProvider undefined Default authentication provider

Security Configuration (securityConfig)

Setting Default Description
enableHSTS true Enable HTTP Strict Transport Security
hstsMaxAge 31536000 HSTS max-age in seconds (1 year)
hstsIncludeSubDomains true Include subdomains in HSTS policy
hstsPreload false Enable HSTS preload
frameOptions DENY X-Frame-Options header
referrerPolicy strict-origin-when-cross-origin Referrer-Policy header

Component-Specific Debug Logging

The debugComponents configuration allows fine-grained control over debug logging by component.

Example: Debugging Collaboration Issues:

export const environment = {
  logLevel: 'DEBUG',
  debugComponents: [
    'DfdCollaborationService',
    'CollaborationSession',
    'WebSocketCollaboration',
    'websocket-api',
  ],
};

Running with Different Environments

# Default environment
pnpm run dev

# Specific environment
pnpm run dev:staging
pnpm run dev:prod

Configuration Files

Server Configuration File Format

The server uses YAML configuration files:

server:
  port: "8080"
  interface: "0.0.0.0"
  tls_enabled: false
  tls_cert_file: ""
  tls_key_file: ""

database:
  # DATABASE_URL is required (12-factor app pattern)
  url: "postgres://user:pass@localhost:5432/tmi?sslmode=disable"

  # Connection pool settings (optional)
  connection_pool:
    max_open_conns: 10
    max_idle_conns: 2
    conn_max_lifetime: 240  # seconds
    conn_max_idle_time: 30  # seconds

  redis:
    host: "localhost"
    port: "6379"

auth:
  jwt:
    secret: "CHANGE_ME"
    expiration_seconds: 3600
    signing_method: "HS256"
  oauth:
    callback_url: "http://localhost:8080/oauth2/callback"

websocket:
  inactivity_timeout_seconds: 300

logging:
  level: "info"
  is_dev: true
  log_dir: "logs"

operator:
  name: "TMI Operator"
  contact: "contact@example.com"

# Secret management (optional)
secrets:
  provider: "env"  # env, aws, or oci
  aws:
    region: ""
    secret_name: ""
  oci:
    compartment_id: ""
    vault_id: ""
    secret_name: ""

# Administrators (optional)
administrators:
  - provider: "github"
    provider_id: "12345"
    subject_type: "user"

See config-example.yml in the tmi repository for complete configuration examples.

Administrator Configuration

Administrators can be configured via YAML or environment variables.

YAML Configuration

administrators:
  - provider: "github"           # OAuth/SAML provider ID (required)
    provider_id: "12345"         # Provider's user ID (for users)
    email: "admin@example.com"   # Fallback email (for users)
    subject_type: "user"         # "user" or "group" (required)
  - provider: "entra"
    group_name: "tmi-admins"     # Group name (for groups)
    subject_type: "group"

Environment Variables (Heroku-friendly)

For single administrator via environment:

Variable Description
TMI_ADMIN_PROVIDER OAuth/SAML provider ID (required)
TMI_ADMIN_SUBJECT_TYPE "user" or "group" (default: "user")
TMI_ADMIN_PROVIDER_ID Provider's user ID (for users)
TMI_ADMIN_EMAIL Provider's email (for users, fallback)
TMI_ADMIN_GROUP_NAME Group name (for groups)

Heroku Deployment

For Heroku deployments, the setup script automatically configures TMI_ prefixed variables:

# Run the setup script
uv run scripts/setup-heroku-env.py

# The script will:
# - Detect DATABASE_URL from Heroku Postgres addon
# - Generate TMI_JWT_SECRET
# - Configure TMI_* prefixed environment variables

Related Documentation

Home

Getting Started

Deployment

Operation

Troubleshooting

Development

Integrations

Tools

API Reference

Reference

Clone this wiki locally