Skip to content

FAQ

Jump to bottom
Eric Fitzgerald edited this page Nov 12, 2025 · 1 revision

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.24+
  • 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 SERVER_PORT environment variable:

export 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:

TLS_ENABLED=true
TLS_CERT_FILE=/path/to/cert.pem
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 providers:

  • GitHub
  • Google
  • Microsoft (Azure AD)
  • SAML
  • Custom providers

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

How do I change the JWT secret?

Set the JWT_SECRET environment variable:

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

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

How do I configure the database?

Set PostgreSQL and Redis connection parameters:

DB_HOST=db.example.com
DB_PORT=5432
DB_USERNAME=postgres
DB_PASSWORD=secret
REDIS_HOST=cache.example.com
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's the difference between development and production configuration?

Development uses relaxed defaults for easier setup:

  • JWT_SECRET: "secret"
  • TLS_ENABLED: false
  • LOG_LEVEL: info

Production requires:

  • Strong JWT_SECRET
  • 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's 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's the "everyone" group?

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

{
  "subject": "everyone",
  "subject_type": "group",
  "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 Docker Scout

See Security-Best-Practices for detailed security guidance.

Real-time Collaboration

Why can't I edit when another user is editing?

When multiple users edit simultaneously, TMI uses edit locks to prevent conflicts. Wait for the other user to finish or ask them to release the lock.

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
  • Concurrent edits managed through Redis locks
  • 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-postgres
  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

Getting Started

Deployment

Operation

Troubleshooting

Development

Integrations

Tools

API Reference

Reference

Clone this wiki locally