Skip to main content

​
Prerequisites

Before you begin, ensure you have the following tools installed:
  • Go 1.26 - We use Go 1.26 for advanced features and runtime improvements
  • Docker Desktop - Required for local Supabase instance (Download here)
  • Supabase CLI - Database management
    • Mac: brew install supabase/tap/supabase
    • Windows/Linux: npm install -g supabase
  • Air - Hot reloading for development: go install github.com/air-verse/air@latest
  • Git - Version control
  • golangci-lint (optional) - Code quality checks: brew install golangci-lint

​
Quick Start

1

Clone the repository

Fork and clone the Adapt repository:
git clone https://github.com/[your-username]/adapt.git
cd adapt
2

Setup Git hooks

Enable pre-commit hooks for automatic formatting:
bash scripts/setup-hooks.sh
The Git hooks will automatically format your code before each commit:
  • Go files formatted with gofmt
  • Markdown, YAML, JSON formatted with Prettier
  • No manual formatting needed!
3

Start development environment

That’s it! Just run:
dev              # Clean output (info level)
dev debug        # Verbose output (debug level)
This single command will:
  • ✅ Check prerequisites (Docker Desktop + Supabase CLI)
  • ✅ Start local Supabase instance (if not running)
  • ✅ Apply all database migrations automatically
  • ✅ Watch for migration changes and auto-reset database
  • ✅ Configure Air for your platform automatically
  • ✅ Connect to isolated local database on port 54322
  • ✅ Start the app with hot reloading on port 8847
  • ✅ Display helpful URLs for easy access
  • ✅ Use clean logging by default (info level)
  • ✅ Zero production database interference

​
Environment Configuration

The app automatically uses .env.local for development, which provides: 
# Local Supabase Configuration (auto-configured)
DATABASE_URL=postgresql://postgres:postgres@localhost:54322/postgres
SUPABASE_URL=http://localhost:54321
APP_ENV=development
LOG_LEVEL=debug

# Production uses .env (different database)
# No manual configuration required!
Never commit .env or .env.local files. They may contain sensitive credentials.

​
Development Server

Once started, the server will be available at:
  • App: http://localhost:8847
  • Supabase Studio: http://localhost:54323
  • Local Database: postgresql://postgres:postgres@localhost:54322/postgres

​
Hot Reloading

Air provides automatic hot reloading:
  • Watches Go files for changes
  • Automatically rebuilds and restarts the server
  • Displays build errors in real-time

​
Manual Start (Without Hot Reloading)

# Build and run
go build ./cmd/app && ./app

# Or run directly
go run ./cmd/app/main.go

​
Database Migrations

Creating new migrations (fully automatic):
1

Generate migration file

supabase migration new your_migration_name
2

Edit the migration

Edit the file in supabase/migrations/ with your SQL changes
3

Save and watch it apply

🎉 Database automatically resets and applies the migration!🎉 Go app automatically restarts with the new schema!
No manual steps required - the dev script watches for migration changes and automatically runs supabase db reset when you save any .sql file.
Never run supabase db push manually. Supabase GitHub integration handles all migration deployment.

​
Prerequisites Check

If air fails, verify your setup: 
# Check Docker Desktop is running
docker ps

# Check Supabase CLI is installed
supabase --version

# Check Air is installed
air -v

​
Code Quality

​
Formatting (Automatic)

Pre-commit hooks automatically format files - you don’t need to do anything! To manually format all files: 
# Format everything (Go + docs/config + web files)
bash scripts/format.sh

# Or format individually:
gofmt -w .                                              # Go files only
prettier --write "**/*.{md,yml,yaml,json,html,css,js}"  # Docs/config/web files

​
Local Development Checks

Before pushing, run these local checks: 
# 1. Basic static analysis (5-10 seconds)
go vet ./...

# 2. Run tests (1-2 minutes)
./run-tests.sh

# 3. Check coverage (optional)
go test -v -coverprofile=coverage.out ./...

​
CI Linting (Enforced)

Our GitHub Actions CI runs golangci-lint v2.9.0 with Go 1.26 support:
  • Runs automatically on every push/PR
  • Blocks merges if linting fails
  • Core linters enabled: govet, staticcheck, errcheck, revive, gofmt, goimports, ineffassign, gocyclo, misspell
  • Configured for Australian English spelling
  • Cyclomatic complexity threshold: 35

​
Troubleshooting

​
Database Connection Errors

# Check PostgreSQL is running
pg_isready -h localhost -p 54322

# Verify Supabase is running
supabase status

​
Port Already in Use

# Find process using port 8847
lsof -i :8847

# Kill process
kill -9 <PID>

​
Module Dependencies

# Clean module cache
go clean -modcache

# Re-download dependencies
go mod download

​
Hot Reloading Not Working

# Verify Air configuration
cat .air.toml

# Reinstall Air
go install github.com/air-verse/air@latest

​
Next Steps

Build docs developers (and LLMs) love

Get started for freeTalk to us