Docker Compose Environments

Purpose

This subtopic addresses the need for streamlined local development and testing setups that closely mirror production blockchain node, indexer, and API service environments. It provides Docker Compose configurations enabling developers to spin up all necessary services—blockchain daemons, indexers, APIs, and reverse proxies—in containerized form on their local machines. This approach eliminates the complexity of manually installing and configuring multiple blockchain components and their dependencies, accelerating development velocity and improving consistency across developer environments.

Functionality

The core functionality revolves around defining and orchestrating a set of Docker services that replicate the main blockchain infrastructure components:

• Local Node Containers: Build and run blockchain node clients and Go-based services from local source code using specialized Dockerfiles (e.g., Dockerfile.local), allowing quick iteration with code changes.

• API Service Containers: Launch API servers for individual blockchain coinstacks (e.g., Litecoin, Avalanche) with live reload support via nodemon, enabling immediate feedback when modifying API code.

• Reverse Proxy Service: Utilize Traefik as a dynamic reverse proxy and load balancer to route HTTP and WebSocket requests to the correct API container based on hostnames. Traefik listens to Docker events, automatically updating its routing configuration.

• Shared Networks: Define Docker networks corresponding to each blockchain coinstack environment, ensuring isolated but connectable service meshes per chain.

• Volume Mounting: Source code directories are mounted into containers, allowing seamless development without rebuilding images for most code changes.

Key workflows include:

1. Building Local Images:

   • The unchained-local-node and unchained-local-go images are built from local directories with Dockerfiles tailored for development.

   • The watcher service manages package installations and runs watch commands to rebuild or reload code across packages in the monorepo.

2. Running Blockchain API Containers:

   • Each coinstack has a dedicated docker-compose.yml specifying an api service.

   • The API service runs within the container’s working directory for the specific coinstack (e.g., node/coinstacks/litecoin/api), using nodemon for hot reload.

3. Routing Traffic via Traefik:

   • Traefik listens on ports 80 and 8080 for HTTP traffic and its dashboard.

   • It inspects Docker container labels to dynamically route requests like api.litecoin.localhost to the corresponding API container on port 3000.

4. Networking:

   • External Docker networks (e.g., litecoin_default) connect the API and related services.

   • The reverse proxy is connected to all relevant coinstack networks to facilitate cross-network routing.

Illustrative Snippet

The LiteCoin API service configuration highlights the core setup:

services:
  api:
    image: unchained-local-node
    env_file: .env
    labels:
      - 'traefik.enable=true'
      - 'traefik.http.routers.litecoin-api.rule=Host(`api.litecoin.localhost`)'
      - 'traefik.http.services.litecoin-api.loadbalancer.server.port=3000'
    working_dir: /app/node/coinstacks/litecoin/api
    command: yarn nodemon
    volumes:
      - ../../..:/app
    networks:
      - litecoin

This service runs the API server with hot reload, listens on the internal port 3000, and exposes it through Traefik under the `api.litecoin.localhost` hostname.

Integration

Within the broader context of developer tooling, Docker Compose environments provide a foundational local platform that complements other subtopics:

• Performance Testing: Developers can spin up local environments to validate API behavior before running load tests, ensuring stability and correctness in a controlled setting.

• Health and Readiness Probes: The local containers can simulate probe behaviors, enabling developers to test service readiness scripts without deploying to Kubernetes.

• Multi-Blockchain Coinstacks: Each coinstack’s Docker Compose file allows isolated development per blockchain, promoting modularity and parallel progress across chains.

• Unified API Layer: Running API servers locally with consistent configuration ensures that developers interact with the same API contracts and middleware logic as in production.

This subtopic fills the gap between complex Kubernetes deployments and lightweight, ephemeral local development setups, enabling rapid iteration and debugging without cloud dependencies.

Diagram

flowchart LR
    subgraph Local Dev Machine
        direction TB
        SourceCode[Source Code Mount]
        NodeImage[unchained-local-node Image]
        GoImage[unchained-local-go Image]
        Watcher[Watcher Service]
        Traefik[Traefik Reverse Proxy]
        LiteAPI[Litecoin API Service]
        AvaAPI[Avalanche API Service]
    end

    SourceCode --> NodeImage
    SourceCode --> GoImage
    SourceCode --> Watcher
    NodeImage --> LiteAPI
    NodeImage --> AvaAPI
    LiteAPI --> Traefik
    AvaAPI --> Traefik
    Watcher --> NodeImage
    Traefik -->|HTTP / WS Requests| Client[Developer / Browser]

This flowchart shows how source code is mounted into Docker images, which run API services that are routed through the Traefik reverse proxy. The watcher service manages code rebuilds and reloads, enabling a smooth development feedback loop.

The Docker Compose Environments subtopic thus bridges production-grade blockchain infrastructure with accessible local development tooling, allowing developers to efficiently build, test, and debug blockchain APIs and node services in a consistent and scalable manner.