Skip to content

quick-start.mdx

Latest commit

 

History

History
135 lines (93 loc) · 3.5 KB

quick-start.mdx

File metadata and controls

135 lines (93 loc) · 3.5 KB
Raw
title Quick Start
description Get Quackback running in under 5 minutes with Docker.
icon rocket

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](/reference/environment-variables) for details.

Getting Help