Copy page

Getting Started

Quick Start

Prerequisites

Before you begin, make sure you have the following installed:

Tool	Minimum version	Check
Node.js®	20+	node --version
pnpm	latest	pnpm --version
Docker®	latest	docker --version

You also need access to the Primebrick GitHub™ repositories.

1. Clone the repositories

Primebrick is split into several repos. For a full local environment you need at minimum the backend and frontend:

Code
git clone https://github.com/michaelsogos/primebrick-v3-backend.git
git clone https://github.com/michaelsogos/primebrick-v3-frontend.git

If you plan to develop microservices or shared libraries, also clone:

Code
git clone https://github.com/michaelsogos/primebrick-v3-microservices.git   # microservices
git clone https://github.com/michaelsogos/primebrick-v3-dal.git  # DAL library
git clone https://github.com/michaelsogos/primebrick-v3-sdk.git  # SDK

2. Start infrastructure with Docker®

The backend repo includes a docker-compose.yml that spins up PostgreSQL®, Casdoor™, and NATS™:

Code
cd primebrick-v3-backend
docker compose up -d

This starts:

• PostgreSQL® — primary database
• Casdoor™ — identity provider (OIDC / OAuth2)
• NATS™ — messaging bus for microservice communication

3. Install dependencies

Install dependencies for the backend and frontend:

Code
cd primebrick-v3-backend
pnpm install

cd ../primebrick-v3-frontend
pnpm install

4. Set up Casdoor™

Primebrick includes a setup script that configures Casdoor™ with the default application, organizations, and roles:

Code
cd primebrick-v3-backend
pnpm run setup:casdoor

This provisions the OIDC client and seed users needed for local development.

5. Run database migrations

Apply the database schema migrations:

Code
pnpm run db:migrate

6. Start the development servers

Start the backend and frontend in separate terminals:

Code
# Terminal 1 — backend
cd primebrick-v3-backend
pnpm run dev

Code
# Terminal 2 — frontend
cd primebrick-v3-frontend
pnpm run dev

Where things run

Service	URL
Backend API	http://localhost:3001
Frontend (SvelteKit™)	http://localhost:5173
Casdoor™ console	http://localhost:8000
NATS™	nats://localhost:4222

Verify it works

1. Open http://localhost:5173 in your browser — you should see the Primebrick frontend.
2. Check the backend health at http://localhost:3001/api/v1/health.
3. View the aggregated OpenAPI spec at http://localhost:3001/api/v1/openapi/aggregated.json.

Troubleshooting

Docker containers won't start

Make sure ports 5432 (PostgreSQL®), 8000 (Casdoor™), and 4222 (NATS™) are not already in use. Stop any conflicting services or adjust the port mappings in docker-compose.yml.

Casdoor™ setup script fails

Ensure the Casdoor™ container is fully up before running pnpm run setup:casdoor. Check with docker compose ps and wait until the Casdoor™ service shows a healthy state.

Database migration errors

Confirm PostgreSQL® is running and the connection string in your .env file points to the Dockerized instance. Run pnpm run db:migrate again after fixing the connection.

Next steps

• Architecture — understand how the pieces fit together.
• API Overview — learn about the REST API.