How Hyperledger Identus fits together

1 · Prerequisites

Docker Desktop or Docker Engine with the Compose v2 plugin — Compose is a docker compose subcommand now, not the old docker-compose binary. The Cloud Agent and PRISM node are JVM services, so give Docker at least 4 GB of memory and 2 CPUs.

docker compose version   # expect v2.x
docker info | grep -i "total memory"

2 · Get a stack

Either take the upstream stack from the Cloud Agent repository, or generate a validated bundle from the Compose Lab in the console's Sandbox — it writes docker-compose.yml, .env and postgres/init.sql with pinned image tags.

git clone https://github.com/hyperledger-identus/cloud-agent
cd cloud-agent/infrastructure/local
./run.sh            # agent on http://localhost:8085/cloud-agent

3 · Lifecycle commands

docker compose config               # print the interpolated stack, catch .env typos
docker compose up -d --wait         # start and block until services are healthy
docker compose ps                   # state + published ports
docker compose logs -f cloud-agent  # follow one service
docker compose restart cloud-agent  # bounce a single service
docker compose pull && docker compose up -d   # upgrade to newer image tags
docker compose down                 # stop, keep the Postgres volume
docker compose down -v              # stop and DELETE all wallet + DID data

--wait is the important one: it returns only once every service with a healthcheck reports healthy, so scripts never race a half-booted agent.

4 · How the stack fits together

  your app / console
          |  REST  :8085/cloud-agent          DIDComm  :8090
          v
   +--------------+  gRPC :50053   +------------+
   | cloud-agent  |--------------->| prism-node |
   +--------------+                +------------+
          |  pollux, connect, agent      |  node
          v                              v
              +--------------------------+
              |  postgres :5432 (pgdata) |
              +--------------------------+

Four databases are created by postgres/init.sql — pollux (credentials), connect (DIDComm connections), agent (wallets and secrets) and node (PRISM node). Keeping them separate stops the modules' migrations from colliding.

5 · Environment and ports

Only the left side of a port mapping is yours to change. If 5432 is already taken by a local Postgres, set POSTGRES_PORT=5433 — the container keeps listening on 5432 inside the network, so no other service needs editing.

6 · Startup order and health

The agent cannot migrate its schema until Postgres accepts connections, so Postgres declares a pg_isready healthcheck and the other services depend on it with condition: service_healthy. Plain depends_on only waits for the container to start, which is not the same as ready. The agent has its own healthcheck against /_system/health with a generous start_period for JVM boot.

7 · Connect the console

On the Agents page pick Docker local, set the base URL to http://localhost:8085/cloud-agent and paste your ADMIN_TOKEN as the admin API key, then run the health probe. Verify from the shell first:

curl -fsS http://localhost:8085/cloud-agent/_system/health
curl -fsS -H "apikey: $ADMIN_TOKEN" \
  http://localhost:8085/cloud-agent/did-registrar/dids

8 · Troubleshooting

9 · Data and cleanup

All state lives in the named volume pgdata. Published DIDs and issued credentials do not survive a down -v, so back it up before resetting.

docker compose exec postgres pg_dumpall -U postgres > identus-backup.sql
docker volume ls | grep pgdata
docker compose down -v && docker compose up -d --wait   # clean slate

Fly.io, from the console

The Agents page provisions a Fly app with three machines — Postgres, a PRISM node and the Cloud Agent — using your Fly organisation token, then stores the generated API key so the console can talk to it over HTTPS.

Simulated

No infrastructure. The app performs the same workflow deterministically so you can learn the protocol shape before deploying anything.