Building Guide

Building Guide

Building ION Flow - How to compile and package the application.

---

Overview

ION Flow consists of multiple Go modules that can be built independently or together.

---

Prerequisites

Requirement	Version	Notes
Go	1.24.3+	go version
GCC	Any	Required for SQLite CGO
Git	2.x	For version info

CGO Requirement

SQLite requires CGO. Ensure you have:

# macOS
xcode-select --install

# Linux (Debian/Ubuntu)
sudo apt-get install build-essential

# Linux (RHEL/CentOS)
sudo yum groupinstall "Development Tools"

---

Building Backend

Development Build

# From project root
go build -o bin/ion-flow main.go

# Or using go run
go run main.go

Production Build

# With optimizations
go build -ldflags="-s -w" -o bin/ion-flow main.go

# With version info
VERSION=$(git describe --tags --always)
go build -ldflags="-s -w -X main.Version=${VERSION}" -o bin/ion-flow main.go

Cross-Compilation

# Linux AMD64
GOOS=linux GOARCH=amd64 CGO_ENABLED=1 go build -o bin/ion-flow-linux-amd64 main.go

# Linux ARM64
GOOS=linux GOARCH=arm64 CGO_ENABLED=1 go build -o bin/ion-flow-linux-arm64 main.go

# macOS AMD64
GOOS=darwin GOARCH=amd64 CGO_ENABLED=1 go build -o bin/ion-flow-darwin-amd64 main.go

# macOS ARM64 (Apple Silicon)
GOOS=darwin GOARCH=arm64 CGO_ENABLED=1 go build -o bin/ion-flow-darwin-arm64 main.go

Note: Cross-compilation with CGO requires appropriate cross-compilers.

---

Building Server

cd server

# Development
go build -o bin/flow-server .

# Production
go build -ldflags="-s -w" -o bin/flow-server .

---

Building Core Library

The core module is typically used as a library, but can be tested:

cd core
go build ./...
go test ./...

---

Build Scripts

Makefile

.PHONY: build build-server clean test

VERSION := $(shell git describe --tags --always)
LDFLAGS := -ldflags="-s -w -X main.Version=$(VERSION)"

build:
  go build $(LDFLAGS) -o bin/ion-flow main.go

build-server:
  cd server && go build $(LDFLAGS) -o ../bin/flow-server .

clean:
  rm -rf bin/
  rm -f coverage.out

test:
  go test -cover ./...

all: clean build build-server

Build Script

build.sh

#!/bin/bash
set -e

VERSION=$(git describe --tags --always)
LDFLAGS="-s -w -X main.Version=${VERSION}"

echo "Building ION Flow v${VERSION}..."

# Clean
rm -rf bin/

# Build backend
echo "Building backend..."
go build -ldflags="${LDFLAGS}" -o bin/ion-flow main.go

# Build server
echo "Building server..."
cd server
go build -ldflags="${LDFLAGS}" -o ../bin/flow-server .
cd ..

echo "Build complete!"
ls -la bin/

---

Docker Build

Dockerfile

# Build stage
FROM golang:1.24-alpine AS builder

RUN apk add --no-cache gcc musl-dev

WORKDIR /app

# Copy go.mod files
COPY go.mod go.sum ./
COPY core/go.mod core/go.sum ./core/
COPY backend/go.mod backend/go.sum ./backend/
COPY packages/helpers/go.mod ./packages/helpers/
COPY packages/channel/go.mod packages/channel/go.sum ./packages/channel/
COPY server/go.mod server/go.sum ./server/

# Download dependencies
RUN go mod download

# Copy source
COPY . .

# Build
RUN CGO_ENABLED=1 go build -ldflags="-s -w" -o /ion-flow main.go

# Runtime stage
FROM alpine:latest

RUN apk add --no-cache ca-certificates

WORKDIR /app

COPY --from=builder /ion-flow .

# Create storage directories
RUN mkdir -p storage/dbs storage/store storage/repos

EXPOSE 8000

CMD ["./ion-flow"]

Build Docker Image

docker build -t ion-flow:latest .
docker run -p 8000:8000 -v ./storage:/app/storage ion-flow:latest

---

Build Optimizations

Size Reduction

# Strip debug info
go build -ldflags="-s -w" -o bin/ion-flow main.go

# Use UPX compression (if available)
upx --best bin/ion-flow

Build Tags

# Production build
go build -tags production -o bin/ion-flow main.go

# With specific features
go build -tags "json1 fts5" -o bin/ion-flow main.go

---

Verifying Build

Check Binary

# File info
file bin/ion-flow

# Version (if embedded)
./bin/ion-flow --version

# Run
./bin/ion-flow

Test Binary

# Quick health check
curl http://localhost:8000/health

# Or for server
./bin/flow-server -port 8080 &
curl http://localhost:8080/data-store-list

---

CI/CD Integration

GitLab CI/CD Example

.gitlab-ci.yml

image: golang:1.24

stages:
  - test
  - build

before_script:
  - apt-get update && apt-get install -y gcc musl-dev

test:
  stage: test
  script:
    - go test -v ./...

build:
  stage: build
  script:
    - go build -ldflags="-s -w" -o bin/ion-flow main.go
  artifacts:
    paths:
      - bin/ion-flow
    expire_in: 1 week

---

Troubleshooting

CGO Errors

# Ensure GCC is installed
gcc --version

# Set CGO_ENABLED
CGO_ENABLED=1 go build ...

SQLite Errors

# Install SQLite development headers
# Debian/Ubuntu
sudo apt-get install libsqlite3-dev

# macOS (usually included)
# RHEL/CentOS
sudo yum install sqlite-devel

Module Errors

# Clean module cache
go clean -modcache

# Re-download
go mod download

---

Related Documentation

• Development Guide - Development setup
• Deployment Guide - Deployment process
• Testing Guide - Testing