Skip to main content

​
When to use this approach

Run services individually from source when you need to:
  • Develop or debug a specific microservice with live reload
  • Step through service code with a debugger
  • Test changes before building a Docker image
  • Run a subset of services while keeping others in Docker
For a full production-equivalent deployment, use Docker Compose instead.

​
Prerequisites

  • Node.js 18.17.0 or later
  • pnpm (installed globally)
  • NestJS CLI
npm install -g pnpm
npm install -g @nestjs/cli@latest
  • Docker (for running PostgreSQL and NATS)
  • A clone of the repository

​
Setup

1

Clone the repository and install dependencies

git clone https://github.com/credebl/platform.git
cd platform
npm install
2

Configure environment variables

cp .env.sample .env
Open .env and set all required values. At minimum, the following must be configured before any service will connect successfully:
  • DATABASE_URL — PostgreSQL connection string
  • NATS_URL — e.g. nats://0.0.0.0:4222
  • REDIS_HOST and REDIS_PORT
  • All *_NKEY_SEED variables for the services you plan to run
  • PLATFORM_ADMIN_EMAIL
  • CRYPTO_PRIVATE_KEY
  • KEYCLOAK_DOMAIN, KEYCLOAK_REALM, KEYCLOAK_MANAGEMENT_CLIENT_ID, KEYCLOAK_MANAGEMENT_CLIENT_SECRET
3

Start PostgreSQL

Start a local PostgreSQL instance using Docker:
docker run --name credebl-postgres \
  -p 5432:5432 \
  -e POSTGRES_USER=credebl \
  -e POSTGRES_PASSWORD=changeme \
  -e POSTGRES_DB=credebl \
  -v credebl_pgdata:/var/lib/postgresql/data \
  -d postgres:16
Update DATABASE_URL in .env to match:
DATABASE_URL="postgresql://credebl:changeme@localhost:5432/credebl?schema=public"
4

Start NATS

Pull and run the NATS message broker:
docker pull nats:latest
docker compose up nats -d
NATS listens on:
  • 4222 — client connections
  • 6222 — cluster routing
  • 8222 — HTTP monitoring
5

Start Redis

docker compose up redis -d
Redis listens on 6379.
6

Run Prisma migrations and generate the client

cd libs/prisma-service/prisma
npx prisma generate
npx prisma db push
cd ..
7

Seed initial data

The seed script populates org roles, agent types, ledger configs, platform config, and the platform admin user. It reads master data from prisma/data/credebl-master-table.json.
cd libs/prisma-service
npx prisma db seed
This is equivalent to running the seed container in the Docker Compose deployment.
8

Start the API gateway

Open a terminal and start the API gateway. Use --watch to enable live reload during development:
nest start --watch
The gateway binds to http://0.0.0.0:5000. The Swagger UI is available at http://localhost:5000/api.
9

Start each microservice

Open a separate terminal window for each service. Start them in the order shown below, as later services depend on earlier ones being available on NATS.
nest start user [--watch]
The full set of services and their commands:
ServiceCommand
API gatewaynest start [--watch]
Usernest start user [--watch]
Organizationnest start organization [--watch]
Connectionnest start connection [--watch]
Issuancenest start issuance [--watch]
Verificationnest start verification [--watch]
Ledgernest start ledger [--watch]
Agent provisioningnest start agent-provisioning [--watch]
Agent servicenest start agent-service [--watch]
organization and utility are not listed in the README’s start sequence but are part of the platform. Start utility before connection, and organization before verification and agent-provisioning.

​
NATS authentication (NKEY seeds)

Each microservice authenticates to NATS using an NKey seed defined in .env. Set a unique seed for each service:
.env
USER_NKEY_SEED=xxxxxxxxxxxxx
API_GATEWAY_NKEY_SEED=xxxxxxxxxxxxx
ORGANIZATION_NKEY_SEED=xxxxxxxxxxxxx
AGENT_PROVISIONING_NKEY_SEED=xxxxxxxxxxxxx
AGENT_SERVICE_NKEY_SEED=xxxxxxxxxxxxx
VERIFICATION_NKEY_SEED=xxxxxxxxxxxxx
ISSUANCE_NKEY_SEED=xxxxxxxxxxxxx
CONNECTION_NKEY_SEED=xxxxxxxxxxxxx
ECOSYSTEM_NKEY_SEED=xxxxxxxxxxxxx
CREDENTAILDEFINITION_NKEY_SEED=xxxxxxxxxxxxx
SCHEMA_NKEY_SEED=xxxxxxxxxxxxx
UTILITIES_NKEY_SEED=xxxxxxxxxxxxx
GEOLOCATION_NKEY_SEED=xxxxxxxxxxx
X509_NKEY_SEED=xxxxxxxxxxx
OIDC4VC_ISSUANCE_NKEY_SEED=xxxxxxxxxxx
OIDC4VC_VERIFICATION_NKEY_SEED=xxxxxxxxxxx
The authentication type is controlled by NATS_AUTH_TYPE in .env. Supported values are nkey, creds, usernamePassword, and none. For local development, nkey is the default.

​
Accessing endpoints

Once the API gateway and at least the user service are running, navigate to: 
http://localhost:5000/api
The Swagger UI lists all registered routes. Routes provided by microservices that are not yet running will return NATS timeout errors.

​
Monitoring logs

Each nest start process writes structured logs to stdout. For production-like log aggregation, set the following in .env:
.env
CONSOLE_LOG_FLAG=true
ELK_LOG=true
LOG_LEVEL=debug
ELK_LOG_PATH=http://localhost:9200/
ELK_USERNAME=elastic
ELK_PASSWORD=xxxxxx
OpenTelemetry tracing is also supported. Enable it with:
.env
IS_ENABLE_OTEL=true
OTEL_SERVICE_NAME=CREDEBL-PLATFORM-SERVICE
OTEL_TRACES_OTLP_ENDPOINT=http://localhost:4318/v1/traces
OTEL_LOGS_OTLP_ENDPOINT=http://localhost:4318/v1/logs

Build docs developers (and LLMs) love

Get started for freeTalk to us