Skip to content
Chinmina Chinmina

Local development

Running Chinmina locally is a crucial part of successfully contributing. Since Chinmina acts as a bridge between Buildkite and GitHub though, local execution has similar prerequisites to installing it into a standard environment.

This guide will walk you through the setup of GitHub and Buildkite, then introduce running the server locally in Docker. It is possible to run the executable directly, but this tends to make running the server more difficult.

Setting up your local environment

Required tools:

  1. direnv for local environment configuration
  2. Docker (docker compose) to run the server on the local machine.
  3. Go language and toolchain.

Setting up GitHub and Buildkite

Refer to the “Getting Started” guide’s sections on Buildkite and GitHub for the creation of the Buildkite API key and the GitHub application.

Collect the configuration values as suggested.

Additionally, to run alongside Chinmina, there are several Buildkite Agent containers that are started. These will require the following environment variables to be forwarded in order to run correctly:

BUILDKITE_AGENT_TOKEN

The agent token available from Buildkite when setting up a queue.

BUILDKITE_AGENT_TAGS

Used in testing only. These comma-separated, key-value pairs should be provided in order for the created agent containers to accept jobs.

Server configuration

  1. Setup your local environment by creating a .envrc.local file, using the template provided in the repository’s .envrc file. This file’s contents will override any defaults set in .envrc.

  2. Using the “Getting started” guide’s essential configuration section, fill in the suggested values in .envrc.local.

  3. Run direnv allow to bring the updated configuration into the environment.

Running the server

This project uses the venerable make as a build tool.

Run:

  • make build to build the executables
  • make test to … run the tests
  • make docker to start the system with Docker Compose, running Chinmina, the Buildkite agent and Jaeger.

When compose is running, the Buildkite agents will process jobs from pipelines in your test organization, and authenticate to GitHub. Jaeger is accessible to observe the Chinmina telemetry.