Self-hosting quick start

Get a self-hosted Quackback instance running with Docker Compose in a few minutes, complete first-time setup, and prepare it for production.

Get a self-hosted Quackback instance running with Docker Compose in a few minutes. This is for the open-source edition; on Quackback Cloud you just sign up and skip all of this.

Prerequisites

Docker Engine 20.10+ with Docker Compose v2
About 1 GB of free RAM
For production: a domain or subdomain and a reverse proxy for HTTPS

You don't need to install PostgreSQL, Redis, or a storage server. The production Compose stack runs the app, PostgreSQL (with pgvector), and S3-compatible object storage (PGSTY Silo) for you.

Start Quackback

1. Clone the repository

git clone https://github.com/QuackbackIO/quackback.git
cd quackback

2. Create your environment file

cp .env.prod.example .env

Fill in every value in .env. At minimum set BASE_URL, SECRET_KEY, POSTGRES_PASSWORD, and MINIO_ROOT_PASSWORD. Generate secrets with:

openssl rand -base64 32

Don't wrap values in quotes and don't add inline # comments on a value line. Docker reads values literally.

3. Start the stack

docker compose -f docker-compose.prod.yml up -d

Migrations run automatically on the first start.

4. Open the app at http://localhost:3000 (or your BASE_URL behind a reverse proxy).

Warning: Always use docker-compose.prod.yml. The root docker-compose.yml is for local development only: it starts the datastores with insecure defaults and no app service.

First-time setup

1. Create your account. The setup wizard asks for your email and sends a sign-in code. If you haven't configured email yet, the code is printed in the app logs:

docker compose -f docker-compose.prod.yml logs app

2. Name your workspace and finish the wizard.

3. Follow the launch checklist at Admin > Getting started. It walks you through the setup steps that matter for your goal.

Common first stops:

Create a board: Admin > Settings > Boards
Invite your team: Admin > Settings > Members & Teams
Customize branding: Admin > Settings > Branding
Turn on modules such as the help center, support inbox, or status page: Admin > Settings > General
Connect Slack: Admin > Settings > Integrations

Get ready for production

Before you invite real users:

Put Quackback behind a reverse proxy with HTTPS, and set TRUSTED_PROXY_HOPS (or TRUSTED_CLIENT_IP_HEADER). See Set up a reverse proxy.
Configure email delivery with exactly one provider: SMTP, Amazon SES, or Resend. See Configure email delivery.
Keep your SECRET_KEY safe and unchanged. It signs sessions and encrypts stored credentials.
Pin QUACKBACK_TAG in .env to a release version instead of latest.
Set up regular backups of the database and object storage.

See Deploy with Docker for the full guide.

Import existing feedback

Moving from another tool or a spreadsheet? Go to Admin > Settings > Imports & exports, download the CSV template, fill it in, upload it, review the preview, and commit. See Import and export data.

Troubleshooting

Port 3000 already in use

Change the published port with APP_PORT in .env (the container always listens on 3000 internally):

APP_PORT=8080

The stack refuses to start

The production Compose file refuses to start until every required secret is set, and names the missing variable. Fill it in .env and run docker compose -f docker-compose.prod.yml up -d again.

Emails are not sending

With no email provider configured, emails are written to the app logs instead of being sent. Configure one provider as described in Configure email delivery.

Getting help

GitHub Issues: bug reports and feature requests
GitHub Discussions: questions and community support