Install Ballet on one host
==========================

The compose installation runs Ballet's services as containers on one
Linux host with Docker Engine: Core (with the web UI), Knowledge, the LLM
gateway and an agent that runs coding-agent sessions as processes in its
own container (:doc:`/reference/agents`). Ballet needs no Docker socket.

Requirements
------------

- Linux with Docker Engine and the Compose plugin (``docker compose``).
  The services use the host network (``network_mode: host``); with
  Docker Desktop, enable host networking in its settings.
- Free ports 8080 (Core), 8081 (Knowledge), 8082 (gateway), 8083
  (agent metrics), 9090 (Prometheus), 3000 (Grafana), and 8180 for the
  development Keycloak.
- An Anthropic API key for the projects, and a git token for their
  repositories.

Start
-----

.. code-block:: bash

   git clone https://github.com/denyszorinets/ballet.git && cd ballet
   docker compose -f deploy/compose.yaml up -d --build

This builds the images (``make images`` builds them too) and starts the
services without authentication (see below for several users). The agent
image, ``ballet-agent``, has git, Claude Code and common build tools;
sessions run in it as the user ``ballet``. Extend it for your projects'
toolchains and set ``BALLET_AGENT_IMAGE`` to your image.

Open http://localhost:8080 on the host — no sign-in: you are the local
user. Then, as in :doc:`run-locally`:

#. create an organization and a project;
#. store the organization's Anthropic key (organization page → *LLM credentials*);
#. in the project settings, set the repository and a git token;
#. add tickets — or plan them with the planner — and move them to
   *Ready*.

Configuration
-------------

Every service reads its ``BALLET_*`` environment variables
(:doc:`/reference/configuration`); ``deploy/compose.yaml`` sets the
installation-specific ones and takes these from the environment or an
``.env`` file next to it:

``BALLET_OIDC_ISSUER_URL``
   Your identity provider's issuer. Empty (the default): no
   authentication — one local user, and Core listens on ``localhost``
   only. Set it for several users: register the ``ballet-web`` public
   client with ``http://<host>:8080/*`` as redirect URI
   (:doc:`configure-oidc`). To try it with the development Keycloak and
   its demo users (``alice`` / ``alice``): ``BALLET_OIDC_ISSUER_URL=http://localhost:8180/realms/ballet
   docker compose -f deploy/compose.yaml --profile keycloak up -d``.

``BALLET_PLATFORM_ADMINS``
   Claim matchers that are platform admins, e.g.
   ``groups:ballet-admins``.

``BALLET_ANTHROPIC_URL``
   Anthropic API base URL (default ``https://api.anthropic.com``).

``BALLET_AGENT_IMAGE``
   The agent image (default ``ballet-agent``), e.g. one extending it with
   your projects' toolchains.

``BALLET_AGENT_NAME``, ``BALLET_AGENT_CAPACITY``
   The agent's name and how many sessions it runs at once (default 2).
   Sessions share the agent's container, each in its own workspace.

``BALLET_LOG_LEVEL``
   ``debug``, ``info`` (default), ``warn`` or ``error``.

Monitoring
----------

The installation includes Prometheus (http://localhost:9090), scraping
every service's ``/metrics`` (:doc:`/reference/metrics`), and Grafana
(http://localhost:3000, ``admin`` / ``BALLET_GRAFANA_PASSWORD``, default
``admin``) with three dashboards in the *Ballet* folder:

**Ballet · Delivery**
   Tickets done and failed, lead time, rework (loops per ticket), stage
   outcomes, pipelines in progress and what they wait for, questions and
   how fast they are answered — by planner or humans.

**Ballet · LLM usage**
   Tokens and requests by organization, project, model and token type;
   refused or failed requests (for example over budget).

**Ballet · Platform**
   Services up, durable jobs and dead jobs, runs and session durations,
   versions.

Every dashboard filters by organization and project. Prometheus keeps 30 days
(``BALLET_METRICS_RETENTION``). The dashboards are generated by
``deploy/monitoring/dashboards.py`` (``make dashboards``); edit that
script, not the JSON.

State and backups
-----------------

All state lives in the ``ballet-data`` volume: Core's and Knowledge's
SQLite databases, the token signing keys, the key encrypting stored
credentials, and the service tokens. Back it up as a whole, with the
services stopped:

.. code-block:: bash

   docker compose -f deploy/compose.yaml stop
   docker run --rm -v ballet_ballet-data:/data -v "$PWD":/backup alpine \
     tar czf /backup/ballet-data.tgz -C /data .
   docker compose -f deploy/compose.yaml start

Upgrades
--------

.. code-block:: bash

   git pull
   docker compose -f deploy/compose.yaml up -d --build

Database migrations run when the services start. Pipelines in progress
continue (:ref:`reference-pipelines-recovery`).

Security notes
--------------

- With host networking the services listen on all interfaces: allow only
  port 8080 (or a TLS reverse proxy in front of it), and Grafana's 3000
  if you use it, through the host's firewall. The gateway and Knowledge
  are only needed by agent sessions on the same host; Prometheus only
  by Grafana.
- Agent sessions run on the host network as the unprivileged user
  ``ballet`` in the agent container: they can reach every service
  listening on the host.
- The development Keycloak and its demo users are for trying Ballet;
  use your own identity provider for real use.