---
title: Getting started
description: What you need to prepare to get Chinmina going.
---
Chinmina itself is a simple service, but it sits in the middle of an ecosystem.
This means that a working installation requires a number of setup items.

## Requirements

Before you start, there are a few things you'll need to have:

1. A Buildkite organization, and a user with sufficient access to create an API
   token that can be used to get the details of any pipeline that is expected to
   be built.
2. A GitHub organization, and a user with sufficient permissions to create a
   GitHub App and install it into the organization.
3. Ability to deploy a server that can be accessed by the build agents (for
   example, an ECS service)
4. Ability to allow Buildkite agents to download and use a custom plugin *or*
   ability to add a plugin to the default settings of the Buildkite agents.

## As you go

Values to save for required configuration are marked in the instructions below
like this: `📝 ENV_VAR_NAME`.

Collect these values as you proceed so they can be provided for your
installation's configuration.

## Buildkite setup

Create an API key with access to the REST API **only** with access to the
`read_pipelines` scope. Save as `📝 BUILDKITE_API_TOKEN`.

> \[!TIP]
>
> Use a "bot" user to create the token if you can, as this will not be affected
> when personnel in your organization change.

## GitHub setup

1. Create an application in your GitHub organization, adding `contents:read` as
   the repository permissions.

   Collect the "Application ID" of the application created. This is found in the
   "About" section of the "General" page of the application in the GitHub UI.

   Save as `📝 GITHUB_APP_ID`

2. Create and save a private key for the application.

   Save as `📝 GITHUB_APP_PRIVATE_KEY`.

3. Install the application into the GitHub organization

   Choose the repositories the application will have access to. This is the
   limit of the resources that the application can vend tokens for.

   Collect the "Installation ID" of the application in your organization. The Installation
   ID is the last segment of the URL on the installation configuration page.

   Save as `📝 GITHUB_APP_INSTALLATION_ID`

> \[!TIP]
>
> For a production installation on AWS it is strongly recommended that you upload
> your private key to KMS, as documented in [Protecting the GitHub private key
> ](./kms.md)

## Chinmina Bridge setup

The server is a Go application expecting to read configuration from environment
variables, and can be deployed to a container runtime environment or a server.
Container distribution is recommended.

It is possible to run multiple instances together in a cluster. While the
internal cache is not shared between instances, this will only affect the
latency, not the correctness.

#### Essential configuration

A minimal configuration of the service requires at least the configuration
below. See the [Configuration](../reference/configuration.md) reference for details of all
configuration.

* [`JWT_BUILDKITE_ORGANIZATION_SLUG`](../reference/configuration.md#jwt_buildkite_organization_slug)

  The slug of your Buildkite organization. This is the identifier of your
  organization that appears in your Buildkite URLs.

* [`JWT_AUDIENCE`](../reference/configuration.md#jwt_audience)

  The expected value of the `aud` claim in the JWT. Describes the intended
  audience of the issued JWT token, and guards against token reuse. While this
  is optional, it's a good idea for this to be unique to the installation.

* [`BUILDKITE_API_TOKEN`](../reference/configuration.md#buildkite_api_token)

  The API token created for pipeline metadata lookups. **Store securely and
  provide to the container securely.**

* **Either**:
  * [`GITHUB_APP_PRIVATE_KEY_ARN`](../reference/configuration.md#github_app_private_key_arn)

    It is **strongly** recommended to [store the private key in AWS KMS](./kms.md)
    and provide the ARN of the key here. This will allow Chinmina to sign tokens
    but protects the key from extraction and misuse.

  * [`GITHUB_APP_PRIVATE_KEY`](../reference/configuration.md#github_app_private_key) **Use only if KMS is not
    available.**

    The PEM formatted private key of the created GitHub app. **Store securely and
    provide to the container securely.** This is a highly sensitive credential.

* [`GITHUB_APP_ID`](../reference/configuration.md#github_app_id)

  The application ID of the GitHub application created above.

* [`GITHUB_APP_INSTALLATION_ID`](../reference/configuration.md#github_app_installation_id)

  The installation ID of the created GitHub application into your organization.

The service will start (by default) on port 8080, but this is
[configurable](../../reference/configuration.md#server_port) if necessary.
Generally speaking, this is best handled via container port mapping.