docker-compose.yml

Overview

This `docker-compose.yml` file serves as the foundational Docker Compose configuration for the ShapeShift Unchained platform's **local development environment**. It orchestrates core services essential for running and developing blockchain node clients, API servers, and supporting tooling containers in a containerized, reproducible manner on local developer machines.

Primary Purposes

• Build and run local blockchain node runtimes based on Node.js and Go stacks.

• Facilitate live development workflows with a watcher service that monitors source code changes and triggers rebuilds or restarts.

• Route and expose service traffic through a Traefik v2.5 reverse proxy container that dynamically manages HTTP routing for multiple blockchain APIs.

• Provide isolated Docker networks for each blockchain coinstack, enabling modular and network-segregated service discovery and communication.

This setup enables developers to quickly spin up a realistic multi-blockchain API environment locally, without requiring a full Kubernetes or production-like cluster.

Services

The file defines four main services:

1. unchained-local-node

• Purpose: Builds and runs the Node.js-based blockchain node runtime image.

• Image: unchained-local-node

• Build Configuration:

  • Context: ./node directory relative to the compose file.

  • Dockerfile: Dockerfile.local used for a local development build.

**Usage:** This service compiles and provides the Node.js runtime environment for blockchain API servers to run against local source code.

2. unchained-local-go

• Purpose: Builds and runs the Go-based blockchain node runtime image.

• Image: unchained-local-go

• Build Configuration:

  • Context: ./go/build directory.

  • Dockerfile: Dockerfile.local

**Usage:** Provides a local Go runtime container for blockchain services implemented in Go, facilitating development and testing.

3. watcher

• Purpose: Watches source code changes and triggers rebuilds or reloads of the relevant Node.js packages.

• Build Configuration:

  • Context: ./node

  • Dockerfile: Dockerfile.local

• Working Directory: /app/node

• Command:
  Runs a shell command that installs dependencies (yarn install) and then starts lerna in watch mode scoped to all @shapeshiftoss/* packages in parallel:

  sh -c "yarn install && yarn lerna run watch --scope @shapeshiftoss/* --parallel"
  

• Volumes:
  Mounts the entire current directory to /app inside the container to ensure live source code syncing.

**Important Implementation Detail:** The extra `yarn install` inside the container addresses a known issue on macOS where platform-specific packages (e.g., `@nx/nx-linux-arm64-musl`) fail if `node_modules` are copied directly from the host.

**Usage Example:** During development, as files change on the host, this watcher container detects those changes and recompiles/restarts Node.js services automatically, improving feedback loops.

4. reverse-proxy

• Purpose: Runs Traefik v2.5 as a dynamic reverse proxy to route HTTP and WebSocket requests to individual blockchain API containers.

• Image: traefik:v2.5

• Command-line Flags:

  • --api.insecure=true
    Enables the Traefik web UI dashboard on port 8080 (insecure for dev only).

  • --providers.docker=true
    Enables Docker provider to listen to Docker events and dynamically update routing based on container labels.

  • --providers.docker.exposedbydefault=false
    Ensures only containers explicitly labeled are exposed through Traefik.

• Networks:
  Connected to all blockchain coinstack Docker networks and a dedicated proxy_default network, allowing it to route traffic across all services.

• Ports:

  • Exposes HTTP port 80 ("80:80")

  • Exposes Traefik dashboard port 8080 ("8080:8080")

• Volumes:
  Mounts Docker socket (/var/run/docker.sock:/var/run/docker.sock) to listen for Docker events.

**Usage:** Traefik serves as the unified gateway for all blockchain API endpoints, using Docker labels and networks to route requests transparently.

Networks

The file defines multiple Docker networks, each corresponding to a blockchain coinstack environment. This isolates services per blockchain while allowing the reverse proxy to connect across them.

**Defined Networks:**

Each network is explicitly named to ensure consistent references across multiple docker-compose files.

Important Implementation Details

• Multi-network Connection:
  The reverse-proxy service connects to all blockchain networks, allowing Traefik to route requests to any blockchain API service running in their respective network.

• Explicit Image Builds:
  Both unchained-local-node and unchained-local-go are built locally from source with dedicated Dockerfiles, which enables rapid iteration and debugging.

• Source Code Mounting in Watcher:
  Mounting the entire source into the watcher container means that any changes in the host filesystem immediately reflect inside the container, triggering rebuilds or restarts.

• Traefik Docker Provider:
  Traefik automatically configures itself by listening to Docker events, reading container labels (defined in coinstack-specific Compose files), and updating its routing without manual configuration.

Interaction with Other Parts of the System

• Coinstack-Specific Compose Files:
  Each blockchain coinstack defines its own docker-compose.yml (e.g., node/coinstacks/litecoin/docker-compose.yml) that defines an api service connected to the respective blockchain network (e.g., litecoin_default). These API containers expose ports and labels that Traefik uses for routing.

• Volume Mounting for Hot Reload:
  The watcher service and API containers mount the source code, enabling development workflows with live reloads using tools like nodemon and lerna.

• Traefik as Unified Gateway:
  The reverse proxy exposes all APIs under different hostnames or paths, simplifying access to various blockchain services during development.

• Performance Testing Scripts:
  Load testing tools (e.g., k6 scripts) target the local API endpoints exposed through Traefik to validate API performance and scalability.

• Local Node and Go Services:
  The node and Go images provide foundational runtime environments for blockchain logic, which the API services depend upon.

Usage Example

To start the local development environment with this compose file:

docker-compose up --build

This command builds the `unchained-local-node` and `unchained-local-go` images, starts the watcher service to enable live code watching, and runs Traefik reverse proxy for routing.

Developers can then access local blockchain APIs via URLs like:

http://api.litecoin.localhost
http://api.ethereum.localhost

Assuming coinstack-specific Compose files define the appropriate Traefik labels.

Visual Diagram: Service and Network Structure

flowchart TD
  subgraph Services
    ULN[unchained-local-node]
    ULG[unchained-local-go]
    Watcher[Watcher Service]
    Traefik[Traefik Reverse Proxy]
  end

  subgraph Networks
    Arbitrum[arbitrum_default]
    Bitcoin[bitcoin_default]
    Litecoin[litecoin_default]
    Proxy[proxy_default]
  end

  ULN -->|Builds Node.js blockchain runtime| Networks
  ULG -->|Builds Go blockchain runtime| Networks
  Watcher -->|Watches source & rebuilds| ULN
  Watcher --> ULN
  Traefik -->|Routes HTTP/WS traffic| Networks
  Traefik --> Proxy

  %% Connections to networks
  Traefik --- Arbitrum
  Traefik --- Bitcoin
  Traefik --- Litecoin
  Traefik --- Proxy

  %% Example API containers (defined in coinstack-specific compose files)
  BitcoinAPI[Bitcoin API Container]
  LitecoinAPI[Litecoin API Container]
  BitcoinAPI --- Bitcoin
  LitecoinAPI --- Litecoin
  Traefik --> BitcoinAPI
  Traefik --> LitecoinAPI

**Diagram Explanation:** This flowchart shows the core services (`unchained-local-node`, `unchained-local-go`, `watcher`, `Traefik`) and their connections to various blockchain networks. Traefik connects to all relevant networks and routes requests to blockchain API containers (defined elsewhere). The watcher triggers rebuilds of the Node.js runtime image.

Summary

The `docker-compose.yml` file is a central piece in the ShapeShift Unchained developer tooling ecosystem. It:

• Builds and runs local Node.js and Go blockchain runtimes.

• Provides a watcher service for live code recompilation and restart.

• Runs Traefik as a reverse proxy to dynamically route requests on local networks.

• Defines multiple blockchain-specific Docker networks for modular isolation.

• Enables rapid local development, debugging, and testing of multi-blockchain APIs.

This setup forms the backbone upon which coinstack-specific API services and performance testing scripts operate, streamlining developers' ability to run and iterate on the entire blockchain API platform locally.

End of Documentation for docker-compose.yml