Step-by-step guide to install and set up Rustic Debug

Tags: installationsetupgetting-started

Installation Guide

Get Rustic Debug up and running in your environment with these installation methods.

Prerequisites

Before installing Rustic Debug, ensure you have:

Node.js v18.0 or higher (for npm installation)
Redis v6.0 or higher running and accessible
RusticAI application using Redis for messaging
Modern web browser (Chrome, Firefox, Safari, Edge)

Installation Methods

Method 1: NPM (Recommended)

The quickest way to get started with Rustic Debug.

# Install globally
npm install -g @rustic-ai/rustic-debug

# Or with yarn
yarn global add @rustic-ai/rustic-debug

# Or with pnpm
pnpm add -g @rustic-ai/rustic-debug

Verify Installation

# Check version
rustic-debug --version

# View help
rustic-debug --help

Method 2: Docker

Run Rustic Debug in a containerized environment.

# Pull the latest image
docker pull rusticai/rustic-debug:latest

# Run the container
docker run -d \
  --name rustic-debug \
  -p 3000:3000 \
  -e REDIS_URL=redis://host.docker.internal:6379 \
  rusticai/rustic-debug

Docker Compose

Create a docker-compose.yml:

version: '3.8'
services:
  rustic-debug:
    image: rusticai/rustic-debug:latest
    ports:
      - "3000:3000"
    environment:
      - REDIS_URL=redis://redis:6379
      - NODE_ENV=production
    depends_on:
      - redis
    networks:
      - rustic-network

  redis:
    image: redis:7-alpine
    ports:
      - "6379:6379"
    networks:
      - rustic-network

networks:
  rustic-network:
    driver: bridge

Then run:

docker-compose up -d

Method 3: From Source

Build and run from the source code.

# Clone the repository
git clone https://github.com/rustic-ai/rustic-debug.git
cd rustic-debug

# Install dependencies
pnpm install

# Build the project
pnpm build

# Start the application
pnpm start

Development Mode

# Run in development mode with hot reload
pnpm dev

# Run frontend and backend separately
pnpm --filter frontend dev
pnpm --filter backend dev

Method 4: Kubernetes

Deploy to a Kubernetes cluster using Helm.

# Add the Rustic helm repository
helm repo add rustic https://charts.rustic.ai
helm repo update

# Install Rustic Debug
helm install rustic-debug rustic/rustic-debug \
  --set redis.url=redis://my-redis-service:6379 \
  --set ingress.enabled=true \
  --set ingress.host=debug.example.com

Configuration

Basic Configuration

After installation, configure Rustic Debug to connect to your Redis instance:

# Start with basic configuration
rustic-debug start \
  --redis-url redis://localhost:6379 \
  --port 3000 \
  --host 0.0.0.0

Advanced Configuration

Create a configuration file rustic-debug.config.json:

{
  "redis": {
    "url": "redis://localhost:6379",
    "password": "your-password",
    "db": 0,
    "connectionTimeout": 5000,
    "reconnectStrategy": "exponential"
  },
  "server": {
    "port": 3000,
    "host": "0.0.0.0",
    "cors": {
      "enabled": true,
      "origins": ["http://localhost:*"]
    }
  },
  "debug": {
    "readOnly": true,
    "maxMessages": 10000,
    "retentionHours": 24
  },
  "auth": {
    "enabled": false,
    "token": "your-secret-token"
  }
}

Load the configuration:

rustic-debug start --config ./rustic-debug.config.json

Environment Variables

You can also use environment variables:

export REDIS_URL=redis://localhost:6379
export REDIS_PASSWORD=your-password
export REDIS_DB=0
export DEBUG_PORT=3000
export DEBUG_HOST=0.0.0.0
export DEBUG_READ_ONLY=true
export DEBUG_AUTH_TOKEN=your-secret-token

rustic-debug start

Connecting to Redis

Redis Connection Strings

Different Redis configurations:

# Standard connection
redis://localhost:6379

# With password
redis://:password@localhost:6379

# With username and password
redis://username:password@localhost:6379

# With database selection
redis://localhost:6379/2

# Redis Cluster
redis://node1:6379,node2:6379,node3:6379

# Redis Sentinel
redis+sentinel://localhost:26379/mymaster

# TLS/SSL connection
rediss://localhost:6380

Testing Redis Connection

Before starting Rustic Debug, verify your Redis connection:

# Test connection
rustic-debug test-connection --redis-url redis://localhost:6379

# Output:
# ✅ Successfully connected to Redis at localhost:6379
# ✅ Redis version: 7.0.5
# ✅ Found 3 guilds with 142 messages

Platform-Specific Instructions

macOS

# Install Redis (if needed)
brew install redis
brew services start redis

# Install Rustic Debug
npm install -g @rustic-ai/rustic-debug

# Start
rustic-debug start

Ubuntu/Debian

# Install Redis (if needed)
sudo apt update
sudo apt install redis-server
sudo systemctl start redis

# Install Node.js (if needed)
curl -fsSL https://deb.nodesource.com/setup_18.x | sudo -E bash -
sudo apt install nodejs

# Install Rustic Debug
sudo npm install -g @rustic-ai/rustic-debug

# Start
rustic-debug start

Windows

# Install Redis (using WSL2 or Docker)
# WSL2 approach:
wsl --install
wsl sudo apt install redis-server
wsl sudo service redis-server start

# Install Rustic Debug
npm install -g @rustic-ai/rustic-debug

# Start
rustic-debug start

Verifying Installation

After installation, verify everything is working:

Check Service Status:
```
rustic-debug status
```
Open the Web UI:
```
open http://localhost:3000
```

Run Health Check:

curl http://localhost:3000/health

# Expected response:
{
  "status": "healthy",
  "redis": "connected",
  "version": "1.0.0",
  "uptime": 120
}

Setting Up as a Service

systemd (Linux)

Create /etc/systemd/system/rustic-debug.service:

[Unit]
Description=Rustic Debug Service
After=network.target redis.service

[Service]
Type=simple
User=rustic
WorkingDirectory=/opt/rustic-debug
ExecStart=/usr/bin/rustic-debug start --config /etc/rustic-debug/config.json
Restart=on-failure
RestartSec=10

[Install]
WantedBy=multi-user.target

Enable and start:

sudo systemctl enable rustic-debug
sudo systemctl start rustic-debug

PM2 (Node.js Process Manager)

# Install PM2
npm install -g pm2

# Start with PM2
pm2 start rustic-debug --name rustic-debug -- start

# Save configuration
pm2 save
pm2 startup

Troubleshooting Installation

Common Issues

Issue: Cannot connect to Redis

# Check Redis is running
redis-cli ping
# Should return: PONG

# Check Redis connection
rustic-debug test-connection --redis-url redis://localhost:6379

Issue: Port already in use

# Find what's using port 3000
lsof -i :3000

# Use a different port
rustic-debug start --port 3001

Issue: Permission denied

# Fix npm permissions (macOS/Linux)
sudo npm install -g @rustic-ai/rustic-debug

# Or change npm prefix
npm config set prefix ~/.npm-global
export PATH=~/.npm-global/bin:$PATH

Issue: Node version too old

# Check Node version
node --version

# Update Node.js using nvm
nvm install 18
nvm use 18

Uninstalling

NPM

npm uninstall -g @rustic-ai/rustic-debug

Docker

docker stop rustic-debug
docker rm rustic-debug
docker rmi rusticai/rustic-debug

From Source

# Remove the cloned directory
rm -rf /path/to/rustic-debug

Next Steps

Now that Rustic Debug is installed: