Installation Guide

Get WaddlePerf up and running in minutes with multiple installation options

Quick Navigation

Prerequisites Docker Install Binary Install Build from Source Configuration Verification Troubleshooting Next Steps

Prerequisites

System Requirements

Component	Requirements
Operating System	Linux (Ubuntu 20.04+, Debian 11+, RHEL 8+), Windows 10/11, macOS 10.15+
Memory	Minimum 512MB RAM (1GB+ recommended)
Disk Space	100MB for client, 500MB for server
Network	Outbound connectivity to target servers
Software	Python 3.9+ or Go 1.21+ (for building from source)

Network Ports

Important: Ensure the following ports are accessible:

HTTP: 80
HTTPS: 443
Web UI: 8080
iperf3: 5201
UDP Ping: 2000/udp

Docker Installation (Recommended)

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

Full Stack with Docker Compose

Terminal

# 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

Terminal

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

Deploy Server Container

Terminal

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

Pro Tip: Docker installation handles all dependencies automatically and provides consistent environments across platforms.

Binary Installation

Download pre-built binaries for your platform from GitHub Releases

Linux Installation

AMD64 Architecture

Terminal

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

Terminal

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)

Terminal

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)

Terminal

# 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

Terminal

# 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

Terminal

# 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

Terminal

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

Windows (PowerShell as Administrator)

PowerShell

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

Terminal

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

Server Configuration

Terminal

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)

~/.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)

/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

Terminal

# 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

Permission Denied Errors

Terminal

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

Port Already in Use

Terminal

# 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 ...

System Tray Not Working (Linux)

Terminal

# 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

Python Module Errors

Terminal

# Create virtual environment
python3 -m venv venv
source venv/bin/activate
# Install requirements
pip install -r requirements.txt

Next Steps

Usage Guide

Learn how to use WaddlePerf for network testing

AutoPerf Mode

Set up continuous monitoring with alerts

Architecture

Understand WaddlePerf's system design

GitHub Repository

View source code and contribute

← Back to Documentation Next: Usage Guide →