Rust Tour

An interactive Rust learning platform featuring progressive exercises aligned with "The Rust Programming Language" book.

Overview

Rust Tour is a comprehensive learning platform that combines theoretical knowledge from the official Rust Book with hands-on coding exercises. It provides a structured pathway for developers to master Rust through progressive, test-driven exercises.

Key Features

• Progressive Learning Path: 40 exercises across 5 chapters implemented, with 200+ exercises across 20 chapters planned following the Rust Book structure
• Test-Driven Development: Each exercise includes comprehensive test suites
• Interactive Web Interface: Monaco editor with syntax highlighting and live feedback
• Integrated Terminal: Built-in terminal for running Rust commands directly
• Smart Progress Tracking: JSON-based progress persistence with learning analytics
• Multiple Exercise Types: Code completion, bug fixing, from-scratch implementation, code review, and performance optimization
• Adaptive Difficulty: Exercises scale from beginner to advanced within each chapter
• Community Driven: Open-source platform with contribution workflows

🚀 Get Started → Jump to Installation Methods | ⚡ Quick Install → Download Binary

🚀 Why We Recommend GitHub Codespaces

GitHub Codespaces provides the ideal environment for learning Rust - eliminating setup friction so you can focus entirely on mastering the language. Here's why we strongly advocate for using Codespaces:

✅ Zero Setup Barrier

• No local installation required - Start coding in seconds
• Pre-configured environment - Rust toolchain, VS Code extensions, and all dependencies ready
• Consistent experience - Same environment for every learner, regardless of their operating system
• Instant access - Works on any device with a web browser

💰 Generous Free Tier (2025)

GitHub Free Personal Accounts include:

• 120 core hours per month (60 hours of runtime on a 2-core machine)
• 15 GB of storage per month
• No payment method required to get started
• Automatic notifications when approaching usage limits

For context: 60 hours per month is more than sufficient for:

• Completing all Rust Tour exercises
• Building several practice projects
• Experimenting with advanced Rust concepts
• Contributing to open-source projects

🎯 Perfect for Learning

• Eliminate environment issues - No wrestling with PATH variables, compiler versions, or missing dependencies
• Focus on concepts - Spend time learning Rust, not debugging setup problems
• Collaborative learning - Share your exact environment with instructors or study groups
• Cross-platform consistency - Same experience on Windows, Mac, or Linux

📚 Educational Benefits

• Immediate productivity - Start learning Rust concepts from minute one
• Professional workflow - Experience industry-standard development tools
• Version control integration - Built-in Git workflow teaches best practices
• Real development environment - Not a limited sandbox or tutorial platform

🔗 Official References

• Codespaces Documentation: docs.github.com/codespaces
• Billing Information: GitHub Codespaces Billing
• Getting Started: GitHub Codespaces Features

---

💡 Transparency Disclaimer

We are not sponsored by or affiliated with GitHub in any way. This recommendation comes purely from our commitment to reducing barriers to learning Rust. After extensive testing of various development environments, GitHub Codespaces consistently provides the smoothest onboarding experience for new Rust developers. Our goal is simple: help you start writing Rust code as quickly as possible, with minimal friction.

---

Installation Methods

Quick Start Options

1. Binary Installation - Download pre-built executable (no dependencies)
2. Cargo Installation - Install via cargo (requires Rust)
3. GitHub Codespaces - Cloud-based, zero setup
4. Docker - Containerized deployment
5. Local Repository - Clone and run

GitHub Codespaces (Recommended for Learning)

With Progress Tracking (Recommended):

1. Fork this repository to your GitHub account
2. Navigate to your fork and click "Code" → "Create codespace on main"
3. Wait for environment initialization (2-3 minutes)
4. Start the application:

   ./scripts/welcome.sh
   

5. Access the web interface:
   • Automatic: Codespaces will show a popup notification with a link to open the forwarded port
   • Manual: Click the "Ports" tab in VS Code and open the forwarded URL for port 3000
   • Direct: Access at http://localhost:3000 if running locally
6. Your progress will be saved to your fork automatically

Without Progress Tracking:

1. Navigate to the main repository and click "Code" → "Create codespace on main"
2. Wait for environment initialization (2-3 minutes)
3. Start the application:

   ./scripts/welcome.sh
   

4. Access the web interface:
   • Automatic: Codespaces will show a popup notification with a link to open the forwarded port
   • Manual: Click the "Ports" tab in VS Code and open the forwarded URL for port 3000

Docker Installation

Using Docker Compose (Recommended):

1. Clone the repository:

   git clone https://github.com/ghanithan/rust-tour.git
   cd rust-tour
   

2. Start with Docker Compose:

   docker-compose up -d
   

3. Access the application at http://localhost:3000

4. Stop the application:

   docker-compose down
   

Using Docker directly:

# Build and run
docker build -t rust-tour .
docker run -d \
  --name rust-tour \
  -p 3000:3000 \
  -v $(pwd)/progress:/app/progress \
  rust-tour

# Management commands
docker logs rust-tour
docker stop rust-tour && docker rm rust-tour

Using Pre-built Images from GitHub Container Registry:

For stable releases (recommended for production):

# Docker Compose with latest stable release
docker-compose -f docker-compose.ghcr.yml up -d

# Or direct Docker run
docker run -d \
  --name rust-tour \
  -p 3000:3000 \
  -v $(pwd)/progress:/app/progress \
  ghcr.io/ghanithan/rust-tour:latest

For development/testing with latest main branch:

# Use latest development build from main branch
docker run -d \
  --name rust-tour-dev \
  -p 3000:3000 \
  -v $(pwd)/progress:/app/progress \
  ghcr.io/ghanithan/rust-tour:main-latest

Available image tags:

Production Tags (stable releases):

• latest - Latest stable release with embedded assets (production-optimized)
• v0.1.0 - Specific version releases with embedded assets (production-optimized)
• 0.1 - Latest patch in minor version series with embedded assets
• 0 - Latest minor in major version series with embedded assets

Development Tags (main branch):

• main-latest - Latest development build from main branch (fast builds, separate web files)
• main-abc123 - Specific commit from main branch for traceability

Build Differences:

• Production images (latest, version tags): Built with Dockerfile.prod, full optimization, embedded assets
• Development images (main-latest, main-*): Built with Dockerfile, fast compilation, separate web files for debugging

For Development:

# Use the development Docker setup with hot reload
docker-compose -f docker-compose.dev.yml up

# This provides:
# - Live code reloading
# - Development tools (cargo-watch, etc.)
# - Both Rust server (3000) and Vite dev server (5173)

Binary Installation (Quick Setup)

Download pre-built binaries for your platform - no Rust toolchain required!

macOS

# Download the latest release for macOS (Apple Silicon)
curl -L https://github.com/ghanithan/rust-tour/releases/latest/download/rust-tour-aarch64-apple-darwin.tar.gz -o rust-tour.tar.gz

# Extract the binary
tar -xzf rust-tour.tar.gz

# Make it executable and move to a directory in your PATH
chmod +x rust-tour
sudo mv rust-tour /usr/local/bin/

# Verify installation
rust-tour --version

# Start learning!
rust-tour

Linux

# Download the latest release for Linux (x86_64)
wget https://github.com/ghanithan/rust-tour/releases/latest/download/rust-tour-x86_64-unknown-linux-gnu.tar.gz

# Extract the binary
tar -xzf rust-tour-x86_64-unknown-linux-gnu.tar.gz

# Make it executable and move to a directory in your PATH
chmod +x rust-tour
sudo mv rust-tour /usr/local/bin/

# Verify installation
rust-tour --version

# Start learning!
rust-tour

Alternative without sudo:

# Extract to your home directory
mkdir -p ~/.local/bin
tar -xzf rust-tour-x86_64-unknown-linux-gnu.tar.gz -C ~/.local/bin/
chmod +x ~/.local/bin/rust-tour

# Add to PATH if not already there
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc

# Start learning!
rust-tour

Windows

Option 1: PowerShell (Recommended)

# Download the latest release for Windows
Invoke-WebRequest -Uri "https://github.com/ghanithan/rust-tour/releases/latest/download/rust-tour-x86_64-pc-windows-msvc.zip" -OutFile "rust-tour.zip"

# Extract the archive
Expand-Archive -Path "rust-tour.zip" -DestinationPath "."

# Move to a directory in your PATH (e.g., C:\Windows\System32 or create a custom directory)
# Option A: System-wide (requires admin)
Move-Item -Path "rust-tour.exe" -Destination "C:\Windows\System32\rust-tour.exe"

# Option B: User directory (no admin required)
New-Item -ItemType Directory -Force -Path "$env:USERPROFILE\bin"
Move-Item -Path "rust-tour.exe" -Destination "$env:USERPROFILE\bin\rust-tour.exe"
# Add to PATH: Settings → System → About → Advanced system settings → Environment Variables
# Add %USERPROFILE%\bin to your user PATH variable

# Verify installation
rust-tour --version

# Start learning!
rust-tour

Option 2: Manual Download

1. Go to Releases Page
2. Download rust-tour-x86_64-pc-windows-msvc.zip
3. Extract the zip file
4. Move rust-tour.exe to a directory in your PATH
5. Open Command Prompt or PowerShell and run rust-tour

Post-Installation

After installing the binary, on first run:

• Rust Tour will guide you through downloading the exercises (~5MB)
• Choose where to store your exercises (default: ~/rust-tour-exercises)
• Your progress is automatically saved between sessions

All platforms support these options:

rust-tour --help                    # Show help and available options
rust-tour --port 8080              # Use a custom port
rust-tour --exercises-path /path   # Use exercises from a specific location

Cargo Installation (Recommended for Rust Developers)

If you already have Rust installed, you can use cargo for automatic updates:

# Install Rust Tour
cargo install rust-tour

# Start learning
rust-tour

First-time setup:

• On first run, Rust Tour will guide you through downloading the exercises
• You'll choose where to store your exercises and progress (default: ~/rust-tour-exercises)
• Download size is approximately 5MB and takes 10-30 seconds
• Your progress is automatically saved between sessions

What happens on first run:

1. Welcome screen with information about the exercises
2. Prompt to download exercises from GitHub
3. Choose your preferred storage location
4. Automatic download and setup
5. Server starts with the web interface at http://localhost:3000

Subsequent runs:

• Rust Tour remembers your exercise location
• Starts immediately without any prompts
• All your progress is preserved

Command-line options:

rust-tour --help                    # Show help and available options
rust-tour --port 8080              # Use a custom port
rust-tour --exercises-path /path   # Use exercises from a specific location

Local Repository Installation (End Users)

For using the pre-built application:

1. Prerequisites: Git only
2. Clone and run:

   git clone https://github.com/ghanithan/rust-tour.git
   cd rust-tour
   ./scripts/welcome.sh
   

3. Access the application at http://localhost:3000

Local Development Installation (Contributors)

For development and customization:

1. Prerequisites:

   • Rust toolchain (1.75.0 or later)
   • Node.js (18.0 or later)
   • Git

2. Clone and setup:

   git clone https://github.com/ghanithan/rust-tour.git
   cd rust-tour
   ./scripts/run.sh setup
   

3. Start development servers:

   ./scripts/run.sh dev
   

   This starts both the Rust server and web development server with hot reloading.

Working with Exercises

Exercise Structure

Each exercise is a standalone Cargo project located in the exercises/ directory:

exercises/
├── ch01_getting_started/
│   ├── ex01_hello_world/
│   │   ├── Cargo.toml
│   │   ├── README.md
│   │   ├── metadata.json
│   │   ├── src/main.rs
│   │   ├── tests/unit_tests.rs
│   │   └── hints.md
│   └── ex02_hello_cargo/
└── ch02_guessing_game/

Running Tests for Individual Exercises

Navigate to any exercise directory and run tests:

# Navigate to specific exercise
cd exercises/ch01_getting_started/ex01_hello_world

# Run all tests for this exercise
cargo test

# Run tests with output displayed
cargo test -- --nocapture

# Run a specific test
cargo test test_hello_world_output

# Check your solution
cargo run

# Verify code quality
cargo clippy -- -D warnings
cargo fmt --check

Checking Exercise Solutions

# Run tests to validate your solution
cargo test

# Check code quality
cargo clippy -- -D warnings
cargo fmt --check

# Or manually compare with reference solution (if available)
diff src/main.rs ../../../solutions/ch01/ex01/main.rs

Architecture

graph TB
    subgraph "User Interface"
        A[Web Browser] --> B[React Frontend]
        B --> C[Monaco Editor]
        B --> D[Progress Dashboard]
        B --> E[Integrated Terminal]
    end
    
    subgraph "Backend Services"
        F[Rust Web Server] --> G[Exercise Framework]
        F --> H[Progress Tracker]
        F --> I[Terminal Emulator]
        G --> J[Test Runner]
        G --> K[Solution Validator]
    end
    
    subgraph "Content Layer"
        L[Exercise Repository]
        M[Test Suites]
        N[Reference Solutions]
        O[Progress Storage]
    end
    
    B <--> F
    E <--> I
    G --> L
    J --> M
    K --> N
    H <--> O
    
    style A fill:#f9f,stroke:#333,stroke-width:2px
    style F fill:#ff9,stroke:#333,stroke-width:2px
    style L fill:#9ff,stroke:#333,stroke-width:2px

Component Overview

• Web Interface (web/): TypeScript/React application providing the interactive learning environment
• Web Server (web-server/): Rust-based backend handling API requests and terminal emulation
• Exercise Framework (exercise-framework/): Core logic for exercise validation and progress tracking
• Exercises (exercises/): Structured learning content with tests and hints
• Scripts (scripts/): Automation tools for development and exercise management

Learning Path

The curriculum follows "The Rust Programming Language" book structure:

1. Getting Started - Basic syntax and tooling
2. Programming a Guessing Game - First complete program
3. Common Programming Concepts - Variables, types, functions, control flow
4. Understanding Ownership - Rust's core memory management concept
5. Using Structs - Custom data types
6. Enums and Pattern Matching - Algebraic data types
7. Managing Growing Projects - Modules, packages, and crates
8. Common Collections - Vectors, strings, hash maps
9. Error Handling - Result and Option types
10. Generic Types, Traits, and Lifetimes - Advanced type system features

Each chapter contains 6-12 exercises progressing from basic to advanced concepts. Currently 5 chapters (40 exercises, ~16 hours of content) are implemented:

• Chapter 1: Getting Started (6 exercises)
• Chapter 2: Guessing Game (8 exercises)
• Chapter 3: Common Concepts (12 exercises)
• Chapter 4: Understanding Ownership (6 exercises)
• Chapter 5: Using Structs (8 exercises)

Development Workflow

Running the Full Test Suite

# Run all exercise tests
./scripts/run.sh test

# Run framework tests
cargo test --workspace

# Run web tests (if in development mode)
cd web && npm test

# Test Docker build
docker build -t rust-tour-test .

Docker Development Commands

# Build Docker image with automated script
./scripts/build-docker.sh

# Test the built image
./scripts/test-docker.sh

# Manual build and run
docker build -t rust-tour .
docker run -d \
  --name rust-tour \
  -p 3000:3000 \
  -v $(pwd)/progress:/app/progress \
  rust-tour

# Development with volume mounts
docker run -d \
  --name rust-tour-dev \
  -p 3000:3000 \
  -v $(pwd)/exercises:/app/exercises:ro \
  -v $(pwd)/progress:/app/progress \
  rust-tour

# View container logs and management
docker logs -f rust-tour
docker exec -it rust-tour sh
docker stop rust-tour && docker rm rust-tour

Creating New Exercises

# Manually create the structure
mkdir -p exercises/ch04_understanding_ownership/ex05_ownership_puzzle
cd exercises/ch04_understanding_ownership/ex05_ownership_puzzle
cargo init

# Add test structure
mkdir tests
touch tests/unit_tests.rs hints.md README.md metadata.json

Release Process

We use an automated release process with AI-generated release notes:

Creating a Release:

1. Go to Actions tab in GitHub
2. Run "Create Release" workflow
3. Enter version number (e.g., 0.1.0)
4. Select release type (patch, minor, major)
5. The workflow will:
   • Run full validation suite
   • Generate AI-powered release notes
   • Create git tag and GitHub release
   • Trigger Docker image builds automatically

Manual Release Steps (Alternative):

# Create and push a version tag
git tag v0.1.0
git push origin v0.1.0

# This automatically triggers the release workflow
# Docker images will be built and published to GHCR

Release Artifacts:

• GitHub Release with generated changelog
• Docker Images on GHCR:
  • ghcr.io/ghanithan/rust-tour:latest (production)
  • ghcr.io/ghanithan/rust-tour:v0.1.0 (specific version)
  • ghcr.io/ghanithan/rust-tour:0.1 (minor series)
  • ghcr.io/ghanithan/rust-tour:0 (major series)
  • ghcr.io/ghanithan/rust-tour:main-latest (development)

Code Quality Standards

All contributions must pass:

# Rust formatting
cargo fmt --all -- --check

# Rust linting
cargo clippy --all-targets --all-features -- -D warnings

# JavaScript/TypeScript
cd web && npm run lint

# Docker build test
docker build -t rust-tour-test .

Contributing

We welcome contributions from the community. Please read our Contributing Guide for details on:

• Code style and standards
• Exercise creation guidelines
• Testing requirements
• Pull request process

Quick Contribution Checklist

1. Fork the repository and create a feature branch
2. Write tests for any new functionality
3. Ensure all tests pass locally
4. Update documentation as needed
5. Submit a pull request with clear description

Areas for Contribution

• New Exercises: Expand existing chapters or propose new topics
• Improved Hints: Enhance the progressive hint system
• UI/UX Improvements: Better visualization and interactivity
• Performance Optimizations: Speed up test execution and validation
• Documentation: Tutorials, guides, and API documentation
• Translations: Localize content for non-English speakers

Technical Requirements

Minimum System Requirements

• OS: Linux, macOS, or Windows (with WSL2)
• RAM: 4GB minimum, 8GB recommended
• Disk: 2GB free space
• Network: Internet connection for initial setup

Supported Browsers

• Chrome/Chromium 90+
• Firefox 88+
• Safari 14+
• Edge 90+

License

This project is licensed under the MIT License - see the LICENSE file for details.

The MIT License is one of the most permissive licenses, allowing you to use, modify, and distribute this software freely for any purpose, including commercial use.

Acknowledgments

• GitHub Codespaces for providing the perfect development environment
• The Rust Team for creating an exceptional language and comprehensive documentation
• The Rust community for continuous feedback and contributions
• All contributors who help improve this learning platform

Documentation

For comprehensive guides, tutorials, and detailed documentation, visit our Wiki which includes:

• Installation & Setup Guide - Detailed installation for all platforms
• Exercise Guide - How to work with exercises effectively
• Contributing Guide - Guidelines for contributors
• FAQ & Troubleshooting - Solutions to common issues

Support

• Issues: Report bugs via GitHub Issues
• Discussions: Join our GitHub Discussions
• Documentation: Visit our Wiki

---

Ready to begin your Rust journey? Start with Chapter 1 or jump to any topic that interests you!