Skip to content

FAQ

Jump to bottom
Eric Fitzgerald edited this page Oct 18, 2026 · 6 revisions

Frequently Asked Questions (FAQ)

Common questions about TMI deployment, configuration, and usage.

Getting Started

What is TMI?

TMI (Threat Modeling Improved) is a collaborative threat modeling application. It enables teams to create data flow diagrams, identify security threats, and document risk assessments with real-time collaborative editing.

Where can I try TMI?

Visit https://www.tmi.dev to access the hosted instance. The API is available at https://api.tmi.dev.

What are the system requirements?

For development:

  • Go 1.26+
  • Docker Desktop
  • Make

For production, see Deploying-TMI-Server and Deploying-TMI-Web-Application.

How do I get started with threat modeling?

See Using-TMI-for-Threat-Modeling and Creating-Your-First-Threat-Model for step-by-step guidance.

Configuration & Setup

How do I change the server port?

Set the TMI_SERVER_PORT environment variable:

export TMI_SERVER_PORT=9090
./bin/tmiserver

Or configure in YAML:

server:
  port: "9090"

See Configuration-Reference for all configuration options.

How do I enable HTTPS/TLS?

Set TLS configuration variables:

TMI_SERVER_TLS_ENABLED=true
TMI_SERVER_TLS_CERT_FILE=/path/to/cert.pem
TMI_SERVER_TLS_KEY_FILE=/path/to/key.pem

See Configuration-Reference for complete TLS setup.

How do I configure OAuth authentication?

Each OAuth provider requires:

  1. Client ID from the provider
  2. Client secret (keep secure!)
  3. Callback URL configured on the provider

Supported OAuth/OIDC providers:

  • GitHub
  • Google
  • Microsoft (Entra ID)
  • Any generic OIDC-compliant provider

TMI also supports SAML identity providers (configured separately).

See Setting-Up-Authentication for provider-specific setup instructions.

How do I change the JWT secret?

Set the TMI_JWT_SECRET environment variable:

export TMI_JWT_SECRET="your-long-random-secret-256-bits"

Important: Change this from the default "secret" in production!

How do I configure the database?

TMI supports five databases: PostgreSQL, Oracle, MySQL, SQL Server, and SQLite. Set the database and Redis connection URLs:

TMI_DATABASE_URL=postgres://postgres:secret@db.example.com:5432/tmi?sslmode=require
TMI_REDIS_URL=redis://cache.example.com:6379/0

Alternatively, Redis can be configured with individual fields:

TMI_REDIS_HOST=cache.example.com
TMI_REDIS_PORT=6379

See Database-Setup and Configuration-Reference for details.

Can I use environment variables and YAML together?

Yes. Environment variables override YAML configuration values. This allows flexible deployment:

  • Use YAML for defaults
  • Override specific values via environment variables for each deployment

Deployment

How do I deploy TMI to production?

See Planning-Your-Deployment, Deploying-TMI-Server, and Deploying-TMI-Web-Application for comprehensive guides.

Key steps:

  1. Set up PostgreSQL and Redis
  2. Configure Setting-Up-Authentication
  3. Enable TLS/HTTPS
  4. Configure Configuration-Reference
  5. Deploy Deploying-TMI-Server
  6. Deploy Deploying-TMI-Web-Application
  7. Configure Monitoring-and-Health

What is the difference between development and production configuration?

Development uses relaxed defaults for easier setup:

  • TMI_JWT_SECRET: "secret"
  • TMI_SERVER_TLS_ENABLED: false
  • TMI_LOG_LEVEL: info

Production requires:

  • Strong TMI_JWT_SECRET
  • TMI_SERVER_TLS_ENABLED: true
  • More restrictive logging and access controls
  • Database backups and monitoring

Can I deploy TMI to Kubernetes?

Yes. TMI runs in Docker containers, making it suitable for Kubernetes deployment. See Component-Integration for details.

How do I backup the database?

PostgreSQL and Redis data should be backed up regularly:

# PostgreSQL backup
pg_dump -U postgres -d tmi > backup.sql

# PostgreSQL restore
psql -U postgres -d tmi < backup.sql

# Redis backup
redis-cli BGSAVE

# Redis restore
redis-cli BGREWRITEAOF

See Database-Operations for backup procedures.

Access Control & Security

How do I grant access to a threat model?

Use authorization roles:

  1. Navigate to the threat model's sharing settings
  2. Add users or groups
  3. Assign role: Reader, Writer, or Owner

See Collaborative-Threat-Modeling for step-by-step instructions.

What is the difference between Reader, Writer, and Owner?

  • Reader - View-only access
  • Writer - Can view and edit; cannot delete or change access
  • Owner - Full permissions including delete and access control

See Glossary and Authorization Reference.

What is the "everyone" group?

A pseudo-group that grants access to all authenticated users. Useful for organization-wide documents:

{
  "principal_type": "group",
  "provider": "*",
  "provider_id": "everyone",
  "role": "reader"
}

See Glossary for more information.

Can I prevent unauthorized access to my threat models?

Yes. Use authorization controls:

How often should I rotate my JWT secret?

Recommended: Every 90 days. More frequently for highly sensitive deployments.

When rotating:

  1. Deploy new secret
  2. Keep old secret for grace period (24-48 hours)
  3. Force re-authentication of active sessions
  4. Audit logs for unusual activity

What should I do about security vulnerabilities?

  1. Subscribe to security notifications
  2. Test patches in staging first
  3. Apply patches promptly to production
  4. Monitor container image vulnerabilities with Grype (make scan-containers)

See Security-Best-Practices for detailed security guidance.

Real-time Collaboration

What happens when another user edits at the same time?

TMI does not lock diagram elements. In a collaboration session the server applies operations one at a time in arrival order; it rejects only structural conflicts (for example, adding a cell that already exists, or updating a cell that was removed), and the client then resynchronizes. If two users change the same existing cell, the later change wins. REST updates use optimistic locking with If-Match (a stale version returns 409 version_mismatch). See WebSocket-API-Reference.

How is real-time editing implemented?

Real-time editing uses WebSocket connections:

  • Client connects via ws:// (development) or wss:// (production)
  • Changes broadcast to all connected clients
  • Operations are applied one at a time in arrival order (see WebSocket-API-Reference)
  • Changes synchronized to PostgreSQL

See Working-with-Data-Flow-Diagrams for usage.

What happens if my connection drops?

  • Changes in progress are lost
  • Reconnection is automatic
  • Latest saved version is restored
  • No conflict with other users' changes

API & Integration

How do I use the TMI API?

The REST API is documented in OpenAPI 3.0.3:

What authentication do I need for API requests?

  1. Authenticate with OAuth to get a JWT token
  2. Include the token in request headers: Authorization: Bearer <token>

See Setting-Up-Authentication and API-Specifications.

Can I integrate TMI with my issue tracker?

Yes. TMI supports webhook integrations and custom integrations via the API.

See Issue-Tracker-Integration and Webhook Integration.

Troubleshooting

The server won't start

Check:

  1. Port is available: lsof -i :8080
  2. Database is running: make start-database
  3. Redis is running: make start-redis
  4. Configuration is valid: check logs for errors

See Getting-Help and Common-Issues.

I can't authenticate with OAuth

Check:

  1. OAuth provider credentials are correct
  2. Callback URL matches provider configuration
  3. Provider is enabled in config
  4. TLS/HTTPS is properly configured

See Setting-Up-Authentication.

Database connection failed

Check:

  1. Database host/port are correct
  2. Credentials are valid
  3. Database is running and accessible
  4. Network connectivity to database

See Database-Operations.

WebSocket connection keeps dropping

Check:

  1. TLS mismatch: wss:// for HTTPS, ws:// for HTTP
  2. Firewall allows WebSocket connections
  3. Proxy supports WebSocket protocol
  4. Redis is running (manages WebSocket connections)

Performance is slow

See Performance-Troubleshooting for optimization guides.

Community & Support

Where can I get help?

How do I report a bug?

  1. Check Common-Issues and existing GitHub issues
  2. Create a new GitHub issue with:
    • Description of the problem
    • Steps to reproduce
    • Expected vs. actual behavior
    • Environment details (OS, TMI version, etc.)

How do I request a feature?

  1. Check existing GitHub issues and discussions
  2. Create a feature request with use case and benefit
  3. Participate in community discussions

Can I contribute to TMI?

Yes! See Contributing for guidelines.

Related Resources

Home

Releases

Getting Started

Deployment

Operation

Troubleshooting

Development

Integrations

Tools

API Reference

Reference

Clone this wiki locally