ℹThis page lives in the Users section and is also referenced from Deployment. If you arrived from there, your sidebar has switched to Users.

Installation

This guide walks through setting up a local CDT development environment. Plan for 15–25 minutes on a fresh machine.

Prerequisites

Tool	Version	Purpose
Node.js	18.0 or newer (LTS recommended)	Runs the Next.js application
Yarn or npm	latest	Package manager
Git	any recent version	Cloning the repository
Docker (optional)	24.0 or newer	Runs PostgreSQL, MinIO, and Martin locally

Verify your installations:

node --version
yarn --version  # or: npm --version
git --version

If node --version reports below 18, upgrade before continuing — older versions are not supported and will fail at install time.

1. Clone the repository

git clone https://github.com/CollabDigitalTwins/core.git
cd core

2. Install dependencies

Yarn is recommended because the lockfile is yarn.lock:

yarn install

Or with npm:

npm install

3. Configure environment variables

Copy the example file:

cp .env.example .env

Open .env and fill in values. For a minimal local setup, the required variables are:

• DATABASE_URL — PostgreSQL connection string
• AUTH_SECRET — any random 32+ character string
• AUTH_URL — http://localhost:3000
• S3_ACCESS_KEY and S3_ACCESS_SECRET — MinIO credentials
• MINIO_ENDPOINT — localhost for local MinIO

All other keys are optional and only needed if you want to test the matching feature (Google OAuth, Geocode Earth, reCAPTCHA, etc.). The full list with descriptions is in the Environment variables reference.

4. Start the database services

The simplest path is to run PostgreSQL and MinIO locally with Docker Compose:

docker compose up -d postgres minio

Apply Prisma migrations once the database is ready:

npx prisma migrate dev

If you have an existing PostgreSQL or MinIO instance you want to use instead, point DATABASE_URL and the MinIO variables at it and skip the Docker step.

5. Start the development server

yarn dev

Or with npm:

npm run dev

The application is available at http://localhost:3000.

Verify the installation

Open http://localhost:3000. You should see the CDT sign-in screen. Sign in with the credentials your administrator provided, then complete the Quickstart to confirm the full stack works end-to-end.

Troubleshooting common issues

Symptom	Likely cause	Fix
EADDRINUSE: address already in use :::3000	Another process is on port 3000	Stop the other process or run yarn dev -p 3001
Error: Cannot find module 'next' after install	Install was incomplete	Delete node_modules and yarn.lock (or package-lock.json), then reinstall
Prisma migrate fails with connect ECONNREFUSED	PostgreSQL is not running or DATABASE_URL is wrong	Confirm docker compose ps shows postgres healthy and that the URL host/port match
unsupported engine warning during install	Node.js version is older than 18	Upgrade Node.js — use nvm or download from nodejs.org
Sign-in returns 500 with AUTH_SECRET errors	AUTH_SECRET is missing or too short	Set it to at least 32 random characters in .env
Map renders blank	NEXT_PUBLIC_GEOCODE_EARTH_API_KEY or Martin URL is missing	Set the values in .env or accept reduced functionality for local dev

If your issue is not listed here, see the broader Troubleshooting page or open an issue on GitHub.