Setting Up Torrust with Claude Code

A Complete Development Environment Guide

Based on a real terminal session, this guide documents the complete process of setting up the Torrust BitTorrent index development environment using Claude Code, including all the challenges encountered and solutions applied.

Overview

Torrust is a modern BitTorrent index system built with Rust and Vue.js, consisting of three main components:

• torrust-tracker – BitTorrent tracker backend (Rust)
• torrust-index – API backend for torrent indexing (Rust)
• torrust-index-gui – Web frontend (Nuxt.js/Vue.js)

Setting Up Torrust with Claude Code

Comprehensive Project Analysis

Claude Code immediately analyzed the project structure and identified all components:

📁 torrust-tracker/      # Rust BitTorrent tracker
📁 torrust-index/        # Rust API backend
📁 torrust-index-gui/    # Nuxt.js frontend
📄 docker-compose.yml    # Container orchestration
📄 .env                  # Environment configuration

Dependency Verification

Claude Code verified the presence of required tools:

• ✅ Rust toolchain (including nightly)
• ✅ Node.js v20.12.2
• ✅ Development tools (imdl, sqlx-cli)

Following Official Documentation

Claude Code followed the official Torrust development guide, ensuring full compatibility with the intended setup process.

Build Process

Step 1: Building Components

# Build Torrust Tracker
cd torrust-tracker && cargo build

# Build Torrust Index  
cd torrust-index && cargo build

# Setup GUI dependencies
cd torrust-index-gui && npm install
cp .env.local .env

✅ All components built successfully without modification.

Step 2: Storage Directory Creation

# Tracker storage directories
mkdir -p ./torrust-tracker/storage/tracker/lib/database
mkdir -p ./torrust-tracker/storage/tracker/lib/tls
mkdir -p ./torrust-tracker/storage/tracker/etc

# Index storage directories
mkdir -p ./torrust-index/storage/index/lib/database
mkdir -p ./torrust-index/storage/index/lib/tls

✅ Directory structure matched the expected configuration.

Major Issues Encountered and Solutions

Issue 1: Database Initialization Failures

Error:

unable to open database file: ./storage/tracker/lib/database/sqlite3.db
thread 'main' panicked...

Root Cause: The app expected an existing SQLite DB file.

Fix:

touch storage/tracker/lib/database/sqlite3.db
touch storage/index/lib/database/sqlite3.db

✅ Why it worked: Torrust expects existing DB files and doesn’t create them automatically.

Issue 2: Port Conflicts

Error:

importer API TCP listener to bind to socket address: Os { code: 48, ... "Address already in use" }

Root Cause: Multiple Index services running on the same port.

Fix:

lsof -i :3001
kill <pid>

✅ Why it worked: Ensured only one instance was listening on each port.

Issue 3: CORS Configuration Problems

Error:

Access to fetch at 'http://localhost:3001/v1/user/token/renew' from origin 'http://localhost:3000' has been blocked by CORS policy...

Root Cause: The required CORS environment variable wasn’t set.

Fix:

TORRUST_INDEX_API_CORS_PERMISSIVE=true cargo run

✅ Why it worked: Claude identified TORRUST_INDEX_API_CORS_PERMISSIVE from source code and activated permissive CORS.

How Claude Code Helped

• 🔍 Systematic Debugging
  • Analyzed logs line-by-line
  • Identified root causes instead of surface fixes
  • Used diagnostic tools like lsof, curl
• 📖 Code Analysis
  • Read source code to identify config logic
  • Found undocumented environment variables
  • Verified DB initialization logic in Rust code
• ⚙️ Service Orchestration
  • Ensured proper service startup order
  • Understood dependencies between services
• ✅ Testing and Verification
  • Used curl to test APIs
  • Verified CORS headers
  • Confirmed DB presence

Final Working Setup

Required Running Services (3 terminals)

• Terminal 1 – Tracker
  bash

  Copy Code

  cd torrust-tracker
  cargo run

• Terminal 2 – Index
  bash

  Copy Code

  cd torrust-index
  TORRUST_INDEX_API_CORS_PERMISSIVE=true cargo run

• Terminal 3 – GUI
  bash

  Copy Code

  cd torrust-index-gui
  npm run dev

Access Points

• 🌐 GUI: http://localhost:3000/
• 🔗 Index API: http://localhost:3001/
• 🎯 Tracker: UDP: 6969, HTTP: 7070, API: 1212

Clean Setup Guide for Others

🧰 Prerequisites

• Rust (nightly)
• Node.js v20.12.2+
• Git

📦 Setup Steps

# Install Rust tools
cargo install imdl sqlx-cli

# Clone repos
mkdir torrust-dev && cd torrust-dev
git clone https://github.com/torrust/torrust-tracker.git
git clone https://github.com/torrust/torrust-index.git
git clone https://github.com/torrust/torrust-index-gui.git

# Build tracker
cd torrust-tracker && cargo build
mkdir -p storage/tracker/lib/database storage/tracker/lib/tls storage/tracker/etc
touch storage/tracker/lib/database/sqlite3.db

# Build index
cd ../torrust-index && cargo build
mkdir -p storage/index/lib/database storage/index/lib/tls
touch storage/index/lib/database/sqlite3.db

# Setup GUI
cd ../torrust-index-gui && npm install
cp .env.local .env

Key Takeaways

• Database Files Are Critical: Must be created manually before app startup
• CORS Must Be Explicitly Enabled: Set TORRUST_INDEX_API_CORS_PERMISSIVE=true
• Service Dependencies Matter: GUI → Index → Tracker (start in that order)
• Expected 404s Are Normal: Token endpoint returns 404 if no user is logged in
• Claude Code Excels at Systematic Setup: It debugged, read source, and diagnosed like a seasoned engineer

Conclusion

This setup process demonstrates how Claude Code can assist with complex multi-service development environments. By combining log analysis, source code reading, and iterative testing, it enabled a clean and fully functional Torrust development environment — even in the face of port conflicts, missing DBs, and CORS issues.