diff --git a/package-lock.json b/package-lock.json index b5d5cf3..14d2700 100644 --- a/package-lock.json +++ b/package-lock.json @@ -3443,9 +3443,9 @@ } }, "node_modules/caniuse-lite": { - "version": "1.0.30001688", - "resolved": "https://registry.npmjs.org/caniuse-lite/-/caniuse-lite-1.0.30001688.tgz", - "integrity": "sha512-Nmqpru91cuABu/DTCXbM2NSRHzM2uVHfPnhJ/1zEAJx/ILBRVmz3pzH4N7DZqbdG0gWClsCC05Oj0mJ/1AWMbA==", + "version": "1.0.30001727", + "resolved": "https://registry.npmjs.org/caniuse-lite/-/caniuse-lite-1.0.30001727.tgz", + "integrity": "sha512-pB68nIHmbN6L/4C6MH1DokyR3bYqFwjaSs/sWDHGj4CTcFtQUQMuJftVwWkXq7mNWOybD3KhUv3oWHoGxgP14Q==", "dev": true, "funding": [ { diff --git a/src/routes/blog/setting-up-torrust-with-claude-code/+page.server.ts b/src/routes/blog/setting-up-torrust-with-claude-code/+page.server.ts new file mode 100644 index 0000000..5cf0731 --- /dev/null +++ b/src/routes/blog/setting-up-torrust-with-claude-code/+page.server.ts @@ -0,0 +1,14 @@ +import { getMetadata } from '$lib/data/metadata'; +import type { PageServerLoad } from './$types'; + +export const load: PageServerLoad = async ({ url }) => { + const slug = url.pathname.split('/').filter(Boolean).pop(); + if (!slug) throw new Error('Slug could not be determined.'); + + const metadata = await getMetadata(); + const currentPost = metadata.find((post) => post.slug === slug); + + if (!currentPost) throw new Error(`Post not found: ${slug}`); + + return { currentPost, allPosts: metadata }; +}; diff --git a/src/routes/blog/setting-up-torrust-with-claude-code/+page.svelte b/src/routes/blog/setting-up-torrust-with-claude-code/+page.svelte new file mode 100644 index 0000000..83b8ef8 --- /dev/null +++ b/src/routes/blog/setting-up-torrust-with-claude-code/+page.svelte @@ -0,0 +1,424 @@ + + + + +
+ +
+

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

+ +

Initial Setup and Analysis

+ +

What Claude Code Did Right

+ +

Comprehensive Project Analysis

+

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

+ +

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

+ +

βœ… All components built successfully without modification.

+

Step 2: Storage Directory Creation

+ +

βœ… Directory structure matched the expected configuration.

+

Major Issues Encountered and Solutions

+ +

+ Issue 1: Database Initialization Failures +

+

Error:

+ +

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

+

Fix:

+ +

+ βœ… Why it worked: Torrust expects existing DB files and doesn’t create them automatically. +

+ +

Issue 2: Port Conflicts

+

Error:

+ + +

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

+

Fix:

+ + +

βœ… Why it worked: Ensured only one instance was listening on each port.

+ +

Issue 3: CORS Configuration Problems

+

Error:

+ +

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

+

Fix:

+ +

+ βœ… 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 + +
    • +
  • + Terminal 2 – Index + +
    • +
  • + Terminal 3 – GUI + +
    • +
+

Access Points

+ + +

Clean Setup Guide for Others

+ +

🧰 Prerequisites

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

πŸ“¦ Setup Steps

+ + +

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. +

+
+
+ + +
+

Related Posts:

+
+ {#each data.allPosts.slice(0, 3) as post} + + + + {/each} +
+
+ + + diff --git a/src/routes/blog/setting-up-torrust-with-claude-code/metadata.ts b/src/routes/blog/setting-up-torrust-with-claude-code/metadata.ts new file mode 100644 index 0000000..014b7b8 --- /dev/null +++ b/src/routes/blog/setting-up-torrust-with-claude-code/metadata.ts @@ -0,0 +1,12 @@ +export const metadata = { + title: 'Setting Up Torrust with Claude Code', + slug: 'setting-up-torrust-with-claude-code', + contributor: 'Graeme Byrne', + contributorSlug: 'graeme-byrne', + date: '2025-07-09T19:53:17.990Z', + coverImage: + '/images/posts/setting-up-torrust-with-claude-code/setting-up-torrust-with-claude-code.png', + excerpt: + '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.', + tags: ['Tutorial', 'AI', 'Claude'] +}; diff --git a/static/blogMetadata.json b/static/blogMetadata.json index aa2209c..473b6ab 100644 --- a/static/blogMetadata.json +++ b/static/blogMetadata.json @@ -13,17 +13,32 @@ ] }, { - "title": "Contributor Path", - "slug": "contributor-path", + "title": "Bencode to JSON Converter in Rust", + "slug": "bencode-to-json-converter-in-rust", "contributor": "Jose Celano", "contributorSlug": "jose-celano", - "date": "2024-10-29T09:20:51.608Z", - "coverImage": "/images/posts/contributor-path/rust-crab-going-safe-into-water.webp", - "excerpt": "Ready to contribute to Torrust? Here's your guide to get started and make meaningful contributions, from small fixes to full-fledged features.", + "date": "2024-11-01T11:57:37.926Z", + "coverImage": "/images/posts/bencode-to-json-converter-in-rust/bencode-to-json-converter-in-rust.webp", + "excerpt": "We're excited to introduce bencode2json, a crate that simplifies converting Bencode data to JSON, benefiting the Rust BitTorrent community.", "tags": [ - "Community", - "Onboarding", - "Contributors" + "Bencode", + "JSON", + "Converter", + "Rust" + ] + }, + { + "title": "Deploying Torrust To Production", + "slug": "deploying-torrust-to-production", + "contributor": "Jose Celano", + "contributorSlug": "jose-celano", + "date": "2023-12-20T00:00:00.000Z", + "coverImage": "/images/posts/deploying-torrust-to-production/deploy-torrust-to-a-digital-ocean-droplet.png", + "excerpt": "Dive into our step-by-step tutorial on deploying a BitTorrent Index and Tracker, written in Rust, on a Digital Ocean droplet. From initial server setup to advanced configurations, this guide is designed for both non-developers and tech-savvy users, ensuring a seamless, production-ready deployment.", + "tags": [ + "Tutorial", + "Deployment", + "Production" ] }, { @@ -41,34 +56,17 @@ ] }, { - "title": "Bencode to JSON Converter in Rust", - "slug": "bencode-to-json-converter-in-rust", - "contributor": "Jose Celano", - "contributorSlug": "jose-celano", - "date": "2024-11-01T11:57:37.926Z", - "coverImage": "/images/posts/bencode-to-json-converter-in-rust/bencode-to-json-converter-in-rust.webp", - "excerpt": "We're excited to introduce bencode2json, a crate that simplifies converting Bencode data to JSON, benefiting the Rust BitTorrent community.", - "tags": [ - "Bencode", - "JSON", - "Converter", - "Rust" - ] - }, - { - "title": "Hash2Torrent - Retrieve Torrent Files Effortlessly!", - "slug": "hash2torrent-retrieve-torrent-files-effortlessly", + "title": "Contributor Path", + "slug": "contributor-path", "contributor": "Jose Celano", "contributorSlug": "jose-celano", - "date": "2024-09-05T10:00:00.000Z", - "coverImage": "/images/posts/hash2torrent-retrieve-torrent-files-effortlessly/hash2torrent-screenshot.png", - "excerpt": "Discover Hash2Torrent, a new tool to fetch torrent files (metainfo files) directly from their infohash! Simplify your torrent management and integrations with our easy-to-use service.", + "date": "2024-10-29T09:20:51.608Z", + "coverImage": "/images/posts/contributor-path/rust-crab-going-safe-into-water.webp", + "excerpt": "Ready to contribute to Torrust? Here's your guide to get started and make meaningful contributions, from small fixes to full-fledged features.", "tags": [ - "Service", - "Demo", - "Metainfo", - "Metadata", - "Sample" + "Community", + "Onboarding", + "Contributors" ] }, { @@ -85,17 +83,19 @@ ] }, { - "title": "Deploying Torrust To Production", - "slug": "deploying-torrust-to-production", + "title": "Hash2Torrent - Retrieve Torrent Files Effortlessly!", + "slug": "hash2torrent-retrieve-torrent-files-effortlessly", "contributor": "Jose Celano", "contributorSlug": "jose-celano", - "date": "2023-12-20T00:00:00.000Z", - "coverImage": "/images/posts/deploying-torrust-to-production/deploy-torrust-to-a-digital-ocean-droplet.png", - "excerpt": "Dive into our step-by-step tutorial on deploying a BitTorrent Index and Tracker, written in Rust, on a Digital Ocean droplet. From initial server setup to advanced configurations, this guide is designed for both non-developers and tech-savvy users, ensuring a seamless, production-ready deployment.", + "date": "2024-09-05T10:00:00.000Z", + "coverImage": "/images/posts/hash2torrent-retrieve-torrent-files-effortlessly/hash2torrent-screenshot.png", + "excerpt": "Discover Hash2Torrent, a new tool to fetch torrent files (metainfo files) directly from their infohash! Simplify your torrent management and integrations with our easy-to-use service.", "tags": [ - "Tutorial", - "Deployment", - "Production" + "Service", + "Demo", + "Metainfo", + "Metadata", + "Sample" ] }, { @@ -223,6 +223,20 @@ "Third-party" ] }, + { + "title": "Setting Up Torrust with Claude Code", + "slug": "setting-up-torrust-with-claude-code", + "contributor": "Graeme Byrne", + "contributorSlug": "graeme-byrne", + "date": "2025-07-09T19:53:17.990Z", + "coverImage": "/images/posts/setting-up-torrust-with-claude-code/setting-up-torrust-with-claude-code.png", + "excerpt": "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.", + "tags": [ + "Tutorial", + "AI", + "Claude" + ] + }, { "title": "The Enigmatic Torrent \"Source\" Field", "slug": "the-enigmatic-torrent-source-field", diff --git a/static/images/posts/setting-up-torrust-with-claude-code/setting-up-torrust-with-claude-code.png b/static/images/posts/setting-up-torrust-with-claude-code/setting-up-torrust-with-claude-code.png new file mode 100644 index 0000000..7b70f94 Binary files /dev/null and b/static/images/posts/setting-up-torrust-with-claude-code/setting-up-torrust-with-claude-code.png differ