Getting Started

Prerequisites

Never installed Docker or Git before? See the Prerequisites guide for step-by-step instructions for Windows, macOS, and Linux.

Quick Start

1. Clone the Repository

git clone https://github.com/Questbee/community.git
cd community

2. Configure Environment

cp .env.example .env

Edit .env — the minimum required values:

DB_PASSWORD=a_strong_password
SECRET_KEY=run_python3_to_generate_this
ADMIN_EMAIL=admin@yourorg.com
ADMIN_PASSWORD=ChangeMe123!
ALLOWED_ORIGINS=http://localhost:3000
NEXT_PUBLIC_API_URL=http://localhost:8000/api/v1

Generate a proper SECRET_KEY:

python3 -c "import secrets; print(secrets.token_hex(32))"

Note on email: use a real-looking domain like yourorg.com. Pydantic rejects reserved TLDs like .local.

3. Start the Stack

docker compose up --build
ServiceURLPurpose
Web dashboardhttp://localhost:3000Next.js admin interface
APIhttp://localhost:8000FastAPI backend
API docs (Swagger)http://localhost:8000/docsInteractive endpoint explorer

4. First Login

  1. Open http://localhost:3000
  2. Log in with ADMIN_EMAIL and ADMIN_PASSWORD from your .env
  3. You will be redirected to a Change Password screen — this is mandatory on first login
  4. After changing your password, you land on the dashboard

First Steps in the Dashboard

Create a Project

Forms are organized inside Projects. A project maps to one program or initiative.

  1. Go to Dashboard → click New Project
  2. Enter a name (e.g. "2026 Household Survey")
  3. Click Create

Create and Build a Form

  1. Inside the project, click New Form
  2. Give it a name and optional description
  3. Click Create — you land in the form builder
  4. Add fields from the left panel
  5. Configure each field: label, required, hint, conditional logic
  6. Click Publish when the form is ready

Available field types:

CategoryFields
TextShort text, Long text, Number, Email, Phone
Date / TimeDate, Time, Date + Time
ChoiceSingle choice, Multiple choice, Single choice with write-in
LocationGPS point (geopoint), GPS trace (geotrace)
MediaPhoto, Audio recording, Signature, File attachment
ScanBarcode / QR code
LogicCalculated value, Hidden field
LayoutNote, Divider, Field group, Repeating group

Versioning: Once published, a form version is locked. Any edit creates a new draft. Existing submissions always reference the version they were collected against.

Pairing the Mobile App

The mobile app connects to your server via a QR code generated in the dashboard. The QR code embeds both the server URL and a short-lived pairing token — no separate login is required on the device.

Generate a Pairing Code

  1. In the dashboard go to Settings
  2. Under Mobile Pairing, click Generate QR Code

Connect the App

  1. Open the Questbee app on your device
  2. Tap Scan QR Code
  3. Point the camera at the QR code shown in the dashboard

The app connects, stores your credentials securely, and downloads your assigned forms automatically. You are ready to collect data.

Collecting Data

Via Mobile App (Offline-First)

  1. Open the app → select a form
  2. Fill in all fields — no internet required
  3. Tap Submit — data is saved locally if offline
  4. When the device reconnects, pending submissions upload automatically

Via Web (Online Only)

Web submission from the dashboard is available for managers testing forms or entering data manually.

Viewing Submissions

  1. Go to Submissions in the sidebar
  2. Filter by form using the dropdown
  3. Click any row to see full submission details, including media files

Exporting Data

Click Export on the Submissions page to download your data:

FormatContents
CSVOne row per submission; repeat groups in separate files
GeoJSONGPS points, traces, and routes as a FeatureCollection
GPXRoute/trace fields as a GPX track (opens in QGIS, OsmAnd, etc.)
Media filesZIP archive of all uploaded files with an index CSV
Full packageZIP with all of the above combined

Environment Variables

VariableRequiredDescription
DB_PASSWORDYesPostgreSQL password for the questbee user
SECRET_KEYYesJWT signing secret (32+ random hex chars)
ADMIN_EMAILYesEmail for the auto-created admin account
ADMIN_PASSWORDYesInitial password (must be changed on first login)
ALLOWED_ORIGINSYesComma-separated CORS origins for the dashboard
NEXT_PUBLIC_API_URLYesAPI URL as seen from the browser
MAX_UPLOAD_MBNoMax media file upload size in MB (default: 20)
SYNC_BATCH_SIZENoMax submissions per bulk sync request (default: 100)

Troubleshooting

Dashboard not loading

docker compose logs web

API errors

docker compose logs api

Database issues

docker compose ps           # check all containers are Up
docker compose restart db   # restart database if needed

Mobile app not syncing

  • Confirm the server URL is reachable from the device network
  • Check: docker compose logs api for 4xx/5xx errors

Full reset (delete all data)

docker compose down -v

Next Steps