Installation & Environment Setup

This guide walks through setting up a complete Gen-X development environment: all four repositories cloned and linked, ATC and DevT installed and running, and the shell tooling you need for daily development in place.

Prerequisites

The following tools must be installed before you begin.

Clone the Repositories

Gen-X depends on three companion repositories in addition to the generator itself. Clone all four into the same parent directory — by convention ~/go/src/.

# App generator — the core project you will work in most often
git clone git@gitlab.com:blue-lila/gen-x.git ~/go/src/gen-x

# ATC — Apps Control Tower, the GUI for registering and managing apps
git clone git@gitlab.com:blue-lila/atc.git ~/go/src/atc

# DevT — Developer Tools, utilities and the Git sync interface
git clone git@gitlab.com:blue-lila/devt.git ~/go/src/devt

# KitCla — stateless UI component library used by all generated apps
git clone git@gitlab.com:blue-lila/kitcla.git ~/go/src/kitcla

Configure Dependencies

Gen-X’s go.mod uses replace directives to reference the companion repositories by local path. Update each path to match your setup before installing dependencies.

📝 Note: Open go.mod in the gen-x repository and update the replace block at the bottom. Change each path so it points to your actual ~/go/src/ directory — for example, replace /home/username/go/src/kitcla with /home/YOUR_USERNAME/go/src/kitcla. If any path is incorrect, go mod tidy will fail with a module-not-found error.

Once the paths are correct, resolve the module graph from the gen-x directory.

cd ~/go/src/gen-x
go mod tidy && go mod vendor

Install ATC and DevT

Each companion service ships with a shell installer. Copy the environment file template first, then run the install script.

# Install ATC
cd ~/go/src/atc
cp config/env.dot.dist config/env.dot
./bin/install/install-linux.sh

# Install DevT
cd ~/go/src/devt
cp config/env.dot.dist config/env.dot
./bin/install/install-linux.sh

⚠️ Warning: Never commit config/env.dot — it contains local secrets and machine-specific configuration. Only config/env.dot.dist is safe to commit. Both repositories include env.dot in their .gitignore by default.

Port Map

Each service in the Gen-X development stack runs on a fixed port.

Shell Aliases

Add these aliases to your ~/.bashrc or ~/.zshrc to match the commands used throughout this documentation.

# Navigate to the go/src workspace
alias cdgo='cd ~/go/src'

# Navigate directly to gen-x
alias cdgen='cd ~/go/src/gen-x'

# Run the TDD test suite
alias tdd='ENV=test go test ./tests/... -v'

# Start the app in development mode (build → init → run, port 8086)
alias bird='cd . && ./bin/build/app_dev.sh && ./bin/init/app_dev.sh && ./bin/run/app_web_dev.sh'

# Start the app in production mode
alias birp='cd . && ./bin/build/app_prod.sh && ./bin/init/app_prod.sh && ./bin/run/app_web_prod.sh'

# Tailwind CSS shorthand used by build scripts
alias tailwindcss='npx tailwindcss'

💡 Tip: After adding the aliases, run source ~/.zshrc (or source ~/.bashrc) to activate them in your current session without opening a new terminal.

Custom Keyboard Shortcut

The Accept shortcut triggers the TDD acceptance endpoint at localhost:9289. When the TDD runner pauses and waits for you to accept a set of generated changes, pressing this shortcut submits the acceptance without switching focus away from your editor.

Register it through your desktop environment’s keyboard settings.

Settings → Keyboard → View and Customize Shortcuts → Custom Shortcuts → +

Name:     Accept
Command:  curl http://localhost:9289
Shortcut: Super + X  (Super = Windows key)

Verifying Your Setup

Confirm both services are responding before continuing.

curl -s http://localhost:4555/ping
curl -s http://localhost:8077/ping

If both commands return a response, your environment is ready and you can proceed to create your first application.

Next Steps

• Your First Generated Application — Build SeedVault, a two-model app with a relation
• Daily Workflow — The recommended daily development loop
• Developer Setup (full reference) — Complete setup details including TDD configuration and the full alias reference