NinesDocumentation
Search becomes available when JavaScript loads. All chapters are listed in the navigation.
GitHub
Browse documentation
View Markdown

Docker Compose

Use the repository root and a current Docker installation with Compose.

  • This deployment runs one server and PostgreSQL 17, binds the UI to localhost and stores the database in its own named volume.
  • The image is built from source; no published registry image is assumed.

Login credentials

  • Web username: admin.
  • Web password: NINES_BOOTSTRAP_PASSWORD in your private .env. There is no fixed persistent password.
  • Database password: POSTGRES_PASSWORD in .env, used only by PostgreSQL and the server connection.
  • API key: API_TOKEN in .env, used separately for automation.
  • The setup command below generates these values. admin / admin belongs to in-memory -demo mode and the separate loopback playground. It is not the persistent Compose password.

Start a persistent workspace

sh
git clone https://github.com/ishantanu/nines.git
cd nines
python3 scripts/setup-local.py
  • This creates .env with private file permissions and independent random API, database and bootstrap credentials.
    • It refuses to replace an existing file. Keep .env outside Git.
    • For manual setup, copy .env.example and replace every credential placeholder; the bootstrap password must be 12–72 bytes and the database password must be URL-safe. No model provider is required.
sh
docker compose -p nines up --build -d
docker compose -p nines ps
curl --fail http://127.0.0.1:8080/healthz
docker compose -p nines logs --tail=100 platform
  • Open localhost:8080 and sign in as admin with NINES_BOOTSTRAP_PASSWORD from .env. This is server-authenticated login.
    • Use Access control → Users for profiles, passwords and tenant roles. admin / admin applies only to the separate synthetic -demo mode. Initial persistent data is empty.
    • In a separate terminal, inject the API token without including it in shell history:
sh
# Read interactively, or inject through a secret manager.
read -r -s NINES_API_KEY
export NINES_API_KEY
make cli
bin/nines config set-context local --server http://127.0.0.1:8080 --tenant default
bin/nines get slos --context local --agent
bin/nines plan --context local -f examples/api-availability.slo.yaml --agent
# Review the plan. For a new SLO, creation expects revision zero.
bin/nines apply --context local -f examples/api-availability.slo.yaml --expected-revision 0 --agent
  • The example queries require suitable instrumentation and a configured source to produce observations. Applying the YAML does not create request metrics.

Connect Prometheus or Mimir

  • Legacy single-source evaluation reads PROMETHEUS_URL or MIMIR_URL from .env; configure one, then recreate the server.
    • A provider on the host is not reachable as localhost inside the container.
    • Use a reachable service name or an explicitly configured host gateway.
  • For owner-managed query connections, set NINES_SOURCE_HOSTS to exact approved hostnames in .env, recreate platform, then use Telemetry connections → Add telemetry connection. scripts/setup-local.py supplies the private encryption key used for saved bearer tokens.
    • Keep this key with your protected recovery material.
    • Mimir organizations must also be authorized in trusted tenant configuration.
    • Saving a source does not deploy rules or create an upstream metrics tenant.
  • For a complete example with rule volumes, reloads, Mimir ingestion and two severity policies, use the separate integration playground.

Named tenants and SSO

Named sources, ruler destinations and custom identity configuration require mounted files. Use an additional Compose file such as:

yaml
services:
  platform:
    env_file:
      - ${NINES_RUNTIME_ENV_FILE:?Set an absolute runtime environment file path}
    environment:
      TENANTS_FILE: /etc/nines/tenants.yaml
      AUTH_CONFIG_FILE: /etc/nines/auth.yaml
    volumes:
      - ${NINES_CONFIG_DIR:?Set an absolute config directory}/tenants.yaml:/etc/nines/tenants.yaml:ro
      - ${NINES_CONFIG_DIR:?Set an absolute config directory}/auth.yaml:/etc/nines/auth.yaml:ro
  • The default server already mounts local-account configuration.
    • This override selects your custom auth file instead.
    • Keep this override and its secrets outside Git.
    • Make the YAML readable by container UID 65532.
    • The runtime environment file supplies every secret referenced by those YAML files.
    • The base Compose file still requires its API_TOKEN and database password.
    • Explicit environment entries take precedence over the runtime file.
    • With TENANTS_FILE, grant access using the credentials declared in that file. See identity and tenants.
sh
docker compose -p nines -f compose.yaml -f /etc/nines/identity.compose.yaml up -d --build
  • For a shared deployment, use an HTTPS reverse proxy and set NINES_PUBLIC_URL to its origin.
    • Custom OIDC configuration must use the same public origin.
    • Keep port 8080 bound to loopback or a private proxy network. The Linux guide includes a proxy example.

Stop, upgrade and back up

sh
docker compose -p nines stop platform
docker compose -p nines start platform
  • PostgreSQL applies POSTGRES_PASSWORD during initialization of an empty volume. Changing the environment value alone does not rotate a retained database-role password; update the role through an authenticated database administration session and keep the server environment synchronized.
  • Stopping or running docker compose down without --volumes retains database storage.
    • Do not use down --volumes for an instance whose data you need.
    • Follow the backup and upgrade guide before rebuilding a retained instance.

Confirm the install

  1. Sign in, create a viewer under Access control → Users, and verify its restricted access in a separate browser session.
  2. Add or configure a telemetry connection and test it. Apply an SLO whose queries match real metrics.
  3. Open its Integration status and Performance tabs. Review the Rules plan before applying it, then confirm external evaluation.
  4. Restart platform and confirm accounts, definitions and history are retained.
  • To use another host port, set NINES_PORT and the matching NINES_PUBLIC_URL together.
    • Changing the bootstrap environment password does not reset an existing account; use the Users tab.
    • A token-only or SSO-only deployment can replace the auth mount and AUTH_CONFIG_FILE through the override above.