Skip to main content

​
Overview

Dokrypt orchestrates Docker containers for every chain and service. Understanding the container architecture helps with debugging, customization, and advanced configurations.

​
Container Architecture

When you run dokrypt up, Dokrypt:
  1. Creates a Docker network — dokrypt-{project-name} for inter-container communication
  2. Starts chain containers — Each chain runs in its own container (Anvil, Hardhat, or Geth)
  3. Starts service containers — IPFS, explorers, oracles, etc. in dependency order
  4. Runs health checks — Waits for all containers to report healthy
  5. Saves state — Container IDs and ports saved to ~/.dokrypt/state/

​
Container Runtime

Dokrypt supports Docker and Podman: 
# dokrypt.yaml
settings:
  runtime: docker    # or podman
Or via CLI: 
dokrypt up --runtime podman

​
Runtime Requirements

RuntimeMinimum VersionAPI Version
Docker20.10+1.41+
Podman4.0+—

​
Docker Images

​
Chain Images

EngineImage
Anvilghcr.io/foundry-rs/foundry:latest
Hardhatnode:20-alpine (runs npx hardhat)
Gethethereum/client-go:stable

​
Service Images

ServiceImage
IPFSipfs/kubo:latest
Blockscoutblockscout/blockscout:latest
Subgraphgraphprotocol/graph-node:latest

​
Running Dokrypt in Docker

Dokrypt itself can run as a Docker container: 
docker pull ghcr.io/dokrypt-org/dokrypt:latest

docker run --rm \
  -v /var/run/docker.sock:/var/run/docker.sock \
  -v $(pwd):/workspace \
  -w /workspace \
  ghcr.io/dokrypt-org/dokrypt:latest up
The Docker socket mount is required so Dokrypt can manage sibling containers.

​
Dockerfile.cli

FROM golang:1.24-alpine AS builder
WORKDIR /build
COPY go.mod go.sum ./
RUN go mod download
COPY . .
RUN CGO_ENABLED=0 GOOS=linux go build -ldflags="-s -w" -o /dokrypt ./cmd/dokrypt

FROM alpine:3.20
RUN apk add --no-cache ca-certificates docker-cli
COPY --from=builder /dokrypt /usr/local/bin/dokrypt
ENTRYPOINT ["dokrypt"]

​
Custom Service Images

Use type: custom to run any Docker image: 
services:
  my-api:
    type: custom
    image: my-api:latest
    ports:
      http: 3000
    environment:
      DATABASE_URL: "postgres://db:5432/mydb"

​
Build from Dockerfile

services:
  my-service:
    type: custom
    build:
      context: ./my-service
      dockerfile: Dockerfile
    ports:
      http: 8080

​
Container Labels

Dokrypt labels all containers with: 
dokrypt.project=my-project
dokrypt.service=ethereum
dokrypt.type=chain
You can list Dokrypt containers: 
docker ps --filter "label=dokrypt.project=my-project"

​
Networking

​
Environment Network

All containers share a Docker bridge network named dokrypt-{project}. Containers can reach each other by service name: 
http://ethereum:8545     # Chain RPC (from inside containers)
http://ipfs:5001         # IPFS API (from inside containers)
From the host, use localhost with the mapped ports: 
http://localhost:8545     # Chain RPC (from host)
http://localhost:5001     # IPFS API (from host)

​
Volumes

Services can mount volumes for persistent data: 
services:
  my-service:
    type: custom
    volumes:
      - "./data:/app/data"        # Bind mount
      - "my-volume:/app/storage"  # Named volume
Remove volumes when stopping: 
dokrypt down --volumes

​
Debugging Containers

​
View logs

dokrypt logs -f -s ethereum

​
Execute commands inside a container

dokrypt exec ethereum sh
dokrypt exec ipfs ipfs id

​
Inspect container directly with Docker

docker inspect $(docker ps -q --filter "label=dokrypt.service=ethereum")

​
Resource Limits

Container resource limits can be set through the container runtime configuration. The ContainerConfig supports:
SettingDescription
MemoryLimitMaximum memory (e.g., 512m, 2g)
CPULimitCPU cores (e.g., 1.5 = 1.5 cores)
ReadOnlyRead-only root filesystem
CapDropDropped Linux capabilities
These are configured programmatically through the container runtime interface and can be set via custom service configurations.

​
Cleanup

# Stop everything
dokrypt down

# Stop and remove volumes
dokrypt down --volumes

# Manual cleanup if needed
docker rm -f $(docker ps -aq --filter "label=dokrypt.project=my-project")
docker network rm dokrypt-my-project