buque/BUILD.md

Building and Installing Buque

This guide explains how to build and install Buque from source.

Prerequisites

1. Install Go

Buque requires Go 1.21 or higher.

Check if Go is installed

go version

If Go is not installed or the version is too old, follow these steps:

Ubuntu/Debian

# Remove old version if exists
sudo apt remove golang-go

# Download Go 1.21 (check for latest version at https://go.dev/dl/)
wget https://go.dev/dl/go1.21.6.linux-amd64.tar.gz

# Extract to /usr/local
sudo rm -rf /usr/local/go
sudo tar -C /usr/local -xzf go1.21.6.linux-amd64.tar.gz

# Add to PATH (add these lines to ~/.bashrc or ~/.profile)
export PATH=$PATH:/usr/local/go/bin
export GOPATH=$HOME/go
export PATH=$PATH:$GOPATH/bin

# Reload shell configuration
source ~/.bashrc

# Verify installation
go version

macOS

# Using Homebrew
brew install go

# Or download from https://go.dev/dl/

Windows

Download and install from https://go.dev/dl/

2. Install Docker

Follow the Docker installation guide at docs/DOCKER_SETUP.md

Building Buque

Method 1: Using the Install Script (Recommended)

cd /home/buque

# Run the installation script
./install.sh

This will:

• Check prerequisites
• Build the binary
• Install to $GOPATH/bin
• Verify the installation

Method 2: Using Make

cd /home/buque

# Download dependencies
make deps

# Build the binary
make build

# The binary will be in ./bin/buque
./bin/buque --version

# Or install to $GOPATH/bin
make install

# Verify installation
buque --version

Method 3: Using Go directly

cd /home/buque

# Download dependencies
go mod download

# Build
go build -o bin/buque ./cmd/buque

# Or install directly
go install ./cmd/buque

# Verify
buque --version

Build Options

Build for production (optimized)

go build -ldflags="-s -w" -o bin/buque ./cmd/buque

Flags:

• -s: Strip symbol table
• -w: Strip DWARF debugging information

Build for specific platform

# Linux AMD64
GOOS=linux GOARCH=amd64 go build -o bin/buque-linux-amd64 ./cmd/buque

# Linux ARM64
GOOS=linux GOARCH=arm64 go build -o bin/buque-linux-arm64 ./cmd/buque

# macOS AMD64 (Intel)
GOOS=darwin GOARCH=amd64 go build -o bin/buque-darwin-amd64 ./cmd/buque

# macOS ARM64 (Apple Silicon)
GOOS=darwin GOARCH=arm64 go build -o bin/buque-darwin-arm64 ./cmd/buque

# Windows AMD64
GOOS=windows GOARCH=amd64 go build -o bin/buque-windows-amd64.exe ./cmd/buque

Build for all platforms

make build-all

This creates binaries for:

• Linux (amd64, arm64)
• macOS (amd64, arm64)
• Windows (amd64)

Installation

System-wide installation

# Build and install
make install

# Or manually copy to system path
sudo cp bin/buque /usr/local/bin/

# Verify
buque --version

User-specific installation

# Install to $GOPATH/bin (usually ~/go/bin)
go install ./cmd/buque

# Make sure $GOPATH/bin is in your PATH
echo 'export PATH=$PATH:$(go env GOPATH)/bin' >> ~/.bashrc
source ~/.bashrc

# Verify
buque --version

Troubleshooting

"go: command not found"

Go is not installed or not in PATH. Install Go following the prerequisites section.

"permission denied" when running buque

# Make the binary executable
chmod +x bin/buque

# Or if installed system-wide
sudo chmod +x /usr/local/bin/buque

"cannot find package" errors

# Download dependencies
go mod download
go mod tidy

# Then rebuild
make build

Build fails with "go.mod" errors

# Clean and rebuild
make clean
make deps
make build

Docker connection errors

Make sure Docker is running:

# Check Docker status
systemctl status docker  # Linux
docker ps  # All platforms

# Start Docker if needed
sudo systemctl start docker  # Linux

Verification

After installation, verify everything works:

# Check version
buque --version

# Check help
buque --help

# Initialize (creates config file)
buque init

# Check Docker connection
docker ps

Running Tests

# Run all tests
make test

# Run with coverage
go test -cover ./...

# Run specific package tests
go test ./internal/docker/...

Development Build

For development with hot reload:

# Install air for hot reload
go install github.com/cosmtrek/air@latest

# Run in development mode
make dev

Uninstallation

# Remove binary from $GOPATH/bin
rm $(go env GOPATH)/bin/buque

# Or from system path
sudo rm /usr/local/bin/buque

# Remove configuration (optional)
rm -rf ~/.buque

Next Steps

After successful installation:

1. Read the Quick Start Guide
2. Run the demo: ./scripts/demo.sh
3. Initialize Buque: buque init
4. Start managing your containers!

Getting Help

If you encounter issues:

1. Check the README.md for documentation
2. Run buque --help for command usage
3. Check Docker is running: docker ps
4. Verify Go version: go version
5. Open an issue on GitHub

Build Information

To see build information:

# Version
buque --version

# Go version used
go version

# Docker version
docker --version
docker compose version