QuackbackQuackback
Navigation

Set up local development

Start building in minutes. One command sets up everything: installs dependencies, configures the database, and runs migrations. Then you're ready to develop.

Prerequisites

RequirementVersionPurpose
Bun1.3.7+Runtime and package manager
Docker20.10+PostgreSQL 18+ database
Git2.30+Version control
Node.js20+Optional, for some tooling

Install Bun

# macOS/Linux
curl -fsSL https://bun.sh/install | bash
 
# Windows (WSL)
curl -fsSL https://bun.sh/install | bash

Install Docker

Quick Setup

The fastest way to get started:

# Clone the repository
git clone https://github.com/quackbackio/quackback.git
cd quackback
 
# Run automated setup
bun run setup

The setup script:

  1. Checks for Bun and Docker
  2. Installs dependencies
  3. Creates .env from template
  4. Generates auth secret
  5. Starts PostgreSQL container
  6. Runs database migrations

Manual Setup

If you prefer manual setup:

1. Install Dependencies

bun install

2. Configure Environment

cp .env.example .env

Generate a secret:

openssl rand -base64 32

Edit .env:

DATABASE_URL="postgresql://postgres:password@localhost:5432/quackback"
SECRET_KEY="your-generated-secret-here"
BASE_URL="http://localhost:3000"
REDIS_URL="redis://localhost:6379"

3. Start PostgreSQL

docker compose up -d postgres

Wait for it to be healthy:

docker compose ps  # Should show "healthy"

4. Run Migrations

bun run db:migrate

5. Seed Demo Data (Optional)

bun run db:seed

This creates a demo workspace with sample data.

Start Development Server

bun run dev

Open http://localhost:3000.

Demo Login

If you ran the seed, log in with demo@example.com / password.

Project Structure

quackback/
├── apps/web/                 # Main TanStack Start application
│   ├── src/
│   │   ├── routes/           # File-based routing
│   │   ├── components/       # React components
│   │   └── lib/              # Business logic & utilities
│   ├── e2e/                  # Playwright E2E tests
│   └── public/               # Static assets
│
├── packages/                 # Shared packages
│   ├── db/                   # Database schema & migrations
│   ├── ids/                  # TypeID system
│   ├── email/                # Email service & templates
│   ├── core/                 # Shared core utilities
│   └── integrations/         # Integration connectors
│
├── deploy/                   # Deployment configurations
├── scripts/                  # Utility scripts
└── docker-compose.yml        # Local development services

Common Commands

# Development
bun run dev              # Start dev server
bun run build            # Production build
 
# Database
bun run db:generate      # Generate migration from schema changes
bun run db:migrate       # Run pending migrations
bun run db:studio        # Open Drizzle Studio (DB GUI)
bun run db:seed          # Seed demo data
bun run db:reset         # Reset database (destructive!)
 
# Code Quality
bun run lint             # ESLint + Prettier check
 
# Testing
bun run test             # Run Vitest tests
bun run test <file>      # Run single test file
bun run test:e2e         # Playwright E2E tests
cd apps/web && bun run test:e2e:ui   # E2E with interactive UI

IDE Setup

VS Code

Recommended extensions:

  • ESLint
  • Prettier
  • Tailwind CSS IntelliSense

Settings (.vscode/settings.json):

{
  "editor.formatOnSave": true,
  "editor.defaultFormatter": "esbenp.prettier-vscode",
  "editor.codeActionsOnSave": {
    "source.fixAll.eslint": true
  }
}

Other IDEs

The project uses:

  • ESLint for linting
  • Prettier for formatting
  • TypeScript for type checking

Configure your IDE to use these tools.

Database Management

Drizzle Studio

Visual database browser:

bun run db:studio

Opens at https://local.drizzle.studio.

Direct Access

Connect via psql:

docker compose exec postgres psql -U postgres quackback

Or use any PostgreSQL client with:

  • Host: localhost
  • Port: 5432
  • User: postgres
  • Password: password
  • Database: quackback

Reset Database

Wipe everything and start fresh:

bun run db:reset

This command destroys all data in the database.

Troubleshooting

Port Already in Use

# Find process on port 3000
lsof -i :3000
 
# Kill it
kill -9 <PID>
 
# Or use a different port
PORT=3001 bun run dev

Database Connection Failed

# Check if PostgreSQL is running
docker compose ps
 
# Restart it
docker compose restart postgres
 
# Check logs
docker compose logs postgres

Migrations Failed

# See detailed error
bun run db:migrate 2>&1
 
# Reset and retry
bun run db:reset
bun run db:migrate

Dependencies Issues

# Clear and reinstall
rm -rf node_modules bun.lock
bun install

Next Steps