Getting Started/Quick Start

Quick Start

Get Hatch running locally in under 15 minutes. This guide walks you through cloning the repo, wiring up GitHub OAuth, spinning up local infrastructure, and making your first deployment.

~30 MIN AWS COSTS APPLY TERRAFORM REQUIRED

Prerequisites

Make sure you have the following installed and configured before starting.

Go 1.23+

API, builder, and deployer services

Node.js 20+

Next.js frontend

Docker + Compose

Local infrastructure & image builds

AWS CLI

Configured with IAM credentials

Terraform 1.5+

Infrastructure provisioning

golang-migrate

Running database migrations

Clone & Install

Clone the Hatch monorepo and install dependencies for the workspace and frontend.

bash

git clone https://github.com/YHQZ1/Hatch.git
cd Hatch

bash

cd apps/web && npm install && cd ../..
go work sync

GitHub OAuth App

Hatch uses GitHub OAuth for authentication. Create an OAuth App in your GitHub settings.

Visit github.com/settings/developers → OAuth Apps → New OAuth App:

Field	Value
Application name	Hatch
Homepage URL	http://localhost:3000
Authorization callback URL	http://localhost:8080/auth/callback

Copy the Client ID and generated Client Secret. You will need these for your environment configuration in the next step.

Environment Variables

bash

cp apps/api/.env.example apps/api/.env
cp apps/builder/.env.example apps/builder/.env
cp apps/deployer/.env.example apps/deployer/.env
cp apps/web/.env.local.example apps/web/.env.local

apps/api/.env

PORT=8080
GITHUB_CLIENT_ID=your_github_client_id
GITHUB_CLIENT_SECRET=your_github_client_secret
GITHUB_REDIRECT_URI=http://localhost:8080/auth/callback
JWT_SECRET=a_long_random_string_at_least_32_chars
DATABASE_URL=postgres://hatch:hatch@localhost:5432/hatch?sslmode=disable
REDIS_URL=redis://localhost:6379
RABBITMQ_URL=amqp://guest:guest@localhost:5672/

Local Infrastructure

bash

docker compose up -d postgres redis rabbitmq

Infrastructure binds: PostgreSQL (5432), Redis (6379), and RabbitMQ (5672).

Run Migrations

bash

migrate -path packages/db/migrations -database "postgres://hatch:hatch@localhost:5432/hatch?sslmode=disable" up

Run Services

bash

# Terminal 1 — API
cd apps/api && go run cmd/server/main.go

# Terminal 2 — Builder
cd apps/builder && go run cmd/worker/main.go

# Terminal 3 — Deployer
cd apps/deployer && go run cmd/worker/main.go

# Terminal 4 — Frontend
cd apps/web && npm run dev

Open localhost:3000 to connect your GitHub account and initiate your first deployment. Build logs will stream live via WebSockets.

Next Steps

Self-Hosting GuideDOCS

Provision Hatch on AWS with Terraform.

Environment VariablesREF

Full configuration reference.

ArchitectureSYSTEM

Understanding the system blueprint.

RoadmapPROJECT

Planned features and milestones.