Installation Guide

This guide provides comprehensive installation instructions for KafkaGuard on all supported platforms and deployment scenarios.

Prerequisites
Binary Installation
Docker Installation
Build from Source
Air-Gapped Installation
Installation Verification
Platform-Specific Requirements
Troubleshooting Installation

Prerequisites

Before installing KafkaGuard, ensure you have:

For Binary Installation (Recommended)

Operating System: Linux (Ubuntu 20.04+, RHEL 7+, Debian 10+) or macOS 12+
Architecture: x86_64 (amd64) or ARM64 (arm64)
Network Access: Ability to download from GitHub Releases (for binary installation)
Disk Space: ~100MB for binary and temporary reports

For Docker Installation

Docker: Version 20.10+ with multi-architecture support
Network Access: Ability to pull from Docker Hub (docker.io)
Disk Space: ~60MB for Docker image

For Building from Source

Go: Version 1.22.0 or higher
Git: For cloning the repository
Make: GNU Make (optional, but recommended)
Network Access: For downloading Go dependencies
Disk Space: ~500MB for source code and build artifacts

For Running Scans

Kafka Access: Network connectivity to Kafka brokers (default port 9092)
Credentials: SASL/SSL credentials if your cluster requires authentication
Permissions: Read-only access to Kafka cluster metadata (no write permissions needed)

Binary Installation

Binary installation is the fastest and easiest method. Pre-built binaries are available for Linux and macOS on both x86_64 and ARM64 architectures.

Linux (Ubuntu/Debian)

Method 1: Download and Install to /usr/local/bin (Recommended)

# Download latest release (amd64)
curl -LO https://github.com/aiopsone/kafkaguard-releases/releases/latest/download/kafkaguard_Linux_x86_64.tar.gz && tar -xzf kafkaguard_Linux_x86_64.tar.gz

# Or for ARM64
# curl -LO https://github.com/aiopsone/kafkaguard-releases/releases/latest/download/kafkaguard_Linux_arm64.tar.gz && tar -xzf kafkaguard_Linux_arm64.tar.gz

# Make executable
chmod +x kafkaguard

# Move to system path
sudo mv kafkaguard /usr/local/bin/kafkaguard

# Verify installation
kafkaguard version

Method 2: Download to Local Directory

# Create local bin directory (if it doesn't exist)
mkdir -p ~/bin

# Download latest release
curl -LO https://github.com/aiopsone/kafkaguard-releases/releases/latest/download/kafkaguard_Linux_x86_64.tar.gz && tar -xzf kafkaguard_Linux_x86_64.tar.gz

# Make executable
chmod +x kafkaguard

# Move to local bin
mv kafkaguard ~/bin/kafkaguard

# Add to PATH (add this to ~/.bashrc or ~/.zshrc)
export PATH="$HOME/bin:$PATH"

# Reload shell configuration
source ~/.bashrc  # or source ~/.zshrc

# Verify installation
kafkaguard version

Method 3: Checksum Verification (Recommended for Production)

# Download binary and checksum file
curl -LO https://github.com/aiopsone/kafkaguard-releases/releases/latest/download/kafkaguard_Linux_x86_64.tar.gz && tar -xzf kafkaguard_Linux_x86_64.tar.gz
curl -LO https://github.com/aiopsone/kafkaguard-releases/releases/latest/download/kafkaguard_Linux_x86_64.tar.gz && tar -xzf kafkaguard_Linux_x86_64.tar.gz.sha256

# Verify checksum
sha256sum -c kafkaguard.sha256

# Expected output: "kafkaguard: OK"

# Make executable and install
chmod +x kafkaguard
sudo mv kafkaguard /usr/local/bin/kafkaguard

# Verify installation
kafkaguard version

Linux (RHEL/CentOS)

Method 1: Download and Install to /usr/local/bin

# Download latest release (amd64)
curl -LO https://github.com/aiopsone/kafkaguard-releases/releases/latest/download/kafkaguard_Linux_x86_64.tar.gz && tar -xzf kafkaguard_Linux_x86_64.tar.gz

# Or for ARM64
# curl -LO https://github.com/aiopsone/kafkaguard-releases/releases/latest/download/kafkaguard_Linux_arm64.tar.gz && tar -xzf kafkaguard_Linux_arm64.tar.gz

# Make executable
chmod +x kafkaguard

# Move to system path
sudo mv kafkaguard /usr/local/bin/kafkaguard

# Verify installation
kafkaguard version

Method 2: Create RPM Package (Advanced)

# Download binary
curl -LO https://github.com/aiopsone/kafkaguard-releases/releases/latest/download/kafkaguard_Linux_x86_64.tar.gz && tar -xzf kafkaguard_Linux_x86_64.tar.gz

# Create RPM build directory
mkdir -p ~/rpmbuild/{BUILD,RPMS,SOURCES,SPECS,SRPMS}

# Create RPM spec file (example)
cat > ~/rpmbuild/SPECS/kafkaguard.spec <<EOF
Name:           kafkaguard
Version:        1.0.0
Release:        1%{?dist}
Summary:        Kafka Compliance Scanner
License:        Proprietary
URL:            https://github.com/aiopsone/kafkaguard
BuildArch:      x86_64

%description
KafkaGuard is a Kafka compliance scanner for security and operational auditing.

%install
mkdir -p %{buildroot}/usr/local/bin
install -m 755 kafkaguard %{buildroot}/usr/local/bin/kafkaguard

%files
/usr/local/bin/kafkaguard

%changelog
* $(date +'%a %b %d %Y') System Administrator
- Initial RPM build
EOF

# Build RPM
rpmbuild -bb ~/rpmbuild/SPECS/kafkaguard.spec

# Install RPM
sudo rpm -ivh ~/rpmbuild/RPMS/x86_64/kafkaguard-1.0.0-1.*.rpm

# Verify installation
kafkaguard version

macOS (Intel)

Method 1: Download and Install to /usr/local/bin

# Download latest release (Intel x86_64)
curl -LO https://github.com/aiopsone/kafkaguard-releases/releases/latest/download/kafkaguard_Darwin_x86_64.tar.gz && tar -xzf kafkaguard_Darwin_x86_64.tar.gz

# Make executable
chmod +x kafkaguard

# Move to system path
sudo mv kafkaguard /usr/local/bin/kafkaguard

# On first run, you may need to allow the binary in System Preferences → Security & Privacy
# Or remove the quarantine attribute:
xattr -d com.apple.quarantine /usr/local/bin/kafkaguard

# Verify installation
kafkaguard version

Method 2: Install to User bin Directory

# Create local bin directory
mkdir -p ~/bin

# Download latest release
curl -LO https://github.com/aiopsone/kafkaguard-releases/releases/latest/download/kafkaguard_Darwin_x86_64.tar.gz && tar -xzf kafkaguard_Darwin_x86_64.tar.gz

# Make executable
chmod +x kafkaguard

# Move to local bin
mv kafkaguard ~/bin/kafkaguard

# Remove quarantine attribute
xattr -d com.apple.quarantine ~/bin/kafkaguard 2>/dev/null || true

# Add to PATH (add this to ~/.zshrc)
export PATH="$HOME/bin:$PATH"

# Reload shell configuration
source ~/.zshrc

# Verify installation
kafkaguard version

macOS (Apple Silicon)

Method 1: Download and Install to /usr/local/bin

# Download latest release (ARM64)
curl -LO https://github.com/aiopsone/kafkaguard-releases/releases/latest/download/kafkaguard_Darwin_arm64.tar.gz && tar -xzf kafkaguard_Darwin_arm64.tar.gz

# Make executable
chmod +x kafkaguard

# Move to system path
sudo mv kafkaguard /usr/local/bin/kafkaguard

# Remove quarantine attribute (prevents "unidentified developer" warning)
xattr -d com.apple.quarantine /usr/local/bin/kafkaguard

# Verify installation
kafkaguard version

Note for macOS Users:

On first run, macOS may display a security warning about an "unidentified developer." You can:

Remove the quarantine attribute (recommended):

xattr -d com.apple.quarantine /usr/local/bin/kafkaguard

Or manually allow in System Preferences:
- Go to System Preferences → Security & Privacy → General
- Click "Open Anyway" after the first blocked attempt

Docker Installation

Docker provides the easiest cross-platform installation with no dependencies.

Pull from Docker Hub

# Pull latest image (multi-architecture)
docker pull aiopsone/kafkaguard:latest

# Verify installation
docker run --rm aiopsone/kafkaguard:latest version

Expected Output:

KafkaGuard v1.0.0
Commit: a1b2c3d
Built: 2025-11-15T12:00:00Z
Go: go1.22.0 linux/amd64

Run Basic Scan

# Create directories for policies and reports
mkdir -p policies reports

# Copy policy files to policies directory
cp /path/to/policies/*.yaml policies/

# Run scan against Kafka cluster
docker run --rm \
  -v $(pwd)/policies:/policies:ro \
  -v $(pwd)/reports:/reports \
  aiopsone/kafkaguard:latest scan \
    --bootstrap kafka.example.com:9092 \
    --policy /policies/baseline-dev.yaml \
    --format html,json \
    --out /reports

Docker Compose Example

Create docker-compose.yml:

version: '3.8'

services:
  kafkaguard:
    image: aiopsone/kafkaguard:latest
    volumes:
      - ./policies:/policies:ro
      - ./reports:/reports
      - ./certs:/certs:ro
    environment:
      KAFKAGUARD_SASL_USERNAME: ${KAFKA_USERNAME}
      KAFKAGUARD_SASL_PASSWORD: ${KAFKA_PASSWORD}
    command: >
      scan
      --bootstrap ${KAFKA_BROKER}
      --security-protocol SASL_SSL
      --sasl-mechanism SCRAM-SHA-512
      --tls-ca-cert /certs/ca-cert.pem
      --policy /policies/enterprise-default.yaml
      --format json,html,pdf
      --out /reports

Run with Docker Compose:

# Set environment variables
export KAFKA_BROKER="kafka.prod.example.com:9095"
export KAFKA_USERNAME="admin"
export KAFKA_PASSWORD="secret"

# Run scan
docker-compose run --rm kafkaguard

# View reports
ls -lh reports/

For more Docker usage examples, see Docker Usage Guide.

Build from Source

Building from source gives you the latest features and allows for customization.

Prerequisites

Go 1.22.0+ - Install Go
Git - For cloning the repository
Make - For using Makefile targets (optional)

Build Steps

# 1. Clone the repository
git clone https://github.com/aiopsone/kafkaguard.git
cd kafkaguard

# 2. Download dependencies
go mod download

# 3. Build the binary
make build

# Or build without Make:
go build -o kafkaguard \
  -ldflags="-s -w -X main.version=dev -X main.commit=$(git rev-parse HEAD) -X main.date=$(date -u +%Y-%m-%dT%H:%M:%SZ)" \
  .

# 4. Verify build
./kafkaguard version

# 5. (Optional) Install to system path
sudo mv kafkaguard /usr/local/bin/

# Or install to user bin
mv kafkaguard ~/bin/

Build for Multiple Platforms

# Build for all target platforms
make build-all

# This creates binaries in dist/:
# - kafkaguard
# - kafkaguard-linux-arm64
# - kafkaguard
# - kafkaguard

Run Tests

# Run all tests
make test

# Run tests with coverage
make test-coverage

# Run linters
make lint

For detailed development instructions, see Development Guide.

Air-Gapped Installation

Air-gapped environments (no internet access) require bundling KafkaGuard and dependencies before transfer.

Step 1: Create Air-Gapped Bundle (Internet-Connected System)

# Create bundle directory
mkdir -p kafkaguard-bundle
cd kafkaguard-bundle

# Download KafkaGuard binary (choose your platform)
curl -LO https://github.com/aiopsone/kafkaguard-releases/releases/latest/download/kafkaguard_Linux_x86_64.tar.gz && tar -xzf kafkaguard_Linux_x86_64.tar.gz

# Or build from source
git clone https://github.com/aiopsone/kafkaguard.git
cd kafkaguard
make build
cp kafkaguard ../kafkaguard-bundle/

# Download policies
mkdir -p policies
cp -r kafkaguard/policies/*.yaml policies/

# Download documentation (optional)
mkdir -p docs
cp -r kafkaguard/docs/user-guide docs/

# Create bundle README
cat > README.txt <<EOF
KafkaGuard Air-Gapped Bundle
============================

Version: 1.0.0
Created: $(date)
Platform: linux-amd64

Installation:
1. Extract bundle: tar -xzf kafkaguard-bundle.tar.gz
2. Install binary: sudo mv kafkaguard /usr/local/bin/
3. Verify: kafkaguard version
4. Run scan: kafkaguard scan --bootstrap <kafka-broker> --policy policies/baseline-dev.yaml

EOF

# Create tarball
cd ..
tar -czf kafkaguard-bundle.tar.gz kafkaguard-bundle/

# Verify bundle
tar -tzf kafkaguard-bundle.tar.gz
ls -lh kafkaguard-bundle.tar.gz

Step 2: Transfer to Air-Gapped Environment

Transfer the kafkaguard-bundle.tar.gz file using:

USB drive (most common)
Secure file transfer (if available)
Physical media (CD/DVD for highly restricted environments)

Step 3: Install on Air-Gapped System

# Extract bundle
tar -xzf kafkaguard-bundle.tar.gz
cd kafkaguard-bundle

# Make binary executable
chmod +x kafkaguard

# Install to system path
sudo mv kafkaguard /usr/local/bin/

# Verify installation
kafkaguard version

# Create directories for policies and reports
sudo mkdir -p /opt/kafkaguard/policies
sudo mkdir -p /var/reports/kafkaguard

# Copy policies
sudo cp policies/*.yaml /opt/kafkaguard/policies/

# Test scan
kafkaguard scan \
  --bootstrap kafka-internal:9092 \
  --policy /opt/kafkaguard/policies/baseline-dev.yaml \
  --format json,html \
  --out /var/reports/kafkaguard

Docker Air-Gapped Installation

# On internet-connected system: Save Docker image
docker pull aiopsone/kafkaguard:1.0.0
docker save aiopsone/kafkaguard:1.0.0 | gzip > kafkaguard-docker-1.0.0.tar.gz

# Transfer to air-gapped environment

# On air-gapped system: Load Docker image
docker load < kafkaguard-docker-1.0.0.tar.gz

# Verify
docker images | grep kafkaguard

# Run scan
docker run --rm \
  -v /opt/policies:/policies:ro \
  -v /var/reports:/reports \
  aiopsone/kafkaguard:1.0.0 scan \
    --bootstrap kafka-internal:9092 \
    --policy /policies/baseline-dev.yaml \
    --out /reports

Installation Verification

After installing KafkaGuard, verify the installation is working correctly.

Basic Verification

# 1. Check version
kafkaguard version

# Expected output:
# KafkaGuard v1.0.0
# Commit: a1b2c3d
# Built: 2025-11-15T12:00:00Z
# Go: go1.22.0 linux/amd64

# 2. Check help
kafkaguard --help

# Expected output: List of available commands

# 3. List available controls
kafkaguard list-controls --policy policies/baseline-dev.yaml

# Expected output: List of 20 controls from baseline-dev policy

# 4. Validate a policy file
kafkaguard validate-policy --policy policies/baseline-dev.yaml

# Expected output: "✅ Policy validation successful"

Full Verification (Requires Kafka Access)

# Run a scan against your Kafka cluster
kafkaguard scan \
  --bootstrap YOUR_KAFKA_BROKER:9092 \
  --policy policies/baseline-dev.yaml \
  --format json \
  --out ./reports

# Expected results:
# - Scan completes without errors
# - Report generated in ./reports/
# - Exit code 0 or 1 (0=no findings, 1=findings detected, 2=error)

# Check exit code
echo $?

# View generated report
ls -lh reports/scan-*.json
cat reports/scan-*.json | jq '.summary'

Verification Checklist

kafkaguard version displays version information
kafkaguard --help shows command list
kafkaguard list-controls displays controls (requires policy file)
kafkaguard validate-policy validates policy files
kafkaguard scan runs successfully against test cluster
Reports are generated in specified output directory
Binary is in PATH and accessible from any directory

Platform-Specific Requirements

Linux Requirements

Operating Systems:

Ubuntu 20.04+ (LTS)
Debian 10+ (Buster)
RHEL 7+ / CentOS 7+
Amazon Linux 2
Other modern Linux distributions with glibc 2.28+

Architecture:

x86_64 (amd64) - Intel/AMD 64-bit
ARM64 (aarch64) - ARM 64-bit (AWS Graviton, Raspberry Pi 4)

Disk Space:

Binary: ~40MB
Reports: ~1MB per scan (varies by cluster size and report formats)
Recommended: 100MB free space

Network:

Kafka broker connectivity (port 9092-9095 typically)
DNS resolution for broker hostnames

macOS Requirements

Operating Systems:

macOS 12 (Monterey) or higher
macOS 13 (Ventura) - Recommended
macOS 14 (Sonoma) - Supported

Architecture:

Intel (x86_64) - Intel Macs
Apple Silicon (ARM64) - M1, M2, M3 Macs

Disk Space:

Binary: ~40MB
Reports: ~1MB per scan
Recommended: 100MB free space

Security:

Gatekeeper may block unsigned binaries (use xattr -d to remove quarantine)
No additional permissions required (runs as user)

Docker Requirements

Docker Version:

Docker 20.10+ (with multi-architecture support)
Docker Compose 1.29+ (optional, for compose workflows)

Supported Platforms:

Linux: x86_64, ARM64
macOS: Intel, Apple Silicon
Windows: WSL2 with Docker Desktop

Disk Space:

Docker image: ~60MB
Container runtime: ~50MB memory

Network:

Docker Hub access for pulling images (or air-gapped Docker image load)
Kafka broker connectivity from container network

Troubleshooting Installation

Binary Not Found After Installation

Problem: bash: kafkaguard: command not found

Cause: Binary not in PATH.

Fix:

# Check if binary exists
ls -l /usr/local/bin/kafkaguard

# If not in /usr/local/bin, add to PATH
export PATH="$HOME/bin:$PATH"

# Add to shell profile for persistence
echo 'export PATH="$HOME/bin:$PATH"' >> ~/.bashrc  # or ~/.zshrc
source ~/.bashrc

Permission Denied

Problem: bash: ./kafkaguard: Permission denied

Cause: Binary not executable.

Fix:

# Make binary executable
chmod +x kafkaguard

# Or if installed to /usr/local/bin
sudo chmod +x /usr/local/bin/kafkaguard

macOS Security Warning

Problem: "kafkaguard" cannot be opened because the developer cannot be verified.

Cause: macOS Gatekeeper blocks unsigned binaries.

Fix:

# Remove quarantine attribute
xattr -d com.apple.quarantine /usr/local/bin/kafkaguard

# Or manually allow in System Preferences
# System Preferences → Security & Privacy → General → "Open Anyway"

Checksum Verification Failed

Problem: Checksum doesn't match downloaded binary.

Cause: Incomplete download or corrupted file.

Fix:

# Delete and re-download
rm kafkaguard
curl -LO https://github.com/aiopsone/kafkaguard-releases/releases/latest/download/kafkaguard_Linux_x86_64.tar.gz && tar -xzf kafkaguard_Linux_x86_64.tar.gz

# Verify checksum again
sha256sum -c kafkaguard.sha256

Docker Pull Failures

Problem: Error response from daemon: pull access denied

Cause: Network issues or Docker Hub authentication required.

Fix:

# Verify Docker is running
docker ps

# Try pulling again
docker pull aiopsone/kafkaguard:latest

# If authentication required, login to Docker Hub
docker login

# For air-gapped environments, load from tarball
docker load < kafkaguard-docker-1.0.0.tar.gz

Build from Source Fails

Problem: go: cannot find module providing package

Cause: Go modules not downloaded or Go version too old.

Fix:

# Check Go version (must be 1.22.0+)
go version

# Upgrade Go if needed
# Download from: https://golang.org/dl/

# Clear Go module cache
go clean -modcache

# Re-download dependencies
go mod download

# Try build again
make build

Next Steps

After installing KafkaGuard:

Run Your First Scan - Follow the Quick Start Guide
Learn CLI Commands - Review the CLI Reference
Configure Security - Set up Security & Authentication
Explore Workflows - Check out Usage Patterns

Need Help?

Troubleshooting Guide - Resolve common issues
GitHub Issues - Report bugs or request features
GitHub Discussions - Ask questions

Document Information

Last Updated: 2025-11-15
Applies to Version: KafkaGuard 1.0.0+
License: Proprietary
Feedback: Open an issue if you find errors or have suggestions

Installation Guide

Table of Contents

Prerequisites

For Binary Installation (Recommended)

For Docker Installation

For Building from Source

For Running Scans

Binary Installation

Linux (Ubuntu/Debian)

Linux (RHEL/CentOS)

macOS (Intel)

macOS (Apple Silicon)

Docker Installation

Pull from Docker Hub

Run Basic Scan

Docker Compose Example

Build from Source

Prerequisites

Build Steps

Build for Multiple Platforms

Run Tests

Air-Gapped Installation

Step 1: Create Air-Gapped Bundle (Internet-Connected System)

Step 2: Transfer to Air-Gapped Environment

Step 3: Install on Air-Gapped System

Docker Air-Gapped Installation

Installation Verification

Basic Verification

Full Verification (Requires Kafka Access)

Verification Checklist

Platform-Specific Requirements

Linux Requirements

macOS Requirements

Docker Requirements

Troubleshooting Installation

Binary Not Found After Installation

Permission Denied

macOS Security Warning

Checksum Verification Failed

Docker Pull Failures

Build from Source Fails

Next Steps