Skip to content

Add troubleshooting guide for common setup issues #191

@manraj777

Description

@manraj777

Problem

Developers setting up the OpenMRS performance test project for the first time often encounter common issues during setup, including:

  • Connection errors to OpenMRS on port 80
  • Docker configuration problems
  • Maven build issues
  • Gatling simulation failures
  • Unclear debugging steps when tests fail

Currently, the README provides prerequisites but lacks practical troubleshooting guidance, leading to duplicate questions in the community.

Solution

Create a comprehensive TROUBLESHOOTING.md file documenting:

  1. Common OpenMRS connection issues and how to diagnose them
  2. Docker setup problems (installation, permissions, resources)
  3. Gatling test failures and recovery steps
  4. Maven build errors and resolution
  5. Performance test result interpretation
  6. Links to additional resources and community support

Each section should include:

  • Problem description
  • Symptoms to look for
  • Step-by-step solutions
  • Practical shell commands where applicable

Benefits

  • Reduces support burden from community members
  • Improves first-time contributor experience
  • Provides self-serve solutions for common problems
  • Better documentation for backend tooling

Acceptance Criteria

  • TROUBLESHOOTING.md created with comprehensive sections
  • All major setup issues covered with practical solutions
  • README.md updated to reference TROUBLESHOOTING.md
  • Document includes clear bash/shell commands for debugging
  • Links to relevant OpenMRS documentation included

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions