Local Development Setup

Overview

Adapt provides a streamlined development environment with a single command that handles everything: database setup, migrations, and hot reloading. This guide walks you through local installation and development.

Prerequisites

Before you begin, ensure you have the following installed:

Go 1.26

Adapt uses Go 1.26 for advanced features and runtime improvements.

# Check your Go version
go version

# Should output: go version go1.26.x

Download Go 1.26

Docker Desktop

Required for running the local Supabase instance.

# Verify Docker is running
docker ps

Download Docker Desktop

Supabase CLI

Used for database management and migrations.

# Mac/Linux
brew install supabase/tap/supabase

# Windows
npm install -g supabase

# Verify installation
supabase --version

Air (Hot Reloading)

Provides automatic reloading during development.

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

Git

Version control system.

git --version

Optional: Install golangci-lint for local code quality checks:

brew install golangci-lint

Quick Setup

1. Clone the Repository

# Fork and clone the repository
git clone https://github.com/Harvey-AU/adapt.git
cd adapt

# Setup Git 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

2. Start Development Environment

That’s it! Just run one command:

# Clean output (info level logging)
./dev.sh

# Verbose output (debug level logging)
./dev.sh debug

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

The development server runs on http://localhost:8847

3. Environment Configuration (Automatic)

The app automatically uses .env.local for development, which provides:

.env.local

# 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’re in .gitignore by default.

4. Access Local Services

Once running, you can access:

Adapt Application: http://localhost:8847
Supabase Studio: http://localhost:54323 (database management)
Supabase API: http://localhost:54321
Database: postgresql://postgres:postgres@localhost:54322/postgres

Database Migrations

Creating New Migrations

Migrations are fully automatic with the dev.sh script:

# 1. Generate a new migration file
supabase migration new add_user_preferences

# 2. Edit the file in supabase/migrations/
# Example: supabase/migrations/20250103_add_user_preferences.sql

# 3. Save the file
# 🎉 Database automatically resets and applies the migration!
# 🎉 Go app automatically restarts with the new schema!

No manual steps required - the dev.sh script watches for migration changes and automatically runs supabase db reset when you save any .sql file.

Migration Best Practices

Keep migrations additive: Don’t modify deployed migrations
Use descriptive names: add_scheduler_table.sql not migration_001.sql
Test locally first: Verify migrations work before committing
One change per migration: Easier to debug and rollback

Deployment Process

Push changes to feature branch
Test migrations locally
Merge to main - migrations apply automatically via Supabase GitHub integration

Never run supabase db push manually. Supabase GitHub integration handles all migration deployment.

Development Workflow

Hot Reloading

Air automatically reloads the app when you make changes to:

Go source files (.go)
HTML templates (.html)
Static assets

No need to restart the server manually!

Running Tests

# Run all tests
./run-tests.sh

# Run tests with coverage
go test -v -coverprofile=coverage.out ./...

# View coverage report
go tool cover -html=coverage.out

Code Formatting

Formatting is automatic via pre-commit hooks, but you can manually format:

# 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

Manual API Testing

Test API endpoints using curl or httpie:

# Install httpie (optional)
pip install httpie

# Test health endpoint
http GET localhost:8847/health

# Test job creation (requires auth token)
http POST localhost:8847/v1/jobs \
  Authorization:"Bearer YOUR_JWT_TOKEN" \
  domain=example.com \
  use_sitemap:=true

Database Access

Access the local database directly:

# Using Supabase Studio
open http://localhost:54323

# Using psql
psql postgresql://postgres:postgres@localhost:54322/postgres

Code Organization

Understanding the codebase structure:

adapt/
├── cmd/
│   ├── app/              # Main application entry point
│   │   └── main.go
│   └── test_jobs/        # Job queue testing utility
│       └── main.go
├── internal/
│   ├── api/              # HTTP handlers and middleware
│   │   ├── handlers.go   # Route handlers
│   │   ├── auth.go       # JWT authentication
│   │   └── jobs.go       # Job management endpoints
│   ├── auth/             # Authentication logic
│   ├── crawler/          # Web crawling functionality
│   ├── db/               # Database operations
│   ├── jobs/             # Job queue and worker management
│   └── util/             # Shared utilities
├── web/
│   ├── static/           # CSS, JS, images
│   ├── templates/        # HTML templates
│   └── partials/         # Reusable HTML components
├── supabase/
│   └── migrations/       # Database migrations
├── docs/                 # Architecture and API docs
└── scripts/              # Development and deployment scripts

Debugging

Log Levels

Set LOG_LEVEL in .env.local:

debug - Verbose logging for development (default in dev mode)
info - Standard operational logging
warn - Warning conditions only
error - Error conditions only

Common Debug Commands

# Run with race detection
go run -race ./cmd/app/main.go

# Profile memory usage
go run ./cmd/app/main.go -memprofile=mem.prof

# Check for goroutine leaks
GODEBUG=gctrace=1 go run ./cmd/app/main.go

Sentry Integration

In development, Sentry captures all traces (100% sampling):

.env.local

DEBUG=true
SENTRY_DSN=your_dsn

Troubleshooting

Docker Not Running

Error: Docker is not running. Please start Docker first.

Solution: Start Docker Desktop and wait for it to fully initialize.

Port Already in Use

Error: listen tcp :8847: bind: address already in use

Solution: Kill the process using port 8847:

# Find process using port 8847
lsof -i :8847

# Kill process
kill -9 <PID>

Supabase CLI Not Found

Error: Supabase CLI is not installed.

Solution: Install Supabase CLI:

# Mac/Linux
brew install supabase/tap/supabase

# Windows
npm install -g supabase

Migration Errors

Error: migration failed: syntax error at or near "ALTER"

Solution: Check your migration SQL syntax. Review the migration file in supabase/migrations/.

Module Dependencies

Error: missing go.sum entry

Solution: Clean and re-download dependencies:

# Clean module cache
go clean -modcache

# Re-download dependencies
go mod download

Contributing

Code Quality Checklist

Before submitting a pull request:

Code formatted with go fmt ./...
No issues from go vet ./...
All tests pass with ./run-tests.sh
Update relevant documentation
Push and verify GitHub Actions pass

Commit Messages

Use conventional commits:

feat: - New feature
fix: - Bug fix
docs: - Documentation changes
refactor: - Code refactoring
test: - Test additions/changes
chore: - Maintenance tasks

Examples:

git commit -m "feat: add scheduler API endpoints"
git commit -m "fix: resolve cache warming retry logic"
git commit -m "docs: update installation guide"

Git Workflow

# Create feature branch from main
git checkout -b feature/your-feature

# Make changes and commit
git add .
git commit -m "feat: add new feature"

# Push and create PR
git push origin feature/your-feature

See BRANCHING.md for comprehensive Git workflow.

Next Steps

Architecture Overview

Understand the system design and core components

API Reference

Explore endpoint documentation and examples

Database Schema

Learn about the database structure and migrations

Testing Guide

Write and run tests for Adapt

Getting Help

Check existing documentation in this guide and ARCHITECTURE.md
Search closed issues on GitHub for similar problems
Enable debug logging to get more context
Create minimal reproduction case for bugs
Open GitHub issue with detailed information

For security-related issues, see the Security Policy.

Get Started

Core Features

Integrations

Guides

​Overview

​Prerequisites

​Quick Setup

​1. Clone the Repository

​2. Start Development Environment

​3. Environment Configuration (Automatic)

​4. Access Local Services

​Database Migrations

​Creating New Migrations

​Migration Best Practices

​Deployment Process

​Development Workflow

​Hot Reloading

​Running Tests

​Code Formatting

​Manual API Testing

​Database Access

​Code Organization

​Debugging

​Log Levels

​Common Debug Commands

​Sentry Integration

​Troubleshooting

​Docker Not Running

​Port Already in Use

​Supabase CLI Not Found

​Migration Errors

​Module Dependencies

​Contributing

​Code Quality Checklist

​Commit Messages

​Git Workflow

​Next Steps

Architecture Overview

API Reference

Database Schema

Testing Guide

​Getting Help

Build docs developers (and LLMs) love

Overview

Prerequisites

Quick Setup

1. Clone the Repository

2. Start Development Environment

3. Environment Configuration (Automatic)

4. Access Local Services

Database Migrations

Creating New Migrations

Migration Best Practices

Deployment Process

Development Workflow

Hot Reloading

Running Tests

Code Formatting

Manual API Testing

Database Access

Code Organization

Debugging

Log Levels

Common Debug Commands

Sentry Integration

Troubleshooting

Docker Not Running

Port Already in Use

Supabase CLI Not Found

Migration Errors

Module Dependencies

Contributing

Code Quality Checklist

Commit Messages

Git Workflow

Next Steps

Getting Help