docker-compose.yml

Overview

This `docker-compose.yml` file defines the configuration for a Docker Compose application setup focusing on a single service named `api`. The primary purpose of this file is to orchestrate and run a Go-based API service (`unchained-local-go` image) within a Docker container. It leverages Traefik as a reverse proxy/load balancer to route HTTP requests to the API service based on the hostname.

Key functionalities:

• Runs a Go API service inside a container.

• Uses environment variables and volume mounts for caching and source code access.

• Configures Traefik labels for dynamic routing and load balancing.

• Uses a reflex-based command to watch for code changes, regenerate Swagger API specifications, and run the service.

• Connects the api service to an external Docker network called thorchain-v1_default.

Detailed Explanation

Services

api

• Purpose: Runs the API server for the thorchain-v1 module, automatically regenerating Swagger specs when relevant source files change and restarting the server.

• Image: unchained-local-go

  • This is a prebuilt Docker image presumably containing the Go runtime and application dependencies.

• Environment:

  • GOCACHE=/tmp: Sets the Go build cache directory to /tmp inside the container, likely to improve build times.

• Labels: (Traefik integration)

  • traefik.enable=true: Enables Traefik routing for this container.

  • traefik.http.routers.thorchain-v1-api.rule=Host(api.thorchain-v1.localhost): Routes HTTP requests with the host api.thorchain-v1.localhost to this service.

  • traefik.http.services.thorchain-v1-api.loadbalancer.server.port=3000: Informs Traefik that the service listens on port 3000 internally.

• Command:

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

  • Runs reflex to watch for file changes in directories matching the regex (pkg|internal|thorchain-v1).

  • Excludes files matching 'swagger' to avoid infinite loops.

  • On changes, it runs:

    1. Swagger spec generation for the thorchain-v1 coinstack.

    2. Runs the Go API server with environment variables loaded from .env.

  • This setup enables live reload and API spec regeneration for development efficiency.

• Working Directory: /app

  • The container's working directory is set to /app.

• Volumes:

  • ../..:/app: Mounts the source code from two levels up on the host into /app in the container, allowing live code updates.

  • $GOPATH/pkg/mod/cache:/go/pkg/mod/cache: Mounts the Go module cache from the host to avoid re-downloading dependencies inside the container.

• Networks:

  • Connects to the external network thorchain-v1_default.

Networks

• thorchain-v1:

  • External network named thorchain-v1_default.

  • This network is defined outside this compose file, allowing communication with other containers connected to the same network.

Usage Example

To start the API service with this `docker-compose.yml`:

docker-compose up api

This command will:

• Create or connect to the external network thorchain-v1_default.

• Pull or build the unchained-local-go image if not present.

• Start the container running the API.

• The service will be accessible at http://api.thorchain-v1.localhost via Traefik proxy.

Implementation Details and Algorithms

• Reflex File Watcher:

  • Reflex is used to monitor source code changes dynamically inside the container.

  • It watches for changes in directories relevant to the API (pkg, internal, thorchain-v1).

  • When changes are detected, it regenerates the OpenAPI (Swagger) JSON spec using the swagger generate spec command.

  • After spec regeneration, it runs the API server Go application with environment variables from .env.

• Swagger Spec Generation:

  • The Swagger JSON is generated with the swagger tool, targeting the coinstacks/thorchain-v1 directory.

  • The output is directed to coinstacks/thorchain-v1/api/swagger.json.

  • The command excludes the protoc-gen-openapiv2 and includes the -m flag for module-awareness.

• Traefik Integration:

  • Traefik is configured via Docker labels to:

    • Enable routing to this container.

    • Set routing rules based on the host header.

    • Define the internal service port for load balancing.

Interaction with Other Parts of the System

• Traefik Proxy:

  • This service depends on Traefik running in the same Docker environment to route requests.

  • Traefik uses the labels defined here to dynamically configure HTTP routers and services.

• External Network thorchain-v1_default:

  • The API service is attached to this network to communicate with other services or databases connected to the same network.

  • This external network enables modularity and communication beyond this single docker-compose.yml scope.

• Source Code and Go Module Cache:

  • The volume mounts link the host's source code and Go module cache into the container, enabling live development and dependency caching.

Mermaid Diagram

The following flowchart illustrates the startup and execution workflow of the `api` service in this Docker Compose file:

flowchart TD
    Start[Start Docker Compose]
    Start --> ConnectNet[Connect to external network: thorchain-v1_default]
    ConnectNet --> PullImage[Pull unchained-local-go image]
    PullImage --> CreateContainer[Create container with volumes and env]
    CreateContainer --> StartReflex[Start reflex file watcher]
    StartReflex --> WatchChanges[Watch source directories (pkg, internal, thorchain-v1)]
    WatchChanges -->|On change| GenerateSwagger[Generate Swagger spec]
    GenerateSwagger --> RunAPI[Run Go API server with .env]
    WatchChanges -->|No change| RunAPI
    RunAPI --> TraefikRouting[Traefik routes traffic to port 3000]

Summary

This `docker-compose.yml` file orchestrates a Go API service container with live reload and API documentation generation capabilities. It integrates tightly with a Traefik reverse proxy for routing and uses an external Docker network for broader connectivity. The reflex watcher automates the development workflow by regenerating Swagger specs and restarting the server on source changes, facilitating efficient iterative development.

End of Documentation for docker-compose.yml