Local Development Setup
Step-by-step guide to running the Neostra platform locally for development.
Local Development Setup
This guide covers how to set up and run the full Neostra platform on your local machine for development. The platform consists of multiple services spanning Java/Gradle backends, Node.js frontends, and Python workers.
Prerequisites
Java 17+
Required for all Gradle-based backend services. Install via SDKMAN or your package manager.
Node.js 18+
Required for frontend applications and the cookie modal SDK. Includes npm.
Python 3.10+
Required for the data-discovery-scanner worker service.
Docker
Recommended for running MongoDB and PostgreSQL. Alternatively, install them natively.
Service Architecture
Step 1: Start Databases
Create a docker-compose.yml in your workspace root:
version: "3.8"
services:
mongodb:
image: mongo:6
ports:
- "27017:27017"
volumes:
- mongo-data:/data/db
environment:
MONGO_INITDB_DATABASE: dpdp
postgres:
image: postgres:14
ports:
- "5432:5432"
volumes:
- pg-data:/var/lib/postgresql/data
environment:
POSTGRES_USER: neostra
POSTGRES_PASSWORD: neostra_dev
POSTGRES_DB: neostra
volumes:
mongo-data:
pg-data:
docker compose up -d
# MongoDB
brew tap mongodb/brew
brew install mongodb-community@6.0
brew services start mongodb-community@6.0
# PostgreSQL
brew install postgresql@14
brew services start postgresql@14
createdb neostra
# MongoDB - follow official install guide for your distro
# https://www.mongodb.com/docs/manual/installation/
# PostgreSQL
sudo apt install postgresql-14
sudo systemctl start postgresql
sudo -u postgres createdb neostra
Step 2: Configure Environment Variables
Create a .env file or export the following variables in your shell. Each service reads its configuration from environment variables.
Never commit .env files or secrets to version control. Add .env to your .gitignore.
# MongoDB
export MONGODB_URI="mongodb://localhost:27017"
export MONGODB_DATABASE="dpdp"
# JWT Configuration
export JWT_SECRET="your-local-dev-jwt-secret-min-32-chars"
export JWT_EXPIRATION=10800000
export JWT_TEMP_EXPIRATION=1800000
# SendGrid (use test key or mock for local dev)
export SENDGRID_API_KEY="SG.test-key-for-local-dev"
# Google Cloud Storage (optional for local dev)
export GCS_PROJECT_ID="your-gcs-project"
export GCS_BUCKET_NAME="neostra-dev-uploads"
export GOOGLE_APPLICATION_CREDENTIALS="/path/to/service-account.json"
# CORS
export CORS_ORIGINS="http://localhost:5173,http://localhost:3000"
# PostgreSQL for CPMP
export CPMP_DB_URL="jdbc:postgresql://localhost:5432/neostra"
export CPMP_DB_USERNAME="neostra"
export CPMP_DB_PASSWORD="neostra_dev"
# CPMP API Service
export CPMP_API_PORT=9001
export CPMP_LOG_RECEIPT_PORT=9002
export CPMP_REPORTING_PORT=9003
export CPMP_CRAWLER_PORT=9004
# PostgreSQL for Discovery
export DISCOVERY_DB_URL="jdbc:postgresql://localhost:5432/neostra"
export DISCOVERY_DB_USERNAME="neostra"
export DISCOVERY_DB_PASSWORD="neostra_dev"
# Scanner Worker
export SCANNER_BROKER_URL="amqp://localhost:5672"
# neostra-ui
export VITE_CORE_BASE_URL="http://localhost:9000"
# astra-ui
export VITE_ASTRA_BASE_URL="http://localhost:9010"
Step 3: Run Migrations
The neostra-migrations service must be run once before starting the platform. It uses Mongock change units to seed MongoDB with initial data.
Migrations are idempotent. Running them multiple times will not duplicate data. Mongock tracks which change units have already been applied.
cd neostra-migrations
./gradlew bootRun
What Migrations Seed
Step 4: Start Backend Services
Start neostra-core (Port 9000)
The primary backend service. Must be started first as other services and the UI depend on it.
cd neostra-core
./gradlew bootRun
Verify it is running:
curl http://localhost:9000/api/v1/health
Start CPMP services
The Consent Platform Management services. Start each in a separate terminal.
# Terminal 1
cd cpmp-api-service
./gradlew bootRun
# Terminal 2
cd cpmp-log-receipt-service
./gradlew bootRun
# Terminal 3
cd cpmp-reporting-service
./gradlew bootRun
# Terminal 4
cd cpmp-crawler-service
./gradlew bootRun
Start Data Discovery (Port 8080)
cd data-discovery-boot
./gradlew bootRun
Start the Python scanner worker in a separate terminal:
cd data-discovery-scanner
pip install -r requirements.txt
python -m scanner.main
Start astra-core (Port 9010)
The admin control plane service.
cd astra-core
./gradlew bootRun
Step 5: Start Frontend Applications
The main platform UI, built with Vite.
cd neostra-ui
npm install
VITE_CORE_BASE_URL=http://localhost:9000 npm run dev
Open http://localhost:5173 in your browser.
The admin control plane UI.
cd astra-ui
npm install
npm run dev
Service Port Reference
| Service | Port | Technology | Description |
|---|---|---|---|
neostra-core | 9000 | Java / Gradle | Primary API backend |
neostra-ui | 5173 | Vite / React | Main platform frontend |
neostra-migrations | -- | Java / Gradle | One-time migration runner |
cpmp-api-service | 9001 | Java / Gradle | Consent API |
cpmp-log-receipt-service | 9002 | Java / Gradle | Consent log ingestion |
cpmp-reporting-service | 9003 | Java / Gradle | Consent reporting |
cpmp-crawler-service | 9004 | Java / Gradle | Website cookie crawler |
data-discovery-boot | 8080 | Java / Gradle | Data discovery API |
data-discovery-scanner | -- | Python | Data source scanner worker |
astra-core | 9010 | Java / Gradle | Admin control plane API |
astra-ui | -- | Vite / React | Admin control plane frontend |
| MongoDB | 27017 | MongoDB 6+ | Primary document store |
| PostgreSQL | 5432 | PostgreSQL 14+ | Relational store for CPMP and Discovery |
Troubleshooting
For the minimum viable local setup, you only need MongoDB, neostra-migrations, neostra-core, and neostra-ui. Other services can be started as needed for the features you are working on.
Last updated 1 week ago
Built with Documentation.AI