BugTraceAI-Launcher

BugTraceAI-Launcher

BugTraceAI-Launcher is a one-command Docker deployment wizard that handles the complete setup and lifecycle management of the BugTraceAI platform. It automates dependency detection, port management, service configuration, container orchestration, and an optional AI Setup & Repair Assistant that can install or diagnose and repair a deployment.

Repository: github.com/BugTraceAI/BugTraceAI-Launcher

---

Overview

The Launcher eliminates the complexity of manually deploying and configuring BugTraceAI components. A single command handles everything:

git clone https://github.com/BugTraceAI/BugTraceAI-Launcher.git
cd BugTraceAI-Launcher
./launcher.sh

The interactive wizard guides you through:

1. Selecting a deployment mode
2. Checking system requirements
3. Pulling and building Docker images
4. Configuring environment variables
5. Starting all services
6. Running health checks
7. Displaying access URLs

As of v2.8.7, the provider selector and the AI Setup & Repair Assistant can both use Anthropic (Claude direct API, x-api-key / Messages API) in addition to OpenRouter and Z.ai. The assistant runs on DeepSeek V3 (via OpenRouter) or Claude Haiku 4.5 (Anthropic direct), selected at startup.

---

Features

Feature	Description
Interactive Wizard	Step-by-step guided setup
Auto-Dependency Detection	Checks for Docker, Git, and system requirements; installs Git/curl via apt, dnf, yum, pacman, or zypper, and Docker Compose if missing
Port Management	Detects port conflicts and suggests alternatives (including the PostgreSQL host port)
Three Deployment Modes	Full Platform, Standalone WEB, Standalone CLI (plus optional MCP add-ons)
Service Lifecycle	Start, stop, restart, update, uninstall
Health Checks	Verifies all services are running correctly
Log Access	View logs from any service
Hardened secrets	Generated .env / .env.docker are written with 600 permissions
AI Setup & Repair Assistant	Optional agent (DeepSeek V3 with automatic Claude Haiku 4.5 fallback) that can install from scratch or diagnose and repair an existing deployment

---

Installation

Requirements

• Docker 24.0 or higher
• Git
• 4 GB RAM minimum (8 GB recommended)
• 10 GB disk space
• OpenRouter API key (for AI functionality)

Quick Start

git clone https://github.com/BugTraceAI/BugTraceAI-Launcher.git
cd BugTraceAI-Launcher
./launcher.sh

The Launcher installs to ~/bugtraceai/ by default. No sudo required — only Docker group permissions are needed.

AI Setup & Repair Assistant

BugTraceAI-Launcher includes an optional AI Setup & Repair Assistant (ai_installer.py), which runs on DeepSeek V3 by default with an automatic, sticky fallback to Claude Haiku 4.5 (both via OpenRouter; override either model with the BTAI_INSTALLER_MODEL / BTAI_INSTALLER_FALLBACK_MODEL environment variables). It is no longer troubleshooting-only: a first menu lets you choose between installing BugTraceAI from scratch and repairing or diagnosing an existing deployment (failed services, database connectivity, Docker, ports, broken configuration). You then pick the scope — Full Platform, CLI only, or WEB only. In repair mode the agent diagnoses first and never reinstalls or deletes anything without asking.

The one-liner prompts before entering AI mode:

Try the AI Setup & Repair Assistant (Experimental — installs & troubleshoots)? [y/N]

If you choose AI mode, the assistant shows a risk warning and asks for a [y/N] confirmation before it starts. The OpenRouter API key is entered with hidden input (it never appears on screen) and only a masked form is shown back. It then runs shell commands through its run_command tool in a stateful, persistent Bash shell — commands that look destructive (including docker compose down -v, which would wipe the named database volumes) require an explicit confirmation, and each command runs under a kernel-enforced timeout so a hung command can’t stall the install. The conversation runs in English. Use this mode mainly on clean VMs, VPS instances, or disposable test environments.

---

Commands

Command	Description
./launcher.sh	Launch the interactive setup wizard
./launcher.sh status	Show status of all services
./launcher.sh start	Start all services
./launcher.sh stop	Stop all services
./launcher.sh restart	Restart all services
./launcher.sh update	Pull latest images and restart
./launcher.sh uninstall	Remove all containers, images, and data
./launcher.sh logs	View logs from all services
./launcher.sh logs <service>	View logs from a specific service

---

Deployment Modes

The Launcher supports three deployment modes. See Deployment Modes for detailed descriptions.

Mode	Components	Best For
Full Platform	WEB + CLI (auto-connected)	Complete scanning platform
Standalone WEB	Dashboard only	AI analysis tools, no active scanning
Standalone CLI	Headless API server	CI/CD, scripted scanning, API-only

Full Platform Mode

The recommended mode. Deploys both WEB and CLI, automatically configures the connection between them (CORS, VITE_CLI_API_URL), and starts all services.

./launcher.sh
# Select: Full Platform

Services started:

• BugTraceAI-CLI (FastAPI on port 8000)
• BugTraceAI-WEB Frontend (Nginx on port 6869)
• BugTraceAI-WEB Backend (Express on port 3001)
• PostgreSQL (port 5432, internal)

Standalone Modes

Each standalone mode runs its own Docker Compose project:

./launcher.sh
# Select: Standalone WEB  (or)  Standalone CLI

---

Architecture

+-------------------------------------------------------+
|                  BugTraceAI-Launcher                   |
|                                                        |
|  +------------------+                                  |
|  | launcher.sh      |  Interactive wizard              |
|  +--------+---------+                                  |
|           |                                            |
|           v                                            |
|  +------------------+                                  |
|  | Docker Compose   |  Container orchestration         |
|  +--------+---------+                                  |
|           |                                            |
|     +-----+-----+-----+-----+                         |
|     |           |           |                          |
|     v           v           v                          |
|  +------+   +------+   +------+                       |
|  | CLI  |   | WEB  |   | WEB  |                       |
|  | :8000|   | :6869|   | :3001|                       |
|  +------+   +------+   +------+                       |
|                            |                           |
|                            v                           |
|                      +----------+                      |
|                      | Postgres |                      |
|                      | :5432    |                      |
|                      +----------+                      |
+-------------------------------------------------------+

---

Configuration

Auto-Configuration

In Full Platform mode, the Launcher automatically configures:

• VITE_CLI_API_URL: Points the WEB frontend to the CLI API
• CORS settings: Allows the WEB to communicate with the CLI
• PostgreSQL connection: Configures the WEB backend database
• Docker networking: Sets up inter-container communication

Environment Variables

The Launcher generates the configuration files during setup (created with 600 permissions, since they hold secrets). The CLI .env:

# Generated by BugTraceAI-Launcher
PROVIDER=openrouter            # or zai (Z.ai / GLM)
OPENROUTER_API_KEY=sk-or-v1-...
BUGTRACE_CORS_ORIGINS=*

and the WEB .env.docker (PostgreSQL credentials, FRONTEND_PORT, conflict-checked POSTGRES_PORT, VITE_CLI_API_URL).

Custom Configuration

After initial setup, edit ~/bugtraceai/.env to customize settings, then restart:

./launcher.sh restart

---

Updating

./launcher.sh update

This pulls the latest Docker images, rebuilds if necessary, and restarts all services with zero-downtime where possible.

---

Troubleshooting

Check Service Status

./launcher.sh status

View Logs

# All services
./launcher.sh logs

# Specific service
./launcher.sh logs cli
./launcher.sh logs web

Port Conflicts

If a required port is already in use, the Launcher will detect the conflict and suggest alternatives. You can also manually change ports in the .env file.

Docker Permissions

If you encounter Docker permission errors, ensure your user is in the docker group:

sudo usermod -aG docker $USER
# Log out and back in for the change to take effect

---

Uninstalling

./launcher.sh uninstall

This removes:

• All BugTraceAI Docker containers
• All BugTraceAI Docker images
• The ~/bugtraceai/ installation directory
• Generated configuration files

It does not remove Docker itself or other unrelated containers.

---

Sub-Pages

Page	Description
Deployment Modes	Detailed comparison of Full Platform, Standalone WEB, and Standalone CLI modes

---

See also: Getting Started | Architecture | Deployment Modes