QuackbackQuackback
Navigation

Quick Start

Ready to try Quackback? You'll have it running in under 5 minutes.

Prerequisites

  • Bun (v1.3.7+) and Docker with Docker Compose installed
  • A domain or subdomain (for production)

One-Command Setup

# Clone the repository
git clone https://github.com/quackbackio/quackback.git
cd quackback
 
# Run setup (starts Docker services, installs deps, runs migrations)
bun run setup
 
# (Optional) Seed demo data (~500 posts, sample boards, statuses)
bun run db:seed

Then start the dev server:

bun run dev

Quackback is now running at http://localhost:3000.

First-Time Setup

  1. Open the app - Navigate to http://localhost:3000
  2. Complete onboarding - Follow the setup wizard to create your account (name, email, password), configure your workspace name, and create your first board
  3. Sign in - If you ran bun run db:seed, use demo@example.com with password password
  4. Explore - If seeded, the demo data includes sample boards, posts, and statuses

Environment Configuration

Edit .env with your settings:

# Required
DATABASE_URL="postgresql://postgres:password@localhost:5432/quackback"
SECRET_KEY=""
BASE_URL="http://localhost:3000"
REDIS_URL="redis://localhost:6379"
 
# Email (optional - emails print to console if not configured)
EMAIL_SMTP_HOST="smtp.example.com"
EMAIL_SMTP_PORT="587"
EMAIL_SMTP_USER="your-smtp-user"
EMAIL_SMTP_PASS="your-smtp-password"

Generate a secure secret (note: bun run setup auto-generates this for you):

openssl rand -base64 32

Never commit your .env file to version control. The SECRET_KEY should be a strong, unique value in production.

What's Next?

Configure for Production

For production deployments, you'll need to:

  1. Set up a proper domain with HTTPS
  2. Configure email delivery (SMTP or Resend)
  3. Set a strong SECRET_KEY
  4. Use a managed PostgreSQL database

See the Docker Deployment Guide for complete instructions.

Explore the Platform

  • Create a board - Go to Admin → Settings → Boards
  • Invite your team - Go to Admin → Settings → Team
  • Customize branding - Go to Admin → Settings → Branding
  • Connect Slack - Go to Admin → Settings → Integrations

Import Existing Feedback

Migrating from another platform? Quackback supports CSV import:

  1. Go to Admin → Settings → Boards
  2. Select a board
  3. Click "Import from CSV"

See Import & Export for format details.

Troubleshooting

Port 3000 already in use

# Find and kill the process
lsof -i :3000
kill -9 <PID>

Database connection failed

Ensure PostgreSQL is running:

docker compose ps
# Should show postgres container as "healthy"

If the database container shows as "unhealthy", try running docker compose down -v to remove volumes and then docker compose up -d to start fresh.

Emails not sending

In development, emails are printed to the console. For production, configure SMTP or Resend in your .env file. See Environment Variables for details.

Getting Help