Codakey
Play
← Back to golang/go

How to Deploy & Use golang/go

Go Programming Language Deployment & Usage Guide

1. Prerequisites

System Requirements

  • Operating System: Linux, macOS, Windows, or FreeBSD
  • Architecture: amd64, arm64, 386, arm, ppc64le, s390x, mips, mipsle, mips64, mips64le, riscv64
  • Disk Space:
    • Binary distribution: ~150MB
    • Source build: ~1GB (including bootstrap toolchain and build artifacts)
  • Memory: Minimum 512MB RAM (2GB+ recommended for building from source)

For Building from Source (Contributors/Developers)

  • Bootstrap Go Toolchain: Go 1.20.6 or later (required to compile Go from source)
  • C Compiler: GCC 4.6+ or Clang (required for cgo support)
  • Git: Version 2.0+
  • Perl: Version 5.8+ (for running tests)

2. Installation

Method A: Binary Distribution (Recommended)

Linux/macOS:

# Download latest stable release (adjust version as needed)
wget https://go.dev/dl/go1.21.5.linux-amd64.tar.gz

# Remove any previous Go installation
sudo rm -rf /usr/local/go

# Extract to /usr/local
sudo tar -C /usr/local -xzf go1.21.5.linux-amd64.tar.gz

# Add to PATH
echo 'export PATH=$PATH:/usr/local/go/bin' >> ~/.profile
source ~/.profile

Windows: Download the MSI installer from https://go.dev/dl/ and run it. The installer will automatically configure the PATH.

Verification:

go version
# Output: go version go1.21.5 linux/amd64

Method B: Install from Source

For contributing to Go or when binary distributions are unavailable for your platform:

# Clone the canonical repository
git clone https://go.googlesource.com/go
cd go

# Checkout the specific release branch (optional)
git checkout go1.21.5

# Build
cd src
./all.bash

The ./all.bash script builds the toolchain and runs tests. For a faster build without tests, use ./make.bash.

Bootstrap Requirements: If building the latest development version, you need a working Go installation (1.20.6+). Set the GOROOT_BOOTSTRAP environment variable if your bootstrap Go is not in /usr/local/go:

export GOROOT_BOOTSTRAP=$HOME/go1.20.6

3. Configuration

Environment Variables

Required:

# Add Go binary to PATH (if not using standard location)
export PATH=$PATH:/usr/local/go/bin:$HOME/go/bin

Optional but Recommended:

# Go module cache location (default: $GOPATH/pkg/mod)
export GOMODCACHE=$HOME/go/pkg/mod

# Module proxy (default: https://proxy.golang.org,direct)
export GOPROXY=https://proxy.golang.org,direct

# Disable CGO if not needed (creates static binaries)
export CGO_ENABLED=0

Legacy (Go 1.10 and earlier):

# Only needed if working with legacy GOPATH mode
export GOPATH=$HOME/go
export PATH=$PATH:$GOPATH/bin

Module Configuration

Initialize a new module:

go mod init example.com/myproject
go mod tidy

IDE Setup

Recommended extensions:

  • VS Code: Go extension by Go Team at Google
  • Vim/Neovim: vim-go or nvim-lspconfig with gopls
  • GoLand: JetBrains IDE (commercial)

4. Build & Run

Developing Go Applications

Run directly:

go run main.go

Build executable:

# Build for current platform
go build -o myapp

# Build with optimizations for production
go build -ldflags="-s -w" -o myapp

Testing:

# Run all tests
go test ./...

# Run with race detector
go test -race ./...

# Generate coverage report
go test -coverprofile=coverage.out ./...
go tool cover -html=coverage.out

Building the Go Toolchain (For Contributors)

cd $GOROOT/src

# Full build and test (takes 10-30 minutes)
./all.bash

# Quick build only (no tests)
./make.bash

# Cross-compile toolchain for all platforms
./make.bash --no-clean

5. Deployment

Cross-Compilation

Go supports cross-compilation out of the box:

# Build for Linux AMD64 from macOS/Windows
GOOS=linux GOARCH=amd64 go build -o myapp-linux

# Build for ARM64 (M1/M2 Macs, AWS Graviton)
GOOS=linux GOARCH=arm64 go build -o myapp-arm64

# Build for Windows
GOOS=windows GOARCH=amd64 go build -o myapp.exe

Docker Deployment

Minimal Dockerfile:

# Build stage
FROM golang:1.21-alpine AS builder
WORKDIR /app
COPY . .
RUN go build -ldflags="-s -w" -o myapp

# Runtime stage
FROM scratch
COPY --from=builder /app/myapp /myapp
COPY --from=builder /etc/ssl/certs/ca-certificates.crt /etc/ssl/certs/
ENTRYPOINT ["/myapp"]

Build and run:

docker build -t myapp:latest .
docker run -p 8080:8080 myapp:latest

Cloud Deployment

Static Binary Deployment:

# Build fully static binary
CGO_ENABLED=0 GOOS=linux go build -a -ldflags '-extldflags "-static"' -o myapp

# Deploy to any Linux server
scp myapp user@server:/usr/local/bin/
ssh user@server "systemctl restart myapp"

Platforms:

  • Google Cloud Run: gcloud run deploy
  • AWS Lambda: Use github.com/aws/aws-lambda-go/lambda with provided.al2 runtime
  • Kubernetes: Use distroless or scratch images for minimal attack surface
  • Fly.io: fly deploy with built-in Go support

Systemd Service (Linux Servers)

Create /etc/systemd/system/myapp.service:

[Unit]
Description=My Go Application
After=network.target

[Service]
Type=simple
User=www-data
WorkingDirectory=/var/www/myapp
ExecStart=/var/www/myapp/myapp
Restart=on-failure

[Install]
WantedBy=multi-user.target

Enable and start:

sudo systemctl enable myapp
sudo systemctl start myapp

6. Troubleshooting

Installation Issues

"go: command not found"

  • Verify export PATH=$PATH:/usr/local/go/bin is in ~/.bashrc, ~/.zshrc, or ~/.profile
  • Run source ~/.profile or restart terminal

"cannot find GOROOT"

# Explicitly set GOROOT (usually not needed)
export GOROOT=/usr/local/go
export PATH=$PATH:$GOROOT/bin

Build Failures from Source

"Building Go cmd/dist using bootstrap/go-1.20.6" fails:

  • Ensure bootstrap Go version is 1.20.6 or later
  • Check GOROOT_BOOTSTRAP points to valid Go installation
  • On macOS, ensure Xcode Command Line Tools are installed: xcode-select --install

"runtime: unknown pc" during tests:

  • Disable tests temporarily: ./make.bash instead of ./all.bash
  • Check for hardware issues (RAM/disk corruption)

Module/Dependency Issues

"dial tcp: lookup proxy.golang.org: no such host"

  • Set GOPROXY to direct: export GOPROXY=direct
  • Or use corporate proxy: export GOPROXY=https://corp-proxy.example.com

"verifying module: checksum mismatch"

# Clean module cache
go clean -modcache
go mod download

Runtime Panics (from src/runtime/panic.go)

"panic: runtime error: index out of range"

  • Check array/slice bounds before access
  • Enable bounds checking: go build -gcflags="-B"

"fatal error: runtime: out of memory"

  • Increase system memory or reduce goroutine count
  • Profile memory usage: go tool pprof http://localhost:6060/debug/pprof/heap

Cross-Compilation Issues

"undefined: syscall.SYS_IOCTL" when targeting different OS:

  • Avoid using syscall package directly; use golang.org/x/sys/unix or golang.org/x/sys/windows
  • Ensure CGO is disabled for cross-compilation: CGO_ENABLED=0

Linker Issues (ARM64/ELF specific)

"relocation target not defined" (from src/cmd/link/internal/arm64/asm.go):

  • Update to latest Go version (linker bugs are frequently fixed)
  • Check for assembly code compatibility with target architecture
  • Verify go mod tidy has been run

General Debugging

Get verbose build output:

go build -x -v

Check environment:

go env

Race conditions:

go run -race main.go
← Project overviewView alternatives to golang/go →