docker-compose.yml

Overview

The `docker-compose.yml` file defines and configures a Docker Compose application environment for the **Thorchain API** service. It specifies how to build and run the API service container, including environment variables, runtime commands, volumes, networking, and integration with Traefik as a reverse proxy/load balancer.

This file is essential for local development or deployment setups, enabling the Thorchain API to be run in a containerized environment with automatic file watching and recompilation, and seamless routing through Traefik.

Detailed Explanation

Services

api

• Purpose: Runs the Thorchain API service inside a container.

• Image: unchained-local-go

  • This is the base Docker image used for the container. Presumably, it contains the Go runtime and necessary dependencies pre-installed for building and running the Thorchain API.

• Environment Variables:

  • GOCACHE=/tmp

    • Sets the Go build cache directory inside the container to /tmp for caching compiled packages, improving rebuild times.

• Labels (for Traefik reverse proxy configuration):

  • 'traefik.enable=true'

    • Enables Traefik to manage this container's HTTP routing.

  • 'traefik.http.routers.thorchain-api.rule=Host(api.thorchain.localhost)'

    • Routes requests with the hostname api.thorchain.localhost to this container.

  • 'traefik.http.services.thorchain-api.loadbalancer.server.port=3000'

    • Specifies that Traefik should forward requests to port 3000 inside the container (where the API listens).

• Command:

  sh -c "reflex -r '(pkg|internal|thorchain)' -R 'swagger' -s -- sh -c 'swagger generate spec -w coinstacks/thorchain -o coinstacks/thorchain/api/swagger.json -x protoc-gen-openapiv2 -m && go run cmd/thorchain/main.go -env cmd/thorchain/.env'"
  

  • This command runs a shell that:

    • Uses reflex, a file watcher, to monitor changes in files matching the regex (pkg|internal|thorchain) but excluding swagger directory/files.

    • On detected changes, it runs the following actions:

      1. Generates an OpenAPI (Swagger) specification using swagger generate spec for the coinstacks/thorchain package, outputting JSON to coinstacks/thorchain/api/swagger.json.

      2. Runs the Go application (cmd/thorchain/main.go) with environment variables loaded from cmd/thorchain/.env.

    • This setup facilitates live recompilation and API spec regeneration during development.

• Working Directory: /app

  • The container's working directory is set to /app, where the source code is mounted.

• Volumes:

  • ../..:/app

    • Mounts the host's project root (two levels up) into /app in the container, allowing live code edits to reflect immediately.

  • $GOPATH/pkg/mod/cache:/go/pkg/mod/cache

    • Mounts the Go module cache from the host into the container to speed up module downloads and builds.

• Networks:

  • Connected to the thorchain Docker network to enable communication with other connected services or Traefik.

Networks

thorchain

• Name: thorchain_default

• External: true

  • This indicates the network is pre-existing outside this Compose file and will be used for container networking. It allows the API service to integrate with other containers or services on this network, including the Traefik proxy.

Important Implementation Details

• Live Reloading with Reflex: Using reflex to watch source code changes and trigger regeneration of API specs and re-run the API server enables rapid development without manual container restarts.

• Swagger/OpenAPI Spec Generation: Automatically generates up-to-date API documentation based on code annotations, facilitating easier API client generation, documentation, and testing.

• Traefik Integration via Labels: The labels define routing rules and service ports, allowing Traefik to route incoming HTTP requests to the API container based on hostname and manage load balancing.

• Volume Mounting for Development: Mounting source code and Go module cache from the host ensures that changes are instantly reflected inside the container, and dependencies do not need to be re-downloaded each time.

Interaction with Other System Components

• Traefik Proxy:

  • The API service is integrated with Traefik through Docker labels. Traefik listens for containers with traefik.enable=true and routes requests to them based on rules.

  • Incoming HTTP requests to api.thorchain.localhost are routed by Traefik to port 3000 on this container.

• Developer Host Environment:

  • Source code is shared between the host machine and container via volume mounts, enabling developers to edit code on the host and see instant results.

• Go Module Cache:

  • Sharing module cache avoids redundant downloads and speeds up builds.

• Potential Other Services on thorchain Network:

  • The thorchain_default network may include other Thorchain services or databases that the API communicates with.

Usage Example

To start the Thorchain API service locally using this Compose file:

docker-compose -f docker-compose.yml up

• This will start the API container, which will watch for file changes, regenerate Swagger specs, and run the API server.

• You can then access the API at http://api.thorchain.localhost (assuming your local DNS or /etc/hosts is set up accordingly).

• Modify Go source code files under pkg, internal, or thorchain directories, and reflex will automatically rebuild and restart the API service.

Visual Diagram: Docker Compose Service & Network Structure

flowchart TD
    subgraph DockerCompose
        direction TB
        api[api Service\nImage: unchained-local-go]
        traefik[Traefik Proxy]
    end

    subgraph Host
        src[Host Source Code\n(../..)]
        gocache[Go Module Cache\n($GOPATH/pkg/mod/cache)]
    end

    subgraph Network[thorchain_default Network]
        api
        traefik
    end

    src -->|Volume Mount| api
    gocache -->|Volume Mount| api
    traefik -->|Routes to port 3000| api

Summary

This `docker-compose.yml` file sets up a development environment for the Thorchain API service with:

• Containerized Go API server

• Live code recompilation using reflex

• Automatic Swagger spec generation

• Integration with Traefik reverse proxy for hostname-based routing

• Shared volumes for source code and Go module cache

• Connection to an external Docker network for service communication

It facilitates rapid development and seamless integration into the larger Thorchain ecosystem via Docker networking and proxy configuration.