Running from Source

This guide covers everything needed to get flow8 running directly from the Go source code — for local development, debugging, or building a custom binary.

Prerequisites

Go

flow8 requires Go 1.24.2. Install via the official installer at https://go.dev/dl/ or use asdf/mise for version management.

go version
# go version go1.24.2 linux/amd64

MongoDB

flow8 requires MongoDB as its primary database. For local development, run it via Docker:

docker run -d --name mongo -p 27017:27017 mongo:latest

Or use Docker Compose (see docker-compose.dev.yml).

System Dependencies

Document processing capabilities require native binaries. Install on macOS:

brew install imagemagick tesseract liboffice

On Ubuntu/Debian:

apt-get install -y imagemagick tesseract-ocr libreoffice

Verify each:

convert --version        # ImageMagick
tesseract --version      # Tesseract OCR
soffice --version        # LibreOffice

The path to soffice is configured in .config.yaml under path.soffice. On macOS the default is /Applications/LibreOffice.app/Contents/MacOS/soffice.

Private Go Module Access

flow8 depends on github.com/osbits/gorgany, a private Go module. Set the following before running go mod download or go run:

export GOPRIVATE=git.qix.sx/gorgany/gorgany.git
export GIT_HOST=github.com
export GIT_USER=username
export GIT_PASS=your_access_token
export GOPROXY=https://goproxy.cn

Configure Git credentials so the Go toolchain can fetch the private module:

git config --global url."https://${GIT_USER}:${GIT_PASS}@${GIT_HOST}/".insteadOf "https://${GIT_HOST}/"

Environment Setup

Copy the example environment file and fill in the required values:

cp .env.example .env

Minimum required values for local development:

SERVER_PORT=4454
MONGODB_URI=mongodb://localhost:27017
MONGODB_DB=ud
API_URL=http://localhost:4454/api/
ENV_KEY_SALT=<generate 64 random hex chars>
ENC_KEY_SECRET=<generate 256 random hex chars>

Generate encryption keys:

# 64-char hex salt
openssl rand -hex 32

# 256-char hex secret
openssl rand -hex 128

Build Commands

# Run server directly (development)
go run server.go

# Build production binary
go build -o main server.go

# Run the built binary
./main

Running Tests

# Run all tests
go test ./...

# Run tests for a specific package with verbose output
go test ./pkg/service/... -v

# Run a specific test by name
go test ./pkg/plugins/layers/v2/... -run TestIterator

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

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

Generating the Module Catalog

To regenerate the CSV listing all 135+ modules with their metadata:

go run cmd/modulescsv/main.go

Output is written to the project root as modules.csv.

Remote Debugger (Delve)

The docker-compose.local.yml profile starts the server with the Delve debugger listening on port 2345:

COMPOSE_FILE=docker-compose.local.yml docker-compose up

The entrypoint in this profile is:

dlv --listen=:2345 --headless=true --log=true --accept-multiclient --api-version=2 exec /app/flow8core

Connect from VS Code using a launch.json remote attach configuration:

{
  "type": "go",
  "request": "attach",
  "name": "Attach to flow8 (Delve)",
  "mode": "remote",
  "remotePath": "/app",
  "port": 2345,
  "host": "127.0.0.1"
}

This profile also includes a PostgreSQL service on port 5744 for testing database modules.

Common Development Workflow

# 1. Start dependencies
docker-compose -f docker-compose.dev.yml up -d mongo

# 2. Set environment
source .env   # or export vars manually

# 3. Run server with live reload (using air)
air -c .air.toml

# 4. Or just run directly
go run server.go