docker-compose.yml

Overview

This [docker-compose.yml](/projects/291/68791) file defines the configuration for running the **Avalanche blockchain API service** within a Docker containerized environment tailored for local development. It orchestrates the setup of a single service named `api`, which:

Uses a custom local Docker image (unchained-local-node) designed to run blockchain node-related services.
Loads environment variables from a .env file.
Integrates with Traefik, a dynamic reverse proxy and load balancer, via Docker labels to route local HTTP requests to the API container.
Runs the API server inside the container with live reload capabilities using nodemon.
Mounts the local source code directory into the container to enable real-time code changes without rebuilding Docker images.
Connects the service to an externally defined Docker network named avalanche_default.

This file is part of a broader set of Docker Compose configurations that enable developers to spin up isolated blockchain coinstack API services (e.g., Litecoin, Avalanche) locally with a development-friendly workflow.

Detailed Explanation

Top-Level Keys

services: Defines containerized services to run.
networks: Specifies Docker networks used by the services.

Service: `api`

This is the primary container running the Avalanche API server.

Key	Description
`image`	`unchained-local-node` - A locally built Docker image containing the node/API environment.
`env_file`	`.env` - Loads environment variables from this file to configure service behavior.
`labels`	Docker labels configuring Traefik routing and load balancing rules.
`working_dir`	[/app/node/coinstacks/avalanche/api](/projects/291/69281) - Sets the working directory inside the container.
`command`	`yarn nodemon` - Starts the API using nodemon for hot reloading on source changes.
`volumes`	Mounts `../../..` from host to `/app` in the container, enabling live code updates.
`networks`	Connects this service to the external network `avalanche`.

Labels for Traefik Integration

These labels instruct Traefik to:

Enable reverse proxying for this container.
Route requests where the HTTP Host header matches api.avalanche.localhost.
Forward traffic to the internal port 3000 exposed by the API server inside the container.

labels:
  - 'traefik.enable=true'
  - 'traefik.http.routers.avalanche-api.rule=Host(`api.avalanche.localhost`)'
  - 'traefik.http.services.avalanche-api.loadbalancer.server.port=3000'

Volumes and Working Directory

The volume mounts the project root (../../..) into /app to allow nodemon to detect source changes.
The working directory points to the Avalanche API source code, ensuring commands run in the appropriate context.

Command

Runs yarn nodemon, which watches for file changes and restarts the API server automatically, facilitating rapid development.

Network: `avalanche`

Declares an external Docker network named avalanche_default.
This network is expected to be created outside this Compose file, enabling connectivity with other services (e.g., blockchain node containers, indexers) that also join this network.

networks:
  avalanche:
    name: avalanche_default
    external: true

Usage Example

Assuming the `unchained-local-node` image is already built and the `avalanche_default` Docker network exists, run:

docker-compose up

This command will:

Start the Avalanche API container.
Mount local code for live reload.
Enable Traefik to route http://api.avalanche.localhost requests to this container on port 3000.
Allow developers to modify API source code and see updates instantly via nodemon.

Important Implementation Details

Live Reloading: Using nodemon ensures the API server automatically restarts when source files change, significantly improving developer feedback loops.
Traefik Labels: These are essential to automatically configure Traefik's dynamic routing, avoiding manual proxy config.
External Network: By connecting to avalanche_default, the API can communicate with other blockchain node containers or services on the same network, facilitating integrated local testing.
Volume Mounting: Direct source code mounting avoids frequent Docker image rebuilds, saving development time.

Interaction with Other System Components

Traefik Reverse Proxy: This file relies on Traefik running elsewhere in the local environment, which listens to Docker events and routes requests based on container labels.
Blockchain Node Containers: The API service connects to the Avalanche blockchain node and indexer services (running on the same avalanche_default network) to fetch blockchain data.
Source Code Repository: Developers modify the API source code on their host machine; changes are reflected live in the container due to volume mounting.
Environment Variables: The .env file provides configuration secrets or parameters that control the API service’s runtime behavior.

Mermaid Diagram: Service-Workflow Flowchart

flowchart TD
    A[Developer / Host Machine]
    B[Local Source Code]
    C[Docker Container: Avalanche API]
    D[unchained-local-node Image]
    E[Traefik Reverse Proxy]
    F[avalanche_default Network]
    G[Blockchain Node & Indexer Services]

    A --> B
    B -->|Volume Mount| C
    D --> C
    C --> F
    G --> F
    C -->|HTTP port 3000| E
    E -->|Routes api.avalanche.localhost| A

**Diagram Explanation:**

Developers edit source code on their host machine.
Source code is volume-mounted into the Avalanche API container built from the unchained-local-node image.
The API container connects to other blockchain-related services via the external avalanche_default Docker network.
Traefik reverse proxy routes HTTP requests from developers’ browsers to the API container based on hostname rules.

Summary

This [docker-compose.yml](/projects/291/68791) file is a concise yet powerful configuration enabling local development of the Avalanche blockchain API service. By combining containerization, automatic code reload, network isolation, and dynamic reverse proxying, it provides a developer-friendly environment that closely mirrors production while accelerating iteration and debugging workflows. It fits into a larger ecosystem of Docker Compose files for multiple blockchain coinstacks, collectively supporting a modular and scalable blockchain infrastructure development setup.