moul.dev

Guide for compiling Moul from source, running development hot-reload environments, and executing test suites.

If you are developing features for Moul, embedding custom Go handlers, or contributing to the core engine and UI, this guide covers setting up your local development environment, compiling binaries from source, and running automated test suites.

Prerequisites

Ensure you have the following toolchains installed on your development machine:

Go: Version 1.26 or higher
Node.js / Bun: Node 20+ or Bun 1.1+ (for Web Admin UI compilation)

Air (Optional, for Go live hot-reloading):

go install github.com/air-verse/air@latest

Clone and Setup

git clone https://github.com/moul-dev/moul-dev.git
cd moul-dev

# Install Web Admin UI dependencies
make ui-install

Compiling Binaries

Moul compiles into two standalone single binaries with stripped debug symbols and all static assets embedded:

# 1. Build the 'moul' server engine with embedded Web Admin UI
make build
# Output: ./bin/moul

# 2. Build the 'moul-ctl' TUI console binary
make build-ctl
# Output: ./bin/moul-ctl

Local Development Workflows

# Runs backend with Air hot-reload and Vite Admin UI concurrently
make dev-all

# Live hot-reloading for Go backend changes
make dev

# Start Vite development server for the Web Admin UI with HMR
make ui-dev

Running TUI from Source

You can launch the Bubble Tea terminal UI directly from source against your running local server:

make ctl
# Or run directly with Go:
go run cmd/moul-ctl/main.go
# Or via moul convenience command:
./bin/moul ctl

Seeding Fixtures & Type Generation

# Populate local SQLite database with demo collections and records
make seed

# Generate TypeScript type definitions from collection schemas into UI
make typegen

Running Test Suites

Moul includes comprehensive unit, integration, and end-to-end verification suites:

# Run all Go unit and internal package tests
make test-go

# Run in-process end-to-end test suite (race detector enabled)
make test-e2e

# Run live HTTP API verification scripts against a running server
make test-flow
make test-worker
make test-analytics

# Run TUI tests
make test-tui

# Generate test coverage report
make test-coverage

Code Quality & Linting

# Run golangci-lint
make lint

# Automatically format code and apply lint fixes
make lint-fix

Building from Source & Contributor Workflows