Installation

Bob the Fixer features an intelligent one-command installer that handles everything automatically: dependency checking, port conflict resolution, container setup, and AI CLI registration.

Quick Install

From Web (Recommended)

The easiest way to install Bob the Fixer is using the bootstrap installer:

curl -fsSL https://raw.githubusercontent.com/andrearaponi/bob-the-fixer/main/install.sh | bash

This command will:

1. Clone the repository
2. Make scripts executable
3. Run the full installation process

From Source

If you already have the repository cloned:

git clone https://github.com/andrearaponi/bob-the-fixer.git
cd bob-the-fixer
./install.sh

Installation Process

The installer runs an 8-step process with interactive prompts and automatic error recovery.

Step 1: System Detection

The installer automatically detects your system configuration:

• Operating System: macOS or Linux distribution
• Architecture: x86_64 or ARM64 (Apple Silicon)
• Package Manager: brew, apt, dnf, yum, pacman
• Shell: bash, zsh, fish
• Init System: systemd, launchd

STEP 1/8: SYSTEM DETECTION
━━━━━━━━━━━━━━━━━━━━━━━━━━
  OS:              macOS
  Distribution:    Darwin
  Architecture:    arm64
  Package Manager: brew
  Shell:           zsh

Step 2: Dependency Check

All essential dependencies are verified and missing ones are installed interactively:

Dependency	Required Version	Purpose
Node.js	18.0.0+	MCP server runtime
npm	8.0.0+	Package management
git	Any	Repository cloning
Podman/Docker	Any	Container runtime
podman-compose/docker compose	Any	Container orchestration
jq	Any	JSON processing
curl	Any	HTTP requests
openssl	Any	Encryption keys

Optional dependencies (installed on request):

• Java 17+ (for local sonar-scanner)
• sonar-scanner CLI

Automatic Installation

For each missing dependency, the installer will ask:

⚠️  Node.js not found!
Do you want to install Node.js? [Y/n]:

Java 17 Upgrade Prompt

If an older Java version is detected (< 17), the installer will prompt you to upgrade:

⚠️  Java 11 detected, but Java 17+ is required for sonar-scanner

Do you want to install Java 17? [Y/n]:

Java 17 is required by sonar-scanner to perform code analysis.

Step 3: Port Check

The installer verifies that required ports are available:

Port	Service	Required
9000	SonarQube Web UI & API	Yes
5432	PostgreSQL	Internal only (no host conflict)

If port 9000 is already in use, you get three options:

⚠️  Port 9000 (SonarQube Web UI) already in use!

  Process:  java
  PID:      12345

Options:
  1) Terminate existing process
  2) Use alternative port (9001)
  3) Skip (configure manually later)
  4) Exit installation

Choice [1-4]:

Protected Processes

The installer won't terminate system-critical processes like gvproxy, podman, docker, containerd, systemd, or launchd. If a protected process is using the port, choose option 2 (alternative port) instead.

Step 4: AI CLI Check

The installer detects installed AI CLI tools and offers to install missing ones:

STEP 4/8: AI CLI CHECK
━━━━━━━━━━━━━━━━━━━━━━━━

Detected AI CLIs:
  ✓ Claude Code (claude)
  ✗ GitHub Copilot
  ✗ Google Gemini
  ✗ OpenAI Codex

Which AI CLIs would you like to install?
  1) All available
  2) Claude Code only
  3) GitHub Copilot only
  4) None (skip)

Supported AI Tools:

Tool	Command	Install Method
Claude Code	claude	npm install -g @anthropic-ai/claude-code
GitHub Copilot	gh copilot	gh extension install github/gh-copilot
OpenAI Codex	codex	Via OpenAI SDK
Google Gemini	gemini	npm install -g @google/gemini-cli

Step 5: Infrastructure Setup

This step sets up the containerized SonarQube environment:

1. Detects container runtime (Podman preferred over Docker)
2. Starts Podman machine (on macOS if needed)
3. Pulls container images:
   • PostgreSQL 15 Alpine
   • SonarQube (pinned SHA for reproducibility)
4. Creates containers with health checks
5. Waits for SonarQube to initialize (up to 180 seconds)
6. Generates admin token automatically
7. Creates .env configuration file

STEP 5/8: INFRASTRUCTURE SETUP
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
✓ Using Podman
✓ PostgreSQL image downloaded!
✓ SonarQube image downloaded!
✓ PostgreSQL container started
✓ SonarQube container started
⏳ Starting SonarQube... 45s / 180s
✓ SonarQube ready!
✓ Access token generated!
✓ Configuration saved

Generated Configuration (.env):

SONAR_URL=http://localhost:9000
SONAR_TOKEN=squ_xxxxxxxxxxxxx
SONAR_PROJECT_KEY_PREFIX=bobthefixer
NODE_ENV=development
LOG_LEVEL=info
RATE_LIMIT_ENABLED=true
ENCRYPTION_KEY=<64-char-hex>
LOG_FORMAT=text
LOG_FILE_PATH=./logs/mcp-server.log
HEALTH_CHECK_INTERVAL=30000

Step 6: Project Build

Compiles the TypeScript MCP server:

npm install           # Install dependencies
npm run build         # Compile TypeScript to JavaScript

Output: packages/core/dist/universal-mcp-server.js

Step 7: MCP Server Installation

Registers Bob the Fixer with detected AI CLIs:

For Claude Code:

claude mcp add bob-the-fixer node /path/to/universal-mcp-server.js \
  --scope user \
  --env SONAR_URL=http://localhost:9000 \
  --env SONAR_TOKEN=xxx \
  --env NODE_ENV=development \
  --env LOG_LEVEL=debug

For GitHub Copilot: Creates ~/.copilot/mcp-config.json:

{
  "mcpServers": {
    "bob-the-fixer": {
      "command": "node",
      "args": ["/path/to/universal-mcp-server.js"],
      "env": {
        "SONAR_URL": "http://localhost:9000",
        "SONAR_TOKEN": "xxx"
      }
    }
  }
}

For OpenAI Codex: Adds to ~/.codex/config.toml with extended timeouts for long-running scans.

Step 8: Final Verification

The installer performs 5 verification checks:

Check	What's Verified
Containers	PostgreSQL and SonarQube running
SonarQube API	http://localhost:9000/api/system/health responds
Token	Authentication validates successfully
MCP Server	universal-mcp-server.js exists
AI CLI	Bob the Fixer registered in at least one CLI

STEP 8/8: FINAL VERIFICATION
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
✓ Containers active
✓ SonarQube API reachable
✓ Token valid
✓ MCP server compiled
✓ Bob the Fixer registered in Claude

Checks passed: 5/5
✓ Installation verified!

Success Summary

After successful installation, you'll see:

╔══════════════════════════════════════════════════════════╗
║                                                          ║
║          🎉 BOB THE FIXER SUCCESSFULLY INSTALLED! 🎉      ║
║                                                          ║
╚══════════════════════════════════════════════════════════╝

Installation time: 2m 34s

📋 Configuration:

  SonarQube:       http://localhost:9000
  Login:           admin / admin
  Token:           squ_xxxxxxxxxxxxx
  MCP Server:      /path/to/universal-mcp-server.js

🤖 Installed AI CLIs:

  ✓ Claude Code

Next Steps:

  1. Open your project
  2. Run: claude
  3. Ask: "Analyze this project with Bob the Fixer"

Installation Log

All installation activities are logged to:

/tmp/bob-install-YYYYMMDD_HHMMSS.log

Error Recovery

If installation fails at any step, the installer offers recovery options:

❌ Error at step 5

Options:
  1) Retry this step
  2) Perform full rollback
  3) Perform partial cleanup (keep data)
  4) Exit (keep current state)

The rollback system tracks all actions and can undo:

• Container creation
• Volume creation
• Configuration file changes
• MCP registrations

Post-Installation

Verify Installation

# Check containers are running
podman ps --filter "name=bobthefixer"

# Check SonarQube is healthy
curl http://localhost:9000/api/system/health

# Check MCP registration (Claude)
claude mcp list

# Check MCP registration (Gemini)
gemini mcp list

Access SonarQube

Open http://localhost:9000 in your browser:

• Username: admin
• Password: admin

First Login

SonarQube may prompt you to change the admin password on first login. This is recommended for security.

Test Bob the Fixer

Start your AI assistant and run a test scan:

cd /path/to/your/project
claude

# Then ask:
> Scan this project with Bob the Fixer

Next Steps

• Quick Start Guide - Run your first scan
• Configuration - Customize Bob the Fixer
• Updating - Keep Bob the Fixer updated