PocketBase Setup

Run CrowdCAD on your own computer and share it with your team over your local network. No cloud account is needed and your data never leaves the machine. This guide assumes no programming or terminal experience and walks through every step on a Mac or a Windows PC.

Firebase setupGetting StartedSelf-hostingPrivacy
I'm using:
Steps below change to match your computer.

Before you start

By the end of this guide, CrowdCAD will be running on this computer. Anyone on the same Wi-Fi or wired network can open it in a web browser to dispatch together. Plan for about 45 to 90 minutes, most of it waiting for downloads.

You will need:

  • A Mac running one of the three most recent versions of macOSA Windows 10 or Windows 11 PC (64-bit) where you can install programs, with at least 10 GB of free disk space
  • An internet connection for the setup steps (the finished system works on a local network alone)
  • An email address and a password you will use as the CrowdCAD administrator

You will install four free programs: Git (downloads CrowdCAD), Node.js (runs setup scripts), Docker Desktop (runs CrowdCAD and its database) and, if you do not have one, a GitHub account.

Terminal basics

The terminal is a window where you type instructions (called commands) instead of clicking buttons. This guide gives you every command. You never need to write your own.

To open Terminal: press ⌘+Space, type Terminal and press Return. A window opens with a line ending in %. That line is the prompt, and it means Terminal is ready for a command.

To open PowerShell: press the Windows key, type PowerShell and press Enter. A window opens with a line like PS C:\Users\you>. That line is the prompt, and it means PowerShell is ready for a command. Open it normally. You do not need "Run as administrator".

  • Running a command: click Copy on a command box in this guide, click inside your terminal window, paste with ⌘+VCtrl+V and press ReturnEnter. The %PS> at the start of each line in the boxes stands for the prompt. The Copy button leaves it out.
  • Wait for the prompt. Some commands finish instantly and some take several minutes. When the prompt comes back, the command is done and you can run the next one.
  • Replace placeholders. Words in capitals such as YOUR_USERNAME, and example values such as you@example.com, are placeholders. After pasting, use the arrow keys to move to them and type your own value before pressing ReturnEnter.
  • Stopping a command: press Ctrl+C (Control, also on a Mac).
  • Warnings are normal. Lines with warn or WARNING can usually be ignored. If a command ends with an error, check Troubleshooting at the bottom of this page.
  • After installing a program, close the terminal window and open a new one so it can find the program.

Part 1: Install the tools

Step 1: Install Git

Git downloads CrowdCAD's code and later pulls in updates. You only install it once.

Run this in Terminal:

Terminal
git --version

If a version number such as git version 2.39.5 appears, Git is already installed. Go to the next step.

If a window says the command line developer tools are required, click Install, then Agree, and wait for it to finish (about 5 to 15 minutes). Then run git --version again to confirm.

Run this in PowerShell:

Windows PowerShell
winget install -e --id Git.Git

The first time you use winget it asks you to accept its terms. Type Y and press Enter. If Windows asks whether to allow the installer to make changes, click Yes.

When it finishes, close PowerShell, open a new PowerShell window and check the install:

Windows PowerShell
git --version
git version 2.51.0.windows.1

Step 2: Install Node.js

Node.js runs CrowdCAD's setup scripts. It includes npm, which downloads the packages CrowdCAD needs.

  1. Go to nodejs.org/en/download.
  2. Download the macOS Installer (.pkg) for the version marked LTS.
  3. Open the downloaded file and click through the installer with the default options.
  4. Close Terminal and open a new Terminal window.

Run this in PowerShell and click Yes if Windows asks for permission:

Windows PowerShell
winget install -e --id OpenJS.NodeJS.LTS

Close PowerShell and open a new window. Next, allow PowerShell to run the small scripts that come with Node.js. Without this, commands such as npm stop with "running scripts is disabled on this system". This setting only affects your own Windows account.

Windows PowerShell
Set-ExecutionPolicy -Scope CurrentUser -ExecutionPolicy RemoteSigned

If it asks Do you want to change the execution policy?, type Y and press Enter.

Check that Node.js and npm work:

Terminal
node -v
npm -v
v22.20.0
10.9.3
Windows PowerShell
node -v
npm -v
v22.20.0
10.9.3
Any Node.js version of 20 or higher works.

Step 3: Install Docker Desktop

Docker runs CrowdCAD and its PocketBase database in self-contained packages called containers, so you don't have to set up a web server yourself.

  1. Check which chip your Mac has: open Apple menuAbout This Mac. If it lists Chip: Apple M… you have Apple silicon. If it lists Processor: Intel, you have an Intel Mac.
  2. Go to docker.com/products/docker-desktop, open Download Docker Desktop and pick the Mac version that matches your chip.
  3. Open the downloaded file and drag the Docker icon into the Applications folder.
  4. Open Docker from Applications. Accept the terms and choose the recommended settings. Signing in to a Docker account is optional, so you can click Skip.

Run this in PowerShell and click Yes if Windows asks for permission:

Windows PowerShell
winget install -e --id Docker.DockerDesktop
The download is large and can take 5 to 15 minutes.
  1. Restart your computer when it finishes. Docker needs a Windows feature called WSL that only turns on after a restart.
  2. Open Docker Desktop from the Start menu. Accept the terms and choose the recommended settings. Signing in to a Docker account is optional, so you can click Skip.
  3. If Docker says WSL needs to be installed or updated, follow its prompt, or run wsl --update in PowerShell and restart again.

Wait until Docker Desktop says the engine is running (bottom left of its window), then check it from the terminal:

Terminal
docker --version
Docker version 28.4.0, build d8eb465
Windows PowerShell
docker --version
Docker version 28.4.0, build d8eb465

Step 4: Create a free GitHub account

CrowdCAD's code is hosted on GitHub. You need a free account to make your own copy. If you already have one, sign in and skip this step.

Go to github.com/signup and follow the prompts. Remember your username. You will use it in a later step.

Part 2: Get your own copy of CrowdCAD

Step 5: Make your own copy (fork) on GitHub

A fork is your own copy of CrowdCAD on GitHub. It belongs to you, it can hold your organization's changes, and it stays connected to the original so you can pull in new releases.

  1. Open github.com/crowdcad/crowdcad while signed in to GitHub.
  2. Click Fork near the top right of the page.
  3. Leave the owner as your username and the name as crowdcad, keep Copy the main branch only checked and click Create fork.

GitHub opens your fork at github.com/YOUR_USERNAME/crowdcad. From here on, the original crowdcad/crowdcad is called upstream: it is where new CrowdCAD releases come from.

Step 6: Download your fork to this computer

First move the terminal to your home folder. cd means "change directory", and ~ is a shortcut for your home folder.

Terminal
cd ~
Windows PowerShell
cd ~

Now download (clone) your fork. Paste the command, replace YOUR_USERNAME with your GitHub username and press ReturnEnter:

Terminal
git clone https://github.com/YOUR_USERNAME/crowdcad.git
Cloning into 'crowdcad'...
Resolving deltas: 100%, done.
Windows PowerShell
git clone https://github.com/YOUR_USERNAME/crowdcad.git
Cloning into 'crowdcad'...
Resolving deltas: 100%, done.

Move into the new folder. Every remaining command in this guide runs from inside it.

Terminal
cd crowdcad
Windows PowerShell
cd crowdcad

Step 7: Connect your copy to the original (upstream)

Your download already knows about your fork, under the name origin. This command also connects it to the original CrowdCAD, under the name upstream, so you can download future updates with one command.

Terminal
git remote add upstream https://github.com/crowdcad/crowdcad.git
Windows PowerShell
git remote add upstream https://github.com/crowdcad/crowdcad.git

Check both connections:

Terminal
git remote -v
origin    https://github.com/YOUR_USERNAME/crowdcad.git (fetch)
origin    https://github.com/YOUR_USERNAME/crowdcad.git (push)
upstream  https://github.com/crowdcad/crowdcad.git (fetch)
upstream  https://github.com/crowdcad/crowdcad.git (push)
Windows PowerShell
git remote -v
origin    https://github.com/YOUR_USERNAME/crowdcad.git (fetch)
origin    https://github.com/YOUR_USERNAME/crowdcad.git (push)
upstream  https://github.com/crowdcad/crowdcad.git (fetch)
upstream  https://github.com/crowdcad/crowdcad.git (push)

Part 3: Configure CrowdCAD

Step 8: Create your settings file

CrowdCAD reads its settings from a file named .env.local. Make it by copying the example file that came with the download:

Terminal
cp .env.example .env.local
Windows PowerShell
Copy-Item .env.example .env.local

Then open it in a text editor:

Terminal
open -e .env.local
This opens the file in TextEdit.
Windows PowerShell
notepad .env.local
This opens the file in Notepad.

Step 9: Fill in your settings

The file has a section for Firebase and a section for PocketBase. Leave the Firebase lines as they are (they are ignored). Find each of these lines and change it so the file contains:

.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=you@example.com
PB_ADMIN_PASSWORD=ChooseAStrongPassword123
  • NEXT_PUBLIC_BACKEND: change firebase to pocketbase. This is usually the first line.
  • NEXT_PUBLIC_POCKETBASE_URL and PB_URL: leave these as they are for now. Part 5 changes the first one to share CrowdCAD with other devices.
  • PB_ADMIN_EMAIL: your email address. This becomes the login for PocketBase's database admin screen.
  • PB_ADMIN_PASSWORD: a new password of at least 10 characters. Use only letters and numbers. Symbols such as $ and #, and spaces, confuse Docker.

Save with ⌘+SCtrl+S and close the editor. Write the email and password down somewhere safe. You will type them again in step 12.

Step 10: Download CrowdCAD's packages

This downloads the code libraries CrowdCAD's setup scripts use. It saves them in a node_modules folder inside crowdcad.

Terminal
npm install
added 1024 packages in 1m
Windows PowerShell
npm install
added 1024 packages in 1m
Takes 1 to 5 minutes. Lines starting with 'npm warn' are normal.

Part 4: Start CrowdCAD

Step 11: Build and start CrowdCAD

Make sure Docker Desktop is open and running, then run this command. It builds CrowdCAD and starts two containers: the CrowdCAD app and its PocketBase database.

Terminal
docker compose --env-file .env.local up -d --build
 ✔ Container pocketbase      Started
 ✔ Container crowdcad-web-1  Started
Windows PowerShell
docker compose --env-file .env.local up -d --build
 ✔ Container pocketbase      Started
 ✔ Container crowdcad-web-1  Started
The first build takes 5 to 15 minutes. Later starts take seconds.

Step 12: Create the database admin account

This creates the account that manages PocketBase itself. Paste the command, then replace you@example.com and ChooseAStrongPassword123 with the exact PB_ADMIN_EMAIL and PB_ADMIN_PASSWORD from step 9. Keep the single quotes around the password.

Terminal
docker exec pocketbase /pb/pocketbase superuser upsert you@example.com 'ChooseAStrongPassword123'
Successfully saved superuser "you@example.com"!
Windows PowerShell
docker exec pocketbase /pb/pocketbase superuser upsert you@example.com 'ChooseAStrongPassword123'
Successfully saved superuser "you@example.com"!

You only do this once. The account is saved with the rest of your data.

Step 13: Create CrowdCAD's database tables

This script connects to PocketBase with the admin account and creates the tables CrowdCAD stores venues, events and logs in, along with rules about who can change what.

Terminal
node scripts/setup-pocketbase.js
Connecting to PocketBase at http://127.0.0.1:8090 ...
Authenticated. Setting up collections...

  [create] venues
  [create] events
  ...

Done. CrowdCAD collections are ready, with owner/admin-scoped access rules applied automatically.
Windows PowerShell
node scripts/setup-pocketbase.js
Connecting to PocketBase at http://127.0.0.1:8090 ...
Authenticated. Setting up collections...

  [create] venues
  [create] events
  ...

Done. CrowdCAD collections are ready, with owner/admin-scoped access rules applied automatically.

It ends with a reminder about password-reset emails. That is optional and covered in Part 6, so you can ignore it for now.

Step 14: Open CrowdCAD and create your account

  1. Open a web browser (Chrome, Edge, Safari or Firefox) and go to http://localhost:3000.
  2. Click Sign In, then Sign Up under "Don't have an account?".
  3. Enter your email and a password of at least 8 characters, and create the account. This is your everyday CrowdCAD login. It can use the same email as step 9.

Step 15: Make yourself a CrowdCAD admin

Admins can manage the certification list and give admin access to others from ProfileAdmin. The first admin has to be set from the terminal. Replace you@example.com with the email you signed up with in step 14:

Terminal
node scripts/setAdminPocketbase.js you@example.com
Granted admin access for you@example.com (id: a1b2c3d4e5f6g7h)
Windows PowerShell
node scripts/setAdminPocketbase.js you@example.com
Granted admin access for you@example.com (id: a1b2c3d4e5f6g7h)

Sign out and back in to see the Admin section in your profile. From now on you can make other people admins from ProfileAdminManage Admins.

Part 5: Share CrowdCAD with your team

So far CrowdCAD only works on this computer. These steps let phones, tablets and laptops on the same network open it too. Every device must be on the same Wi-Fi or wired network as this computer.

Step 16: Find this computer's IP address

Other devices reach this computer through its IP address on your network, which looks like 192.168.1.20.

Run this in Terminal. It prints the Wi-Fi address:

Terminal
ipconfig getifaddr en0
192.168.1.20

If nothing prints (for example on a wired connection), open Apple menuSystem SettingsNetwork, click the connection marked Connected and click Details. The address is listed as IP address.

Run this in PowerShell:

Windows PowerShell
ipconfig
Wireless LAN adapter Wi-Fi:
   IPv4 Address. . . . . . . . . . . : 192.168.1.20

Find the IPv4 Address under the adapter you are using (Wi-Fi or Ethernet). Ignore adapters named vEthernet or WSL.

Step 17: Point CrowdCAD at that address

Open your settings file again:

Terminal
open -e .env.local
Windows PowerShell
notepad .env.local

Change the NEXT_PUBLIC_POCKETBASE_URL line to use your IP address in place of 127.0.0.1. Keep http:// at the start and :8090 at the end. Leave PB_URL alone.

.env.local
NEXT_PUBLIC_POCKETBASE_URL=http://192.168.1.20:8090

Save with ⌘+SCtrl+S, close the editor and rebuild CrowdCAD so it picks up the change:

Terminal
docker compose --env-file .env.local up -d --build
Windows PowerShell
docker compose --env-file .env.local up -d --build
Takes a few minutes. Your data is kept.

Step 18: Allow connections through the firewall

If macOS asks whether Docker should accept incoming network connections, click Allow. If you use a third-party firewall, allow ports 3000 and 8090.

  1. If a Windows Security window says the firewall blocked Docker, check Private networks and click Allow.
  2. Make sure Windows treats your network as private: open SettingsNetwork & internetWi-Fi (or Ethernet), click your network and set Network profile type to Private network.

Step 19: Share the link

On another device on the same network, open a browser and go to http:// followed by your IP address and :3000, for example:

Link to share
http://192.168.1.20:3000

Part 6: Everyday use

Step 20: Stopping and starting CrowdCAD

CrowdCAD keeps running as long as Docker Desktop is open, and starts again on its own when Docker Desktop opens. To stop it on purpose, go to your CrowdCAD folder and run:

Terminal
cd ~/crowdcad
docker compose down
Windows PowerShell
cd ~/crowdcad
docker compose down

To start it again later (with Docker Desktop open):

Terminal
cd ~/crowdcad
docker compose --env-file .env.local up -d
Windows PowerShell
cd ~/crowdcad
docker compose --env-file .env.local up -d

Your venues, events, accounts and logs are kept in the .pb-data folder inside crowdcad and survive stops, restarts and updates.

Step 21: Back up your data

Everything CrowdCAD stores lives in the .pb-data folder. Stop CrowdCAD first so nothing is half-written, copy the folder, then start it again:

Terminal
cd ~/crowdcad
docker compose down
cp -R .pb-data ~/crowdcad-backup-$(date +%Y-%m-%d)
docker compose --env-file .env.local up -d
Windows PowerShell
cd ~/crowdcad
docker compose down
Copy-Item -Recurse .pb-data "$HOME\crowdcad-backup-$(Get-Date -Format yyyy-MM-dd)"
docker compose --env-file .env.local up -d

This makes a dated copy in your home folder. Store backups somewhere safe and private, since they contain everything entered during events.

Step 22: Optional: turn on password-reset emails

"Forgot password?" needs an email account for PocketBase to send from. Your organization's IT contact or email provider can give you SMTP settings (server, port, username and password).

  1. Open http://localhost:8090/_/ and sign in with the admin email and password from step 9.
  2. Go to SettingsMail settings, turn on Use SMTP mail server, enter your SMTP settings and save.
  3. Go to CollectionsusersOptions (gear icon)Email templatesReset password and change the link in the email body to http://192.168.1.20:3000/reset-password?token={TOKEN}, using your own IP address. Save.

Part 7: Updating CrowdCAD

New versions of CrowdCAD come out regularly. Updating downloads them from upstream (the original repository you connected in step 7) and then rebuilds your copy. Your data and settings are kept. Update between events, since CrowdCAD is offline for a few minutes while it rebuilds.

Step 23: Download the latest version from upstream

New CrowdCAD releases are published to the original repository (upstream). Open a terminal, go to your CrowdCAD folder and pull them in:

Terminal
cd ~/crowdcad
git pull --no-rebase --no-edit upstream main
From https://github.com/crowdcad/crowdcad
Updating 8747b40..4a03ac8
Fast-forward
Windows PowerShell
cd ~/crowdcad
git pull --no-rebase --no-edit upstream main
From https://github.com/crowdcad/crowdcad
Updating 8747b40..4a03ac8
Fast-forward

This downloads the newest code from upstream and merges it into your copy. Your .env.local settings and your data are left alone. If it prints Already up to date., there is nothing new.

See what changed in each release on the changelog.

Step 24: Rebuild and restart with the new version

Run these three commands one at a time, waiting for the prompt to return after each:

Terminal
npm install
Windows PowerShell
npm install
Downloads any new packages the update needs.
Terminal
docker compose --env-file .env.local up -d --build
Windows PowerShell
docker compose --env-file .env.local up -d --build
Rebuilds and restarts CrowdCAD. Takes a few minutes.
Terminal
node scripts/setup-pocketbase.js
Windows PowerShell
node scripts/setup-pocketbase.js
Adds any new tables, fields or rules the update introduced. Safe to run every time.

Troubleshooting

Click a problem to see how to fix it.

"Cannot connect to the Docker daemon" or "error during connect"

Docker Desktop is not running. Open it, wait until it says the engine is running, then run the command again.

"Bind for 0.0.0.0:3000 failed: port is already allocated" (or 8090)

Another program, often a second copy of CrowdCAD, is already using that port. In Docker Desktop's Containers tab, stop any other CrowdCAD or PocketBase containers, then run step 11 again.

"The container name /pocketbase is already in use"

An older CrowdCAD setup on this computer already has a container named pocketbase. In Docker Desktop's Containers tab, stop and delete that old container (its data lives in its own folder and is not deleted), then run step 11 again.

"PB_ADMIN_EMAIL and PB_ADMIN_PASSWORD must be set"
  • Run npm install (step 10). The scripts need it to read your settings file.
  • Make sure you are in the CrowdCAD folder: run cd ~/crowdcad and try again.
  • Open .env.local and check both lines are filled in and the file is saved.
The setup script says it failed to authenticate

The email or password in step 12 did not match .env.local. Run step 12 again with exactly the same values, then run step 13.

Sign-up says "Failed to create record"

The database tables have not been created yet. Run step 13, then try signing up again.

Sign-up rejects my password

CrowdCAD passwords must be at least 8 characters long.

Other devices can't open the link
  • Check the other device is on the same Wi-Fi or wired network (not a guest network or mobile data).
  • Type the address exactly, starting with http:// and ending in :3000.
  • Check the firewall settings in step 18.
  • Run step 16 again. If the IP address changed, repeat step 17 with the new one.
Other devices load the page but can't sign in

CrowdCAD is still pointed at 127.0.0.1. Repeat step 17, making sure you saved .env.local before running the rebuild command.

"command not found" or "is not recognized as the name of a cmdlet"

The terminal cannot find the program. Close the terminal, open a new one and try again. If it still fails, repeat the install step for that program (Git, Node.js or Docker).

"running scripts is disabled on this system" (Windows)

PowerShell is blocking npm's helper scripts. Run this once, answer Y, then retry your command:

Windows PowerShell
Set-ExecutionPolicy -Scope CurrentUser -ExecutionPolicy RemoteSigned
"not a git repository" or "Could not read package.json"

The terminal is not inside your CrowdCAD folder. Move into it and retry:

Terminal
cd ~/crowdcad
Windows PowerShell
cd ~/crowdcad
Updating says "Please tell me who you are"

Git needs a name and email to record the update on your computer. Set them once (use your own details), then run the update command again:

Terminal
git config --global user.name "Your Name"
git config --global user.email "you@example.com"
Windows PowerShell
git config --global user.name "Your Name"
git config --global user.email "you@example.com"
Updating says "Your local changes would be overwritten"

A file that came with CrowdCAD was edited on this computer. If you did not mean to change it, this command sets your edits aside and the update can run. Your .env.local is not affected.

Terminal
git stash
git pull --no-rebase --no-edit upstream main
Windows PowerShell
git stash
git pull --no-rebase --no-edit upstream main

If you meant to change it, ask for help in the CrowdCAD Discord before continuing.

Still stuck? Ask in the CrowdCAD Discord or email support@crowdcad.org. Include the step number and the exact message you see. Never share your .env.local or passwords.

Next steps