QuackbackQuackback
Navigation

Quick Start

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

Prerequisites

  • Bun (v1.4.0+) 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 your workspace, pick what you want to start with (feedback, support, or a help center), 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
 
# Email (optional: emails print to the 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, Amazon SES, 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

After onboarding, the launch checklist at Admin → Getting started walks you through the setup steps that matter for your goal. Common first stops:

  • Create a board - Go to Admin → Settings → Boards
  • Invite your team - Go to Admin → Settings → Members & Teams
  • 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 → Imports & exports
  2. Download the CSV template and fill it in
  3. Upload it, review the preview, and commit

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