Run with Docker

Decentralization Manager prerequisites · Run Decentralization Manager locally

Outcome

Build one development image, run one isolated Decentralization Manager container with persistent state, connect it to Canton, and verify that its identity survives a restart.

This guide is for development. Use Decentralization Manager production deployment for production images, orchestration, TLS, secrets, backups, monitoring, and upgrades.

Before you begin

• Docker Engine with BuildKit and Docker Compose v2.
• An Engineering-approved Decentralization Manager tag or commit.
• A GitHub SSH key loaded into ssh-agent for the current development build.
• Reachable Canton Admin and Ledger APIs.
• An approved Keycloak or Auth0 development configuration.
• A writable directory for the Noise identity, SQLite database, and DAR files.

Do not enable DECPM_INSECURE in a shared, externally reachable, staging, or production environment.

1. Build the development image

git clone <https://github.com/DLC-link/decentralization-manager.git>
cd decentralization-manager
git checkout <approved-release-tag-or-commit>

eval "$(ssh-agent -s)"
ssh-add ~/.ssh/id_ed25519

DOCKER_BUILDKIT=1 docker build \
  --ssh default \
  -f development/Dockerfile \
  -t dec-party-manager:dev \
  .

Confirm the image exists:

docker image inspect dec-party-manager:dev --format '{{.RepoTags}}'

2. Prepare persistent state

mkdir -p ./development/docker-node/data

The mounted directory must preserve:

noise.key    Persistent peer identity
decpm.db     Operational state and stored configuration
dars/        Packages staged for workflows

Replacing noise.key changes the peer identity. Deleting decpm.db removes local peer, credential, and workflow state.

3. Configure the container

Create ./development/docker-node/decman.env. Include the reviewed values for:

• HTTP and Noise listener addresses and ports.
• Public peer address.
• Canton Admin and Ledger hosts, ports, network, and synchronizer.
• TLS or mTLS settings when the Canton endpoints require them.
• Keycloak or Auth0 browser authentication.
• DECPM_DIR=/app so state is written under /app/data.

Do not store production credentials in this file or commit it to source control.

4. Start one container

docker run -d \
  --name dec-party-manager \
  --restart unless-stopped \
  --env-file ./development/docker-node/decman.env \
  --add-host host.docker.internal:host-gateway \
  -p 8080:8080 \
  -p 9000:9000 \
  -v "$(pwd)/development/docker-node/data:/app/data" \
  dec-party-manager:dev

The HTTP port serves the operator interface. Expose the Noise port only to intended peers.

5. Verify startup and persistence

docker ps --filter name=dec-party-manager
docker logs --tail 100 dec-party-manager
find ./development/docker-node/data -maxdepth 2 -type f -print

docker restart dec-party-manager
docker logs --tail 100 dec-party-manager
find ./development/docker-node/data -maxdepth 2 -type f -print

Confirm that:

• The operator interface is reachable and uses the configured identity provider.
• Canton Admin and Ledger connections report the expected state.
• The same noise.key and decpm.db remain after restart.
• Logs do not expose credentials or tokens.

Optional development mesh

The repository includes development/docker-compose.yml for a three-instance development stack. Use the repository environment templates and verified Canton port forwards. Each instance must have a separate persistent directory. Treat the example participant count and ports as development assumptions, not production architecture.

Troubleshooting

Symptom	Check
Build cannot fetch canton-lib	BuildKit, SSH agent, GitHub key registration, and --ssh default.
Container exits	Required environment values, file permissions, and identity-provider configuration.
Canton connection fails	Container routing, ports, and independent Admin and Ledger TLS settings.
Login redirects repeatedly	Provider origin, redirect URI, client ID, realm or audience, and PKCE configuration.
Peer identity changes after restart	DECPM_DIR, the /app/data mount, and host-directory persistence.

Technical sources

• Development Dockerfile
• Development Compose file
• Production deployment guide

Next step

👉 Form the development mesh: Connect Decentralization Manager peers.