Installation

Quick Start#

Get the incident management platform running locally for development and testing:

Option 1: Go Binary (Recommended for Development)#

# Clone the repository
git clone https://github.com/systmms/incidents.git
cd incidents

# Install dependencies
go mod tidy

# Build all components
make build

# Start the server
./bin/server

# In another terminal, test the CLI
./bin/im declare --title "Test incident" --sev SEV-2

# Server will be available at http://localhost:8080

Option 2: Make Commands (Convenient)#

# Build all binaries
make build

# Run the server
make run-server

# Test CLI functionality (needs server running)
make run-cli

Prerequisites#

Development Requirements#

• Go: 1.22 or later
• Git: For cloning the repository
• Make: For using convenient build commands (optional)

System Requirements#

• Memory: 1GB RAM minimum for development
• CPU: Any modern processor (multi-core helpful for development)
• Storage: 2GB available space for source and builds
• Network: Internet access for Go modules and testing integrations

Optional Development Tools#

• Docker: For containerized development (experimental)
• Air: For hot reload during development (go install github.com/air-verse/air@latest)

Current Development Setup#

Local Development (Recommended)#

This is the primary development method while the platform is being built:

1. Build the project:

   make build

2. Start the server:

   # Start server (uses SQLite by default)
   ./bin/server
   
   # Server starts on http://localhost:8080
   # Database will be created as incidents.db

3. Test the API:

   # Check server health
   curl http://localhost:8080/health
   
   # Response: {"status":"healthy"}

4. Use the CLI:

   # Test CLI commands (server must be running)
   ./bin/im declare --title "Test incident" --sev SEV-2
   ./bin/im --help  # See all available commands

Hot Reload Development#

For active development with automatic rebuilding:

# Install air for hot reload
go install github.com/air-verse/air@latest

# Run with hot reload
air

# Server will restart automatically when Go files change
# Access at http://localhost:8080

Testing Connectors#

The platform includes a connector testing framework:

# Test connector framework (requires external service credentials)
make test-servicenow  # Requires SERVICENOW_URL, SERVICENOW_USERNAME, etc.
make test-jira        # Requires JIRA_URL, JIRA_USERNAME, etc.

# See connector testing guide for setup details

Available Components#

The platform currently includes:

Built Components#

• Server (./bin/server) - Main API server with web interface
• CLI (./bin/im) - Command-line interface with 15+ commands
• Connector Test (./bin/connector-test) - Framework for testing external integrations

CLI Commands Available#

./bin/im --help  # See all commands

# Key commands that work:
./bin/im declare     # Create incidents
./bin/im ack        # Acknowledge incidents
./bin/im resolve    # Resolve incidents
./bin/im timeline   # View incident timeline
./bin/im serve      # Start web server
./bin/im connector  # Manage integrations

Connector Testing#

The platform includes comprehensive testing for:

• ServiceNow integration
• Jira Service Management
• Generic webhook processing

Configuration#

The platform uses these environment variables when available:

Getting Started#

After installation, try these basic operations:

1. Check server status:

   # Ensure server is running
   curl http://localhost:8080/health
   # Expected: {"status":"healthy"}

2. Test CLI functionality:

   # Create a test incident
   ./bin/im declare --title "Test incident" --sev SEV-2
   
   # List available commands
   ./bin/im --help
   
   # Check server connection
   ./bin/im connector list

3. Explore the web interface:

   • Open http://localhost:8080 in your browser
   • Note: Web UI is currently minimal - development is CLI-focused

4. Test connector framework:

   # See what connectors are available for testing
   make help | grep test-

Troubleshooting#

Common Issues#

1. Build failures:

   # Ensure Go version is 1.22+
   go version
   
   # Clean and rebuild
   make clean && make build

2. Server won’t start:

   # Check if port is available
   lsof -i :8080
   
   # Try different port
   ./bin/server --port 9090  # Note: may not work yet

3. CLI can’t connect:

   # Ensure server is running first
   curl http://localhost:8080/health
   
   # Check CLI server URL
   ./bin/im declare --api http://localhost:8080 --title "Test"

Development Status#

What’s Working#

• ✅ Basic server with health endpoint
• ✅ CLI with 15+ commands
• ✅ SQLite database storage
• ✅ Connector testing framework
• ✅ Authentication system structure
• ✅ SCIM server implementation

In Development#

• 🔄 Web user interface
• 🔄 Production deployment
• 🔄 Full connector implementations
• 🔄 Real-time WebSocket features

Next Steps#

1. CLI Reference - Learn all available CLI commands
2. Integration Testing - Test external service connections
3. Development Guide - Contribute to the project