Skip to content

🚀 Tobogganing Quick Start Guide

Get up and running with Tobogganing in under 10 minutes!

📋 Prerequisites

  • Docker & Docker Compose (Latest version)
  • Go 1.23+ (for building from source)
  • Python 3.12+ (for Manager development)
  • Node.js 18+ (for website development)

🐳 Quick Start with Docker Compose

1. Clone the Repository

git clone https://github.com/yourusername/Tobogganing.git
cd Tobogganing

2. Configure Environment

Copy the example environment file and adjust settings:

cp deploy/docker-compose/.env.example deploy/docker-compose/.env
# Edit .env with your database passwords and secrets

Key Environment Variables: 

# Database Configuration
DB_TYPE=mysql
DB_ROOT_PASSWORD=secure_root_password
DB_PASSWORD=secure_app_password

# JWT & Security
JWT_SECRET=your-super-secret-jwt-key
METRICS_TOKEN=prometheus-scraping-token

# Headend Configuration
HEADEND_AUTH_TYPE=jwt
TRAFFIC_MIRROR_ENABLED=true
HEADEND_SYSLOG_ENABLED=true

3. Start the Complete Stack

cd deploy/docker-compose

# Start all services (includes Suricata IDS, FRR, Redis)
docker-compose -f docker-compose.yml up -d

# Check status
docker-compose ps

# View logs
docker-compose logs -f manager headend

4. Access Services

🎛️ Manager Web Portal

  • URL: http://localhost:8000
  • Features:
  • User management with role-based access
  • Real-time analytics dashboard
  • Firewall rule configuration
  • VRF and OSPF management
  • Port configuration interface

Default Admin Account: 

Username: admin
Password: (check container logs for generated password)

📊 Monitoring Stack

🔍 Security Monitoring

  • Suricata IDS Logs: Available in container logs
  • Syslog Server: UDP port 514 (configurable)

5. Initial Configuration

Create Your First User

  1. Access the Manager Portal at http://localhost:8000
  2. Log in with admin credentials
  3. Navigate to "Users" → "Create User"
  4. Assign appropriate role (Admin/Reporter)

Configure Firewall Rules

  1. Go to "Firewall" section
  2. Create domain rules: *.yourcompany.com
  3. Add protocol rules for specific services
  4. Test access with the built-in testing tool

Set Up VRF Network Segmentation

  1. Navigate to "Network" → "VRF Management"
  2. Create VRF: customer-a with RD 65000:100
  3. Configure OSPF areas and authentication
  4. Monitor OSPF neighbors in real-time

🖥️ Client Installation

🖼️ GUI Client with System Tray

# macOS (Universal - Intel + Apple Silicon)
curl -L https://github.com/penguintechinc/tobogganing/releases/latest/download/tobogganing-client-darwin-universal -o tobogganing-client
chmod +x tobogganing-client

# Linux
curl -L https://github.com/penguintechinc/tobogganing/releases/latest/download/tobogganing-client-linux-amd64 -o tobogganing-client
chmod +x tobogganing-client

# Windows
# Download: tobogganing-client-windows-amd64.exe

# Initialize and start GUI
./tobogganing-client init --manager-url http://localhost:8000 --api-key YOUR_API_KEY
./tobogganing-client gui

GUI Features: - ✅ System tray icon with real-time status - ✅ One-click connect/disconnect - ✅ Connection statistics viewer - ✅ Automatic configuration updates - ✅ Cross-platform native experience

Server Deployments

🖥️ Headless Client for Automation

# Download headless version
curl -L https://github.com/penguintechinc/tobogganing/releases/latest/download/tobogganing-client-linux-amd64-headless -o tobogganing-client
chmod +x tobogganing-client

# Configure and run as daemon
./tobogganing-client init --manager-url http://localhost:8000 --api-key YOUR_API_KEY
./tobogganing-client connect --daemon

🐳 Docker Container

docker run -d \
  --name tobogganing-client \
  --cap-add NET_ADMIN \
  --device /dev/net/tun \
  -e MANAGER_URL=http://localhost:8000 \
  -e API_KEY=YOUR_API_KEY \
  ghcr.io/penguintechinc/tobogganing-client:latest

📖 For detailed installation instructions, see Client Installation Guide

Building from Source

Build All Components

# Quick build all React applications + screenshots
./scripts/build-apps.sh

# Or build everything with make
make build

Build Individual Components

# Manager Service
make build-manager

# Headend Proxy
make build-headend

# Native Client
make build-client

# Website
make build-website

# Mobile app only
./scripts/build-apps.sh --mobile-only

# Website only  
./scripts/build-apps.sh --website-only

# Screenshots only
./scripts/build-apps.sh --screenshots-only

Mobile Development Setup

For Android development and testing:

# Install Android Studio and SDK
./scripts/setup-android-studio.sh

# Build and deploy mobile app
./scripts/deploy-mobile.sh

# Start Android emulator
./scripts/setup-android-studio.sh --start-emulator

# Open Tobogganing project in Android Studio
~/open-tobogganing-mobile.sh

Testing

Run All Tests

make test

Run Specific Tests

# Go tests
make test-go

# Python tests  
make test-python

Deployment

Production with Kubernetes

# Apply Kubernetes manifests
kubectl apply -f deploy/kubernetes/

# Check deployment status
kubectl get pods -n tobogganing

Production with Docker Swarm

# Initialize swarm (if needed)
docker swarm init

# Deploy stack
docker stack deploy -c docker-compose.production.yml tobogganing

# Check services
docker service ls

Client Installation

Docker Client

docker run -d \
  --name tobogganing-client \
  --cap-add NET_ADMIN \
  --device /dev/net/tun \
  -e MANAGER_URL=https://manager.example.com \
  -e API_KEY=your-api-key \
  tobogganing/client:latest

Native Client

Linux/macOS

# Download binary
curl -L https://github.com/yourusername/Tobogganing/releases/latest/download/tobogganing-client-$(uname -s)-$(uname -m) -o tobogganing-client
chmod +x tobogganing-client

# Run with config
./tobogganing-client --config config.yaml

Windows

# Download from releases page
# Run with administrator privileges
tobogganing-client.exe --config config.yaml

Mobile Client (Android)

# Build APK from source
./scripts/deploy-mobile.sh

# Install to connected device
adb install -r clients/mobile/android/app/build/outputs/apk/debug/app-debug.apk

# Or download from releases page
# Install APK on Android device

Configuration

Manager Service

Configuration via environment variables:

# Database
DB_TYPE=mysql                    # mysql, postgresql, sqlite
DB_HOST=localhost
DB_PORT=3306
DB_USER=tobogganing
DB_PASSWORD=secure_password
DB_NAME=tobogganing

# Redis
REDIS_URL=redis://localhost:6379

# Security
JWT_SECRET=your-secret-key
SESSION_TIMEOUT_HOURS=8

Headend Server

# Manager connection
MANAGER_URL=http://manager:8000
HEADEND_AUTH_TOKEN=your-token

# Traffic mirroring
TRAFFIC_MIRROR_ENABLED=true
TRAFFIC_MIRROR_DESTINATIONS=10.0.0.100:4789

# Syslog
HEADEND_SYSLOG_ENABLED=true
HEADEND_SYSLOG_SERVER=syslog.example.com:514

Monitoring

Prometheus Metrics

Available at /metrics endpoints:

Health Checks

Logs

# View all logs
docker-compose -f docker-compose.local.yml logs

# View specific service logs
docker-compose -f docker-compose.local.yml logs manager
docker-compose -f docker-compose.local.yml logs headend-us-east

Troubleshooting

Common Issues

  1. Port conflicts: Check if ports are already in use 

    netstat -tulpn | grep -E '8000|3306|6379'

  2. Database connection issues: Verify database is running 

    docker-compose -f docker-compose.local.yml ps mysql

  3. WireGuard module not loaded: 

    # Linux
sudo modprobe wireguard

# Check if loaded
lsmod | grep wireguard

Debug Mode

Enable debug logging:

# Set in environment
export LOG_LEVEL=DEBUG

# Or in docker-compose
environment:
  LOG_LEVEL: DEBUG

Getting Help

Next Steps