PocketBase Setup

This guide covers PocketBase project setup with Docker, local environment configuration, collection provisioning, and password-reset email basics for teams self-hosting CrowdCAD on local or LAN infrastructure with no cloud account required.

Self-hosting Firebase setup Getting Started Privacy Contact

Prerequisites

Before setup, confirm Docker Desktop and a bash-compatible shell are available — Git Bash on Windows, Terminal on macOS/Linux. All docker and npm commands below are the same across platforms, with one Windows-specific exception called out in the superadmin step.

• Docker Desktop (Windows, macOS, or Linux)
• Git and repository access
• Node.js v18+ and npm (for the collection-setup script)
• A local editor and browser for testing

On Windows, Docker Desktop can be installed via winget. It relies on the WSL2 backend, so a system restart is typically required afterward before Docker Desktop can run.

Install Docker Desktop (Windows)

winget install -e --id Docker.DockerDesktop

Clone the repository and start PocketBase

Clone the repository, then build and start the Docker Compose stack, which runs both the Next.js app and a PocketBase instance with data persisted to .pb-data/. If you already have a Firebase-configured checkout of this repo, clone into a separate directory rather than reusing it — each checkout has its own .env.local and .pb-data/.

Clone and start

git clone https://github.com/evanqua/crowdcad.git
cd crowdcad
cp .env.example .env.local
# edit .env.local — see Local environment variables below
docker compose --env-file .env.local up -d --build

Local environment variables

Add the PocketBase config to .env.local. NEXT_PUBLIC_POCKETBASE_URL is read by the app at runtime; PB_URL, PB_ADMIN_EMAIL, and PB_ADMIN_PASSWORDare read only by the collection-setup script below, not by the app itself.

.env.local

NEXT_PUBLIC_BACKEND=pocketbase
NEXT_PUBLIC_POCKETBASE_URL=http://127.0.0.1:8090
PB_URL=http://127.0.0.1:8090
PB_ADMIN_EMAIL=admin@example.com
PB_ADMIN_PASSWORD=YourPassword!

Create the superadmin and required collections

First time only — the superadmin account and collections are stored in .pb-data/ and persist across restarts, so this step is skippable on subsequent runs.

Create superadmin

docker exec pocketbase /pb/pocketbase superuser upsert admin@example.com YourPassword!

On Windows with Git Bash specifically, Git Bash rewrites the leading /pb/... argument as if it were a Windows path, which breaks this command. Prefix it with MSYS_NO_PATHCONV=1:

Create superadmin (Windows / Git Bash)

MSYS_NO_PATHCONV=1 docker exec pocketbase /pb/pocketbase superuser upsert admin@example.com YourPassword!

Then create the collections CrowdCAD needs (venues, events, dispatchLogs, _storage, settings, and an isAdmin field on the built-in users collection). This script is idempotent — safe to run again any time. Skipping it causes sign-up to fail with a "Failed to create record" error, since the users auth collection has no matching app schema yet.

Create collections

node scripts/setup-pocketbase.js

Run the app, stop, and restart

Once the stack is up and collections are created, the app is available at http://localhost:3000 and the PocketBase admin UI at http://localhost:8090/_/.

Stop and restart

docker compose down
# data persists in .pb-data/, so restarting does not require
# repeating the superadmin or collection-setup steps
docker compose --env-file .env.local up -d

Forgot-password emails and SMTP configuration

CrowdCAD's PocketBase auth adapter calls PocketBase's built-in password-reset APIs directly — there is no custom reset-password backend logic layered on top. The app does add its own /reset-password page that reads the reset token from the email link and submits it back to PocketBase, but two things must be configured in the PocketBase admin UI before "forgot password" actually works for your users, and neither is set automatically:

• Point the reset email at this app. By default, PocketBase's reset-password email links to its own admin UI. Under Collections > users > Options > Email templates > Reset password, change the action URL to {APP_URL}/reset-password?token={TOKEN}.
• Configure outbound SMTP. PocketBase does not send email out of the box. Under Settings > Mail settings, enter your organization's SMTP host, port, and credentials. This repo does not expose SMTP settings as environment variables — they're configured entirely through the admin UI and persist in .pb-data/ across restarts.

The collection-setup script also prints a reminder of both steps after it finishes.

Notes and support

Keep .env.local and superadmin credentials outside version control. PocketBase's default auth collection rejects passwords shorter than 8 characters — this is not currently enforced client-side, so a short password fails at the PocketBase API rather than showing a hint before submit.

For broader deployment, governance, and operational responsibility guidance, continue with the Self-hosting documentation.

For setup assistance, contact support@crowdcad.org.