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

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

GitHub Codespaces (Recommended for Learning)

With Progress Tracking (Recommended):

Fork this repository to your GitHub account
Navigate to your fork and click "Code" → "Create codespace on main"
Wait for environment initialization (2-3 minutes)
Start the application:
```
./scripts/welcome.sh
```
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
Your progress will be saved to your fork automatically

Without Progress Tracking:

Navigate to the main repository and click "Code" → "Create codespace on main"
Wait for environment initialization (2-3 minutes)
Start the application:
```
./scripts/welcome.sh
```
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):

Clone the repository:

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

Start with Docker Compose:
```
docker-compose up -d
```
Access the application at http://localhost:3000
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

Go to Releases Page
Download rust-tour-x86_64-pc-windows-msvc.zip
Extract the zip file
Move rust-tour.exe to a directory in your PATH
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:

Welcome screen with information about the exercises
Prompt to download exercises from GitHub
Choose your preferred storage location
Automatic download and setup
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:

Prerequisites: Git only

Clone and run:

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

Access the application at http://localhost:3000

Local Development Installation (Contributors)

For development and customization:

Prerequisites:
- Rust toolchain (1.75.0 or later)
- Node.js (18.0 or later)
- Git

Clone and setup:

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

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:

Getting Started - Basic syntax and tooling
Programming a Guessing Game - First complete program
Common Programming Concepts - Variables, types, functions, control flow
Understanding Ownership - Rust's core memory management concept
Using Structs - Custom data types
Enums and Pattern Matching - Algebraic data types
Managing Growing Projects - Modules, packages, and crates
Common Collections - Vectors, strings, hash maps
Error Handling - Result and Option types
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:

Go to Actions tab in GitHub
Run "Create Release" workflow
Enter version number (e.g., 0.1.0)
Select release type (patch, minor, major)
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

Fork the repository and create a feature branch
Write tests for any new functionality
Ensure all tests pass locally
Update documentation as needed
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!

Name		Name	Last commit message	Last commit date
Latest commit History 103 Commits
.claude/agents		.claude/agents
.devcontainer		.devcontainer
.github		.github
.vscode		.vscode
docs		docs
exercise-framework		exercise-framework
exercises		exercises
node_modules		node_modules
scripts		scripts
web-server		web-server
web		web
.dockerignore		.dockerignore
.gitignore		.gitignore
CLAUDE.md		CLAUDE.md
CONTRIBUTING.md		CONTRIBUTING.md
Cargo.lock		Cargo.lock
Cargo.toml		Cargo.toml
DIRECTORY_BROWSER_FEATURE.md		DIRECTORY_BROWSER_FEATURE.md
Dockerfile		Dockerfile
Dockerfile.base-alpine		Dockerfile.base-alpine
Dockerfile.dev		Dockerfile.dev
Dockerfile.prod		Dockerfile.prod
Dockerfile.simple		Dockerfile.simple
LICENSE		LICENSE
README.md		README.md
docker-compose.dev.yml		docker-compose.dev.yml
docker-compose.ghcr.yml		docker-compose.ghcr.yml
docker-compose.yml		docker-compose.yml
package-lock.json		package-lock.json
test_browser.sh		test_browser.sh

License

ghanithan/rust-tour

Folders and files

Latest commit

History

Repository files navigation

Rust Tour

Overview

Key Features

🚀 Why We Recommend GitHub Codespaces

✅ Zero Setup Barrier

💰 Generous Free Tier (2025)

🎯 Perfect for Learning

📚 Educational Benefits

🔗 Official References

💡 Transparency Disclaimer

Installation Methods

Quick Start Options

GitHub Codespaces (Recommended for Learning)

Docker Installation

Binary Installation (Quick Setup)

macOS

Linux

Windows

Post-Installation

Cargo Installation (Recommended for Rust Developers)

Local Repository Installation (End Users)

Local Development Installation (Contributors)

Working with Exercises

Exercise Structure

Running Tests for Individual Exercises

Checking Exercise Solutions

Architecture

Component Overview

Learning Path

Development Workflow

Running the Full Test Suite

Docker Development Commands

Creating New Exercises

Release Process

Code Quality Standards

Contributing

Quick Contribution Checklist

Areas for Contribution

Technical Requirements

Minimum System Requirements

Supported Browsers

License

Acknowledgments

Documentation

Support

About

Resources

License

Contributing

Uh oh!

Stars

Watchers

Forks

Releases 13

Packages 0

Uh oh!

Contributors 3

Uh oh!

Languages

Packages