Getting Help - ericfitz/tmi GitHub Wiki

Getting Help

This page outlines how to get support, access community resources, and report issues with TMI.

Official Support Channels

GitHub Repository

The primary home for TMI development and issue tracking:

Documentation

Comprehensive documentation is available in multiple locations:

  • Wiki: This wiki provides operational and user-facing documentation
  • Source Docs: Technical documentation in /docs directory of the repository
  • API Specs: OpenAPI and AsyncAPI specifications at API-Specifications
  • Code Comments: Inline documentation in source code

Community Resources

Public Instance

Try TMI before deploying:

Example Projects

Reporting Issues

Bug Reports

When reporting bugs, include:

  1. Description: Clear description of the problem
  2. Steps to Reproduce: Detailed steps to recreate the issue
  3. Expected Behavior: What should happen
  4. Actual Behavior: What actually happens
  5. Environment:
    • TMI version (git commit hash or release version)
    • Operating system and version
    • Browser (for web client issues)
    • Database versions (PostgreSQL, Redis)
  6. Logs: Relevant log output (sanitize sensitive data)
  7. Screenshots: If applicable

Example Bug Report:

## Description
Server crashes when creating a threat model with invalid JSON in metadata field.

## Steps to Reproduce
1. Navigate to threat model creation page
2. Add metadata field with value: `{invalid json`
3. Click "Create Threat Model"
4. Server returns 500 error

## Expected Behavior
Should validate JSON and return 400 Bad Request with validation error.

## Actual Behavior
Server crashes with panic, returns 500 Internal Server Error.

## Environment
- TMI version: commit abc123def
- OS: Ubuntu 22.04 LTS
- PostgreSQL: 15.3
- Redis: 7.0.11

## Logs

panic: invalid character 'i' looking for beginning of object key string ...

Feature Requests

When requesting features:

  1. Use Case: Describe the problem you're trying to solve
  2. Proposed Solution: How you envision the feature working
  3. Alternatives: Other solutions you've considered
  4. Benefits: Who benefits and how
  5. Examples: Similar features in other tools (if applicable)

Create feature requests in GitHub Discussions first to gauge interest before opening an issue.

Security Vulnerabilities

Report security vulnerabilities by creating an issue in the GitHub repository. The product is under active development, and all vulnerability reports are investigated and addressed as appropriate.

When reporting, include:

  1. Description of the vulnerability
  2. Steps to reproduce (proof of concept)
  3. Potential impact
  4. Affected versions

See the Security Policy and Security-Best-Practices for security policies.

Getting Help

Before Asking

  1. Search Documentation: Check this wiki and FAQ
  2. Search Issues: Look for existing GitHub issues
  3. Check Logs: Review server and application logs
  4. Try Common Fixes: See Common-Issues for frequent problems

Where to Ask

For usage questions:

  • GitHub Discussions (preferred)
  • Create a GitHub issue with "question" label

For deployment help:

For API integration:

For development:

Information to Include

When asking for help, provide:

  1. Context: What are you trying to accomplish?
  2. What You've Tried: Steps you've already taken
  3. Environment: OS, TMI version, deployment method
  4. Logs/Errors: Relevant error messages (sanitized)
  5. Configuration: Relevant config (remove secrets!)

Self-Help Resources

Quick Diagnostic Steps

Server won't start:

  1. Check port availability: lsof -i :8080
  2. Verify database connectivity: make start-database
  3. Verify Redis connectivity: make start-redis
  4. Check logs: tail -f logs/server.log

See Common-Issues#server-startup-problems for details.

Authentication failing:

  1. Verify OAuth credentials
  2. Check callback URL configuration
  3. Test provider connectivity
  4. Review authentication logs

See Common-Issues#authentication-problems for details.

WebSocket not connecting:

  1. Check TLS configuration (wss:// vs ws://)
  2. Verify firewall/proxy settings
  3. Test Redis connectivity
  4. Check browser console for errors

See Common-Issues#websocket-problems for details.

Diagnostic Commands

# Check service status
make status

# View server logs
tail -f logs/server.log

# Test Redis connection
redis-cli ping

# Check OAuth protected resource metadata
curl http://localhost:8080/.well-known/oauth-protected-resource

See Debugging-Guide for comprehensive debugging procedures.

Log Analysis

Server logs location:

  • Development: stdout or logs/server.log
  • Docker: docker logs tmi-api-prod
  • Production: Configure via log_dir in the server YAML configuration file (e.g., /var/log/tmi)

Key log patterns:

# Authentication errors
grep "authentication failed" logs/server.log

# Database errors
grep "database error" logs/server.log

# WebSocket errors
grep "websocket" logs/server.log

# API errors (5xx)
grep "status=5" logs/server.log

See Debugging-Guide#log-analysis for detailed log analysis.

Contributing Documentation

Found an error or gap in documentation? Help improve it!

Wiki Contributions

This wiki is maintained in the tmi.wiki repository:

  1. Fork the repository
  2. Make your changes
  3. Submit a pull request
  4. Describe what you changed and why

Source Documentation

Documentation in the main repository (/docs):

  1. Fork ericfitz/tmi
  2. Update documentation in /docs directory
  3. Follow existing structure and style
  4. Submit a pull request

See Contributing for contribution guidelines.

Community Guidelines

Be Respectful

  • Be courteous and professional
  • Respect different perspectives and experience levels
  • Provide constructive feedback
  • Help others learn and grow

Be Clear

  • Use clear, descriptive titles
  • Provide sufficient context
  • Format code and logs properly
  • Use markdown formatting

Be Patient

  • Maintainers and community members are often volunteers
  • Complex issues take time to investigate
  • Not all feature requests can be implemented

Escalation Path

  1. Check Documentation: Wiki, FAQ, source docs
  2. Search Issues: Look for existing reports
  3. Self-Diagnosis: Use Debugging-Guide and Common-Issues
  4. Community Help: Post in GitHub Discussions
  5. Bug Report: Create GitHub issue with full details
  6. Security Issue: Create a GitHub issue per the Security Policy

Related Resources