Skip to content

BUILD_GUIDE.md

Latest commit

 

History

History
230 lines (178 loc) · 5.87 KB

BUILD_GUIDE.md

File metadata and controls

230 lines (178 loc) · 5.87 KB

Cross-Platform Build Guide

This document describes how to build static, cross-platform binaries for the FastHTTP Reverse Proxy.

Overview

The project now supports building static binaries for multiple platforms and architectures using Go's cross-compilation capabilities. All binaries are statically linked for maximum portability.

Supported Platforms

Linux

  • AMD64 (x86_64) - Most servers and desktops
  • ARM64 (AArch64) - ARM-based servers, Raspberry Pi 4+, Apple Silicon under Linux
  • ARM (ARMv7) - Raspberry Pi 2/3, older ARM devices
  • 386 (i386) - Legacy 32-bit Intel systems

Windows

  • AMD64 (x86_64) - Modern Windows systems
  • ARM64 (AArch64) - Windows on ARM (Surface Pro X, etc.)
  • 386 (i386) - Legacy 32-bit Windows systems

macOS (Darwin)

  • AMD64 (x86_64) - Intel-based Macs
  • ARM64 (Apple Silicon) - M1/M2/M3 Macs

FreeBSD

  • AMD64 (x86_64) - FreeBSD servers
  • ARM64 (AArch64) - ARM-based FreeBSD systems

Build Commands

Quick Commands

# Build for current platform only
make build-static

# Build for all platforms
make build-all

# Build and create compressed archives
make build-release

# Build specific platforms
make build-linux
make build-windows
make build-darwin
make build-freebsd

Individual Platform Examples

# Linux AMD64 (most common)
CGO_ENABLED=0 GOOS=linux GOARCH=amd64 go build -a -tags netgo -installsuffix netgo -ldflags="-s -w -extldflags '-static'" -o fasthttp-reverse-proxy-linux-amd64 main.go

# Windows AMD64
CGO_ENABLED=0 GOOS=windows GOARCH=amd64 go build -a -tags netgo -installsuffix netgo -ldflags="-s -w -extldflags '-static'" -o fasthttp-reverse-proxy-windows-amd64.exe main.go

# macOS ARM64 (Apple Silicon)
CGO_ENABLED=0 GOOS=darwin GOARCH=arm64 go build -a -tags netgo -installsuffix netgo -ldflags="-s -w -extldflags '-static'" -o fasthttp-reverse-proxy-darwin-arm64 main.go

Build Flags Explained

  • CGO_ENABLED=0: Disables CGO for static linking
  • -a: Forces rebuilding of all packages
  • -tags netgo: Uses pure Go network stack
  • -installsuffix netgo: Separates build cache
  • -ldflags="-s -w -extldflags '-static'":
    • -s: Strip symbol table
    • -w: Strip debug info
    • -extldflags '-static': Static linking

Binary Sizes

Typical binary sizes after optimization:

  • Linux/FreeBSD: ~6MB
  • Windows: ~6MB
  • macOS: ~6MB
  • ARM variants: ~5.7-5.9MB (slightly smaller)

Compressed Archive Sizes

After compression:

  • tar.gz (Unix systems): ~2.4-2.7MB (60% compression)
  • zip (Windows): ~2.5-2.7MB (57-59% compression)

Distribution

Archive Formats

  • Unix/Linux/macOS/FreeBSD: .tar.gz archives
  • Windows: .zip archives

File Naming Convention

fasthttp-reverse-proxy-{os}-{arch}[.exe]
fasthttp-reverse-proxy-{os}-{arch}[.tar.gz|.zip]

Examples:

  • fasthttp-reverse-proxy-linux-amd64
  • fasthttp-reverse-proxy-windows-amd64.exe
  • fasthttp-reverse-proxy-darwin-arm64.tar.gz
  • fasthttp-reverse-proxy-windows-amd64.zip

Usage Examples

Linux/Unix

# Extract and run
tar -xzf fasthttp-reverse-proxy-linux-amd64.tar.gz
chmod +x fasthttp-reverse-proxy-linux-amd64
./fasthttp-reverse-proxy-linux-amd64 -config config.yml -routes routes.yml

Windows

# Extract and run
unzip fasthttp-reverse-proxy-windows-amd64.zip
fasthttp-reverse-proxy-windows-amd64.exe -config config.yml -routes routes.yml

macOS

# Extract and run
tar -xzf fasthttp-reverse-proxy-darwin-arm64.tar.gz
chmod +x fasthttp-reverse-proxy-darwin-arm64
./fasthttp-reverse-proxy-darwin-arm64 -config config.yml -routes routes.yml

Deployment Scenarios

Docker Alternative

These static binaries can run without Docker:

# Download binary for your platform
wget https://releases.example.com/fasthttp-reverse-proxy-linux-amd64.tar.gz
tar -xzf fasthttp-reverse-proxy-linux-amd64.tar.gz

# Create systemd service
sudo cp fasthttp-reverse-proxy-linux-amd64 /usr/local/bin/fasthttp-reverse-proxy
sudo systemctl enable fasthttp-reverse-proxy
sudo systemctl start fasthttp-reverse-proxy

Embedded Systems

For ARM devices like Raspberry Pi:

# Raspberry Pi 4+ (ARM64)
wget fasthttp-reverse-proxy-linux-arm64.tar.gz

# Raspberry Pi 2/3 (ARMv7)
wget fasthttp-reverse-proxy-linux-arm.tar.gz

CI/CD Integration

# GitHub Actions example
- name: Download Release Binary
  run: |
    wget https://releases.example.com/fasthttp-reverse-proxy-linux-amd64.tar.gz
    tar -xzf fasthttp-reverse-proxy-linux-amd64.tar.gz
    chmod +x fasthttp-reverse-proxy-linux-amd64
    ./fasthttp-reverse-proxy-linux-amd64 &

Verification

Check Binary Info

# File type and architecture
file fasthttp-reverse-proxy-linux-amd64

# Dependencies (should show statically linked)
ldd fasthttp-reverse-proxy-linux-amd64

# Size
ls -lh fasthttp-reverse-proxy-*

Test Binary

# Quick test
./fasthttp-reverse-proxy-linux-amd64 -config config.yml -routes routes.yml &
curl http://localhost:8080/health

Troubleshooting

Common Issues

  1. Permission Denied

    chmod +x fasthttp-reverse-proxy-*

  2. Architecture Mismatch

    # Check your system
uname -m
# x86_64 = amd64
# aarch64 = arm64  
# armv7l = arm

  3. Static Linking Verification

    ldd binary-name
# Should show "statically linked" or "not a dynamic executable"

Performance Notes

  • Static binaries have no external dependencies
  • Slightly larger file size vs dynamic linking
  • No performance impact at runtime
  • Better portability and deployment simplicity
  • Compatible with minimal container images (scratch, distroless)

Automation

The build process can be automated using the provided Makefile targets:

# Full release pipeline
make clean
make build-release
./build-info.sh

This creates all binaries and compressed archives ready for distribution.
⚡