Skip to main content

Getting Started

QA Hub is available as a cloud-hosted service or a self-hosted Docker deployment.

Sign up at qahub.cloud → Create an account. Your workspace is created immediately; a QA Hub administrator approves it before you gain full access (usually within minutes on the cloud plan).

Self-hosted with Docker Compose​

Prerequisites​

  • Docker Engine 24+ and Docker Compose v2+
  • 1 GB RAM minimum (2 GB recommended)
  • A domain name if you plan to expose it publicly

1. Clone the repository​

git clone https://github.com/your-org/qa-hub.git
cd qa-hub

2. Configure environment variables​

cp .env.example .env

Open .env and set the two required variables:

# PostgreSQL connection — the Docker Compose default below works out of the box
DATABASE_URL=postgresql://qahub_user:qahub_password@localhost:5432/qa_hub?schema=public

# Encryption key for AI API keys stored in the database — must be at least 32 characters
APP_SECRET=replace-this-with-a-long-random-string-at-least-32-chars

Optional variables:

# Public URL — used in password-reset emails and OAuth callbacks
NEXT_PUBLIC_APP_URL=https://qa.your-company.com

# SMTP — if unset, email flows degrade gracefully (no emails are sent)
SMTP_HOST=smtp.example.com
SMTP_PORT=587
SMTP_USER=no-reply@example.com
SMTP_PASS=your-smtp-password
SMTP_FROM="QA Hub <no-reply@example.com>"

3. Start the stack​

docker-compose up -d

This starts PostgreSQL and the QA Hub application. The database schema is applied automatically on first boot — no manual migration step needed.

4. Open the app​

Navigate to http://localhost:3000. On first run, the registration page appears.

First login​

  1. Go to Register and create your account with name, email, and password.
  2. Your account starts as Pending. A SUPER_ADMIN must approve it before you can log in.
  3. Once approved, log in — you land on the main dashboard.
Approving your own account on a fresh install

On a brand-new self-hosted installation there are no SUPER_ADMINs yet. Connect directly to the database and update your user's tenant status:

UPDATE "Tenant" SET status = 'ACTIVE' WHERE id = '<your-tenant-id>';

After that, log in normally. Your account now has the QA_MANAGER role and can invite team members.

What's next​