Docker & Container Runtime

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:

Creates a Docker network — dokrypt-{project-name} for inter-container communication
Starts chain containers — Each chain runs in its own container (Anvil, Hardhat, or Geth)
Starts service containers — IPFS, explorers, oracles, etc. in dependency order
Runs health checks — Waits for all containers to report healthy
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

Runtime	Minimum Version	API Version
Docker	20.10+	1.41+
Podman	4.0+	—

Docker Images

Chain Images

Engine	Image
Anvil	`ghcr.io/foundry-rs/foundry:latest`
Hardhat	`node:20-alpine` (runs npx hardhat)
Geth	`ethereum/client-go:stable`

Service Images

Service	Image
IPFS	`ipfs/kubo:latest`
Blockscout	`blockscout/blockscout:latest`
Subgraph	`graphprotocol/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:

Setting	Description
`MemoryLimit`	Maximum memory (e.g., `512m`, `2g`)
`CPULimit`	CPU cores (e.g., `1.5` = 1.5 cores)
`ReadOnly`	Read-only root filesystem
`CapDrop`	Dropped 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

Getting Started

Core Concepts

Features

Advanced

Docker & Container Runtime

Overview

Container Architecture

Container Runtime

Runtime Requirements

Docker Images

Chain Images

Service Images

Running Dokrypt in Docker

Dockerfile.cli

Custom Service Images

Build from Dockerfile

Container Labels

Networking

Environment Network

Volumes

Debugging Containers

View logs

Execute commands inside a container

Inspect container directly with Docker

Resource Limits

Cleanup

​Overview

​Container Architecture

​Container Runtime

​Runtime Requirements

​Docker Images

​Chain Images

​Service Images

​Running Dokrypt in Docker

​Dockerfile.cli

​Custom Service Images

​Build from Dockerfile

​Container Labels

​Networking

​Environment Network

​Volumes

​Debugging Containers

​View logs

​Execute commands inside a container

​Inspect container directly with Docker

​Resource Limits

​Cleanup

Overview

Container Architecture

Container Runtime

Runtime Requirements

Docker Images

Chain Images

Service Images

Running Dokrypt in Docker

Dockerfile.cli

Custom Service Images

Build from Dockerfile

Container Labels

Networking

Environment Network

Volumes

Debugging Containers

View logs

Execute commands inside a container

Inspect container directly with Docker

Resource Limits

Cleanup