Installation Guide

Prerequisites

System Requirements

Network Ports

Docker Installation (Recommended)

The fastest way to get started with WaddlePerf is using Docker containers.

Full Stack with Docker Compose

# Clone the repository
git clone https://github.com/penguintechinc/WaddlePerf.git
cd WaddlePerf

# Start all services
docker-compose up -d

# Check status
docker-compose ps

# View logs
docker-compose logs -f

Individual Container Deployment

Deploy Client Container

docker run -d \
  --name waddleperf-client \
  -p 8080:8080 \
  -e TARGET_SERVER=your-server-address \
  ghcr.io/penguincloud/waddleperf-client:latest

Deploy Server Container

docker run -d \
  --name waddleperf-server \
  -p 80:80 -p 443:443 -p 5201:5201 -p 2000:2000/udp \
  ghcr.io/penguincloud/waddleperf-server:latest

Binary Installation

Download pre-built binaries for your platform from GitHub Releases.

Linux Installation

AMD64 Architecture

wget https://github.com/penguintechinc/WaddlePerf/releases/latest/download/waddleperf-linux-amd64.tar.gz
tar xzf waddleperf-linux-amd64.tar.gz
sudo mv waddleperf /usr/local/bin/
sudo chmod +x /usr/local/bin/waddleperf

ARM64 Architecture

wget https://github.com/penguintechinc/WaddlePerf/releases/latest/download/waddleperf-linux-arm64.tar.gz
tar xzf waddleperf-linux-arm64.tar.gz
sudo mv waddleperf /usr/local/bin/
sudo chmod +x /usr/local/bin/waddleperf

macOS Installation (Universal Binary)

wget https://github.com/penguintechinc/WaddlePerf/releases/latest/download/waddleperf-macos-universal.tar.gz
tar xzf waddleperf-macos-universal.tar.gz
sudo mv waddleperf /usr/local/bin/
sudo chmod +x /usr/local/bin/waddleperf

Windows Installation

Download and extract the appropriate ZIP file:

• waddleperf-windows-amd64.zip for 64-bit systems
• waddleperf-windows-arm64.zip for ARM systems

Add the extracted directory to your PATH environment variable.

Building from Source

Build WaddlePerf from source for custom configurations or development.

Prerequisites for Building

Linux (Ubuntu/Debian)

# Install build dependencies
sudo apt-get update
sudo apt-get install -y build-essential git golang-go

# For system tray support
sudo apt-get install -y libayatana-appindicator3-dev libgtk-3-dev

macOS

# Install Xcode Command Line Tools
xcode-select --install

# Install Homebrew if not present
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

# Install Go
brew install go

Build Process

# Clone repository
git clone https://github.com/penguintechinc/WaddlePerf.git
cd WaddlePerf/go-client

# Install dependencies
go mod download

# Build with system tray support
go build -o waddleperf ./cmd/waddleperf

# Build without system tray (no GTK dependencies)
go build -tags nosystray -o waddleperf ./cmd/waddleperf

# Install to system
sudo mv waddleperf /usr/local/bin/

Thin Client Installation

Quick installation scripts for minimal setup.

Linux/macOS

curl -sSL https://raw.githubusercontent.com/penguintechinc/WaddlePerf/main/client/thin-installers/debian-thininstall.sh | bash

Windows (PowerShell as Administrator)

Invoke-WebRequest -Uri https://raw.githubusercontent.com/penguintechinc/WaddlePerf/main/client/thin-installers/windows-thininstall.ps -OutFile install.ps1
./install.ps1

Configuration

Environment Variables

Client Configuration

export WADDLEPERF_SERVER=server.example.com:8080
export WADDLEPERF_LOG_LEVEL=info
export WADDLEPERF_INTERVAL=3600
export WADDLEPERF_AUTOSTART=true

Server Configuration

export LISTEN_PORT=80
export SSL_PORT=443
export IPERF_PORT=5201
export UDP_PORT=2000
export ENABLE_GEOIP=true

Configuration Files

Go Client Configuration (~/.waddleperf.yaml)

server: server.example.com:8080
interval: 3600
autostart: true
log-file: /var/log/waddleperf.log
verbose: false

Docker Configuration (/client/vars/base.yml)

TARGET_SERVER: server.example.com
TEST_INTERVAL: 3600
S3_BUCKET: waddleperf-results
S3_ENDPOINT: s3.amazonaws.com

Verification

Verify your installation is working correctly.

Test Commands

# Go Client
waddleperf info
waddleperf run -s server.example.com

# Docker
docker exec waddleperf-client python3 /app/bins/getSysInfo.py

# Check logs
docker logs waddleperf-client
docker logs waddleperf-server

Health Checks

• Client Web UI: http://localhost:8080
• Server Status: http://server-ip/health
• iperf3 Test: iperf3 -c server-ip -p 5201

Troubleshooting

Common Issues

# Fix permissions
sudo chown -R $(whoami):$(whoami) /opt/waddleperf
chmod +x /usr/local/bin/waddleperf

# Check what's using the port
sudo lsof -i :8080
sudo netstat -tulpn | grep 8080

# Kill the process or change port
docker run -p 8081:8080 ...

# Install required libraries
sudo apt-get install libayatana-appindicator3-dev libgtk-3-dev

# Or build without system tray
go build -tags nosystray -o waddleperf ./cmd/waddleperf

# Create virtual environment
python3 -m venv venv
source venv/bin/activate

# Install requirements
pip install -r requirements.txt

Next Steps