> For the complete documentation index, see [llms.txt](https://docs.bitsafe.finance/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.bitsafe.finance/decentralization-manager/get-started/run-with-docker.md).

# Run with Docker

[Decentralization Manager prerequisites](/decentralization-manager/get-started/prerequisites.md) · [Run Decentralization Manager locally](/decentralization-manager/get-started/run-locally.md)

### 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](/decentralization-manager/get-started/production-deployment.md) 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.

{% hint style="info" %}
Do not enable `DECPM_INSECURE` in a shared, externally reachable, staging, or production environment.
{% endhint %}

### 1. Build the development image

```bash
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:

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

### 2. Prepare persistent state

```bash
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

```bash
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

```bash
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](https://github.com/DLC-link/decentralization-manager/blob/76d7156c85e605abc008e5fadf8aaa97f4706471/development/Dockerfile)
* [Development Compose file](https://github.com/DLC-link/decentralization-manager/blob/76d7156c85e605abc008e5fadf8aaa97f4706471/development/docker-compose.yml)
* [Production deployment guide](https://github.com/DLC-link/decentralization-manager/blob/76d7156c85e605abc008e5fadf8aaa97f4706471/docs/DEPLOYMENT_GUIDE.md)

### Next step

👉 **Form the development mesh:** [Connect Decentralization Manager peers](/decentralization-manager/get-started/connect-peers.md).


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.bitsafe.finance/decentralization-manager/get-started/run-with-docker.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.