Skip to main content

​
Prerequisites

  • Docker Engine 20.10 or later
  • Docker Compose v2 (docker compose command, not docker-compose)
  • A running PostgreSQL instance (version 16 recommended) accessible from the containers
  • Git

​
Services

The docker-compose.yml file defines the following services:
ServiceImagePortDescription
natsnats4222, 6222, 8222Message broker for inter-service communication
redisredis:6.2-alpine6379Cache layer used by api-gateway and issuance
seedghcr.io/credebl/seed:latest—Runs Prisma migrations and seeds master data
api-gatewayghcr.io/credebl/api-gateway:latest5000HTTP entry point; exposes Swagger UI
userghcr.io/credebl/user:latest—User registration, authentication, and profile management
utilityghcr.io/credebl/utility:latest—Shared utilities required by connection and other services
connectionghcr.io/credebl/connection:latest—DIDComm connection management
issuanceghcr.io/credebl/issuance:latest—Verifiable credential issuance
ledgerghcr.io/credebl/ledger:latest—Ledger interaction and DID registration
organizationghcr.io/credebl/organization:latest—Organization and wallet management
verificationghcr.io/credebl/verification:latest—Credential proof verification
agent-provisioningghcr.io/credebl/agent-provisioning:latest—Spins up per-organization Credo (AFJ) agent containers
agent-serviceghcr.io/credebl/agent-service:latest—Communicates with running agent containers
cloud-walletghcr.io/credebl/cloud-wallet:latest—Cloud wallet service
geolocationghcr.io/credebl/geolocation:latest—Geolocation data service
notificationghcr.io/credebl/notification:latest—Email and push notification dispatch
webhookghcr.io/credebl/webhook:latest—Outbound webhook delivery
schema-file-serverghcr.io/credebl/schema-file-server:latest—Serves schema files for Polygon/W3C credentials

​
Service startup order

The depends_on declarations in docker-compose.yml define the following boot sequence: 
nats, redis
  └── api-gateway
        ├── user
        ├── utility
        │     └── connection
        │           ├── issuance (also needs redis)
        │           │     └── ledger
        │           │           └── organization
        │           │                 └── verification
        │           │                       └── agent-provisioning
        │           │                             └── agent-service
        ├── cloud-wallet
        ├── geolocation
        ├── notification
        └── webhook
agent-service additionally waits for agent-provisioning to log "Agent-Provisioning-Service Microservice is listening to NATS" before it starts.

​
Deployment

1

Clone the repository

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

Configure environment variables

Copy the sample file and fill in the required values:
cp .env.sample .env
The following variables must be set before any service will start correctly:
  • DATABASE_URL — PostgreSQL connection string, e.g. postgresql://postgres:password@host:5432/dbname?schema=public
  • POSTGRES_HOST, POSTGRES_PORT, POSTGRES_USER, POSTGRES_PASSWORD, POSTGRES_DATABASE
  • NATS_URL — defaults to nats://0.0.0.0:4222
  • REDIS_HOST, REDIS_PORT
  • PLATFORM_ADMIN_EMAIL — used by the seed service to create the platform admin user
  • CRYPTO_PRIVATE_KEY — 32-character key used to encrypt wallet credentials; must match the value used by the Studio UI
  • KEYCLOAK_DOMAIN, KEYCLOAK_REALM, KEYCLOAK_MANAGEMENT_CLIENT_ID, KEYCLOAK_MANAGEMENT_CLIENT_SECRET
  • PLATFORM_ADMIN_KEYCLOAK_ID, PLATFORM_ADMIN_KEYCLOAK_SECRET
  • All *_NKEY_SEED variables — one per microservice (e.g. USER_NKEY_SEED, API_GATEWAY_NKEY_SEED, ORGANIZATION_NKEY_SEED, etc.)
  • AGENT_HOST — SSH connection string for the agent host VM, e.g. username@0.0.0.0
  • AFJ_VERSION — Docker image tag for Credo agents, e.g. afj-0.4.1:latest
3

Start infrastructure services

Bring up NATS and Redis before the application services:
docker compose up nats redis -d
Verify they are healthy:
docker compose ps nats redis
4

Run the seed service

The seed service applies Prisma migrations and loads master data (org roles, agent types, ledger configs, platform config):
docker compose up seed
The container exits on completion. Check for errors before proceeding:
docker compose logs seed
The seed service mounts ./libs/prisma-service/prisma/data/credebl-master-table.json into the container. Ensure this file is present in your checkout.
5

Create the agent.env file

The agent-provisioning service mounts ./agent.env into the container at /app/agent.env. This file is passed to each spawned agent container. Create it with at minimum the wallet storage credentials:
touch agent.env
Add the values your agent containers require, for example:
agent.env
WALLET_STORAGE_HOST=<your-postgres-host>
WALLET_STORAGE_PORT=5432
WALLET_STORAGE_USER=postgres
WALLET_STORAGE_PASSWORD=<your-password>
6

Start all platform services

docker compose up -d
To follow logs across all services:
docker compose logs -f
7

Verify services are running

docker compose ps
All services should show running status. The seed container will show exited 0 — that is expected.Confirm the API gateway is accepting requests:
curl -s -o /dev/null -w "%{http_code}" http://localhost:5000/api
A 200 or 301 response confirms the gateway is up.
8

Access the Swagger UI

Open your browser and navigate to:
http://localhost:5000/api
The interactive API documentation lists all available endpoints grouped by microservice.

​
Port reference

PortServiceProtocolPurpose
5000api-gatewayHTTPREST API and Swagger UI
4222natsTCPNATS client connections
6222natsTCPNATS cluster routing
8222natsHTTPNATS monitoring and health
6379redisTCPRedis cache

​
Volume mounts

The agent-provisioning service requires the following mounts: 
volumes:
  - $PWD/apps/agent-provisioning/AFJ/agent-config:/app/agent-provisioning/AFJ/agent-config
  - /var/run/docker.sock:/var/run/docker.sock
  - /app/agent-provisioning/AFJ/token:/app/agent-provisioning/AFJ/token
  - $PWD/agent.env:/app/agent.env
The Docker socket mount (/var/run/docker.sock) is required so agent-provisioning can spin up per-organization agent containers on the host. The agent-service also mounts the Docker socket and uses volumes_from: agent-provisioning to access the shared agent-config and endpoints directories.

​
Troubleshooting

Confirm DATABASE_URL in .env points to a reachable PostgreSQL instance. If PostgreSQL is running on the host machine, use the host’s LAN IP rather than localhost or 127.0.0.1, since services run inside Docker containers.
Check logs with docker compose logs api-gateway. Missing or malformed NKEY seed values are a common cause. Ensure all *_NKEY_SEED variables in .env are set.
agent-service waits for the log line "Agent-Provisioning-Service Microservice is listening to NATS" from agent-provisioning. If agent-provisioning fails to connect to NATS, agent-service will wait indefinitely. Run docker compose logs agent-provisioning to diagnose.
The .env.sample sets NATS_AUTH_TYPE=nkey. Each service has its own *_NKEY_SEED variable. Generate unique NKey seeds for each service and set them in .env. The NATS_CREDS_FILE variable is only required when NATS_AUTH_TYPE=creds.
Verify that /var/run/docker.sock is mounted into agent-provisioning and that the user running Docker has permission to access the socket. Also confirm that AGENT_HOST and AFJ_VERSION are set in .env.

Build docs developers (and LLMs) love

Get started for freeTalk to us