Configuration Guide

This guide covers all configuration options for Tracker.

Environment Variables

Tracker is configured primarily through environment variables. Below is a complete reference.

Database Configuration

Variable	Default	Description
`DB_HOST`	`localhost`	MongoDB hostname or IP address
`DB_PORT`	`27017`	MongoDB port
`DB_NAME`	`tracker`	Database name
`DB_USER`	-	MongoDB username (optional)
`DB_PASSWORD`	-	MongoDB password (optional)
`DB_AUTH_SOURCE`	`admin`	MongoDB authentication database
`DB_TIMEOUT`	`10s`	Connection timeout

Example:

DB_HOST=mongodb.example.com
DB_PORT=27017
DB_NAME=tracker_prod
DB_USER=tracker_user
DB_PASSWORD=secure_password

Server Configuration

Variable	Default	Description
`HTTP_PORT`	`8080`	HTTP/REST API and Web UI port
`GRPC_PORT`	`8765`	gRPC API port
`METRICS_PORT`	`8081`	Prometheus metrics port
`LOG_LEVEL`	`info`	Logging level: `debug`, `info`, `warn`, `error`
`LOG_FORMAT`	`json`	Log format: `json` or `text`

Example:

HTTP_PORT=9080
GRPC_PORT=9765
METRICS_PORT=9081
LOG_LEVEL=debug

Demo Mode

Variable	Default	Description
`DEMO_MODE`	`false`	Enable demo mode banner
`BUY_ME_COFFEE_URL`	-	Buy Me a Coffee link for demo banner

Example:

DEMO_MODE=true
BUY_ME_COFFEE_URL=https://www.buymeacoffee.com/yourname

Authentication

Variable	Default	Description
`AUTH_ANONYMOUS_PERMISSIONS`	all except `access:manage`	Comma separated permissions granted to unauthenticated callers. Set it to an empty value to require authentication everywhere. The default becomes empty in the next major release.
`AUTH_ADMIN_PASSWORD`	generated	Password of the initial `admin` account. Only used when no user exists yet. When unset, a random password is printed once in the logs.
`AUTH_SESSION_SECRET`	persisted in MongoDB	Base64 secret (32 bytes minimum) signing session cookies. Set it explicitly when running several replicas without a shared database secret.
`AUTH_SESSION_TTL`	`12h`	Session lifetime.
`AUTH_PUBLIC_URL`	-	Public URL of the UI. An `https` URL makes cookies `Secure`. Required with OIDC, where it is the base of the redirect URI (`scheme://host[:port]`, no path).
`AUTH_COOKIE_SECURE`	`false`	Force the `Secure` flag on cookies.
`AUTH_TRUST_PROXY`	`false`	Use the last entry of `X-Forwarded-For` as client IP for login rate limiting, and `X-Forwarded-Proto` to decide the request scheme. Only enable it behind a reverse proxy that appends the peer address to the header.
`AUTH_OIDC_ISSUER`	-	OpenID Connect issuer URL. Setting it enables single sign-on. `https` only (`http` for loopback). Must match the token `iss` exactly.
`AUTH_OIDC_CLIENT_ID`	-	OIDC client ID. Required with an issuer.
`AUTH_OIDC_CLIENT_SECRET`	-	OIDC client secret. Required with an issuer. Keep it in a secret store.
`AUTH_OIDC_SCOPES`	`openid profile email`	Requested scopes, space or comma separated.
`AUTH_OIDC_GROUPS_CLAIM`	`groups`	`id_token` claim carrying the groups used for team mapping.
`AUTH_OIDC_USERNAME_CLAIM`	`preferred_username`	`id_token` claim used as username, `email` as fallback.
`AUTH_OIDC_USER_PROVISIONING`	`true`	Create accounts at first OIDC login.
`AUTH_OIDC_TEAM_SYNC`	`true`	Synchronize teams from the groups claim at each login.
`AUTH_OIDC_BUTTON_LABEL`	`Single Sign-On`	Label of the login button (64 characters max).

When AUTH_ANONYMOUS_PERMISSIONS is set, its value is used as is, even when empty. When it is unset, the default is the read-only set event:read,catalog:read,lock:read,links:read if DEMO_MODE=true, otherwise every permission except access:manage (transitional default, with a startup warning).

See AUTHENTICATION.md for permissions, teams and API keys, and Single Sign-On for the OpenID Connect setup, redirect URI and identity provider recipes.

Example:

AUTH_ANONYMOUS_PERMISSIONS=event:read,catalog:read
AUTH_ADMIN_PASSWORD=change-me-at-first-login
AUTH_PUBLIC_URL=https://tracker.example.com

Example with OpenID Connect:

AUTH_PUBLIC_URL=https://tracker.example.com
AUTH_OIDC_ISSUER=https://keycloak.example.com/realms/main
AUTH_OIDC_CLIENT_ID=tracker
AUTH_OIDC_CLIENT_SECRET=<from your secret store>
# Redirect URI to register: https://tracker.example.com/api/v1alpha1/auth/oidc/callback

Slack Integration

Variable	Default	Description
`SLACK_EVENTS_CHANNEL_URL`	-	Slack channel URL for events

Example:

SLACK_EVENTS_CHANNEL_URL=https://yourworkspace.slack.com/archives/C123456

Frontend Configuration

Frontend configuration is done through environment variables prefixed with VITE_:

Variable	Default	Description
`VITE_API_BASE_URL`	`/api`	API base URL
`VITE_GRPC_WEB_URL`	-	gRPC-Web endpoint (if using)

Example (.env.local):

VITE_API_BASE_URL=https://api.tracker.example.com/api

Configuration Files

Docker Compose

Create a .env file in the same directory as docker-compose.yml:

# .env
DEMO_MODE=false
DB_NAME=tracker_production
SLACK_EVENTS_CHANNEL_URL=https://yourworkspace.slack.com/archives/C123456

Then reference in docker-compose.yml:

services:
  tracker:
    env_file:
      - .env
    environment:
      DB_HOST: mongodb
      DB_PORT: 27017

Kubernetes ConfigMap

apiVersion: v1
kind: ConfigMap
metadata:
  name: tracker-config
data:
  DB_HOST: "mongodb-service"
  DB_PORT: "27017"
  DB_NAME: "tracker"
  HTTP_PORT: "8080"
  GRPC_PORT: "8765"
  LOG_LEVEL: "info"

Kubernetes Secret

For sensitive data:

apiVersion: v1
kind: Secret
metadata:
  name: tracker-secrets
type: Opaque
stringData:
  DB_USER: "tracker_user"
  DB_PASSWORD: "secure_password"

Apply to deployment:

apiVersion: apps/v1
kind: Deployment
metadata:
  name: tracker
spec:
  template:
    spec:
      containers:
      - name: tracker
        envFrom:
        - configMapRef:
            name: tracker-config
        - secretRef:
            name: tracker-secrets

MongoDB Configuration

Connection String

Tracker supports MongoDB connection strings:

DB_CONNECTION_STRING=mongodb://user:password@host1:27017,host2:27017/tracker?replicaSet=rs0

Replica Set

For high availability:

DB_HOST=mongo1:27017,mongo2:27017,mongo3:27017
DB_REPLICA_SET=rs0
DB_NAME=tracker

Authentication

With authentication enabled:

DB_HOST=mongodb.example.com
DB_PORT=27017
DB_NAME=tracker
DB_USER=tracker_user
DB_PASSWORD=secure_password
DB_AUTH_SOURCE=admin

TLS/SSL

For secure connections:

DB_TLS_ENABLED=true
DB_TLS_CA_FILE=/path/to/ca.pem
DB_TLS_CERT_FILE=/path/to/cert.pem
DB_TLS_KEY_FILE=/path/to/key.pem

Logging Configuration

Log Levels

debug: Detailed debugging information
info: General informational messages (default)
warn: Warning messages
error: Error messages only

LOG_LEVEL=info

Log Format

JSON (recommended for production):

LOG_FORMAT=json

Text (human-readable for development):

LOG_FORMAT=text

Metrics Configuration

Tracker exposes Prometheus metrics on the metrics port.

Access metrics:

curl http://localhost:8081/metrics

Prometheus scrape config:

scrape_configs:
  - job_name: 'tracker'
    static_configs:
      - targets: ['tracker:8081']

Performance Tuning

Database Indexes

Tracker automatically creates indexes on startup. Monitor index usage:

# Connect to MongoDB
mongosh tracker

# Check indexes
db.events.getIndexes()
db.catalog.getIndexes()

Connection Pooling

Configure MongoDB connection pool:

DB_MAX_POOL_SIZE=100
DB_MIN_POOL_SIZE=10

Request Timeouts

HTTP_READ_TIMEOUT=30s
HTTP_WRITE_TIMEOUT=30s
GRPC_TIMEOUT=30s

Security

CORS Configuration

CORS_ALLOWED_ORIGINS=https://tracker.example.com,https://app.example.com
CORS_ALLOWED_METHODS=GET,POST,PUT,DELETE
CORS_ALLOWED_HEADERS=Content-Type,Authorization

Rate Limiting

RATE_LIMIT_ENABLED=true
RATE_LIMIT_REQUESTS_PER_SECOND=100

Example Configurations

Development

# .env.development
DB_HOST=localhost
DB_PORT=27017
DB_NAME=tracker_dev
HTTP_PORT=8080
GRPC_PORT=8765
LOG_LEVEL=debug
LOG_FORMAT=text
DEMO_MODE=true

Production

# .env.production
DB_HOST=mongodb-prod.example.com
DB_PORT=27017
DB_NAME=tracker
DB_USER=tracker_prod
DB_PASSWORD=${DB_PASSWORD}  # From secrets manager
HTTP_PORT=8080
GRPC_PORT=8765
LOG_LEVEL=info
LOG_FORMAT=json
DEMO_MODE=false
CORS_ALLOWED_ORIGINS=https://tracker.example.com
RATE_LIMIT_ENABLED=true

Docker Compose Production

version: '3.8'

services:
  mongodb:
    image: mongo:8
    restart: always
    environment:
      MONGO_INITDB_ROOT_USERNAME: admin
      MONGO_INITDB_ROOT_PASSWORD: ${MONGO_PASSWORD}
    volumes:
      - mongodb_data:/data/db
    networks:
      - tracker-network

  tracker:
    image: bananaops/tracker:latest
    restart: always
    environment:
      DB_HOST: mongodb
      DB_PORT: 27017
      DB_NAME: tracker
      DB_USER: admin
      DB_PASSWORD: ${MONGO_PASSWORD}
      DB_AUTH_SOURCE: admin
      LOG_LEVEL: info
      LOG_FORMAT: json
      DEMO_MODE: false
    ports:
      - "8080:8080"
      - "8081:8081"
      - "8765:8765"
    depends_on:
      - mongodb
    networks:
      - tracker-network

networks:
  tracker-network:
    driver: bridge

volumes:
  mongodb_data:

Troubleshooting

Configuration Not Applied

Check environment variables are set:
```
docker exec tracker env | grep DB_
```
Restart the service:
```
docker-compose restart tracker
```

Database Connection Failed

Verify MongoDB is accessible:
```
telnet mongodb.example.com 27017
```

Check credentials:

mongosh "mongodb://user:password@host:27017/tracker"

Port Conflicts

Change ports in configuration:

HTTP_PORT=9080
GRPC_PORT=9765
METRICS_PORT=9081

Next Steps

Installation Guide - Install Tracker
Development Guide - Set up development environment
User Guide - Learn how to use Tracker

Getting Help

🐛 Report Issues
💬 Discussions

FilesExpand file tree

CONFIGURATION.md

Latest commit

History

CONFIGURATION.md

File metadata and controls

Configuration Guide

Environment Variables

Database Configuration

Server Configuration

Demo Mode

Authentication

Slack Integration

Frontend Configuration

Configuration Files

Docker Compose

Kubernetes ConfigMap

Kubernetes Secret

MongoDB Configuration

Connection String

Replica Set

Authentication

TLS/SSL

Logging Configuration

Log Levels

Log Format

Metrics Configuration

Performance Tuning

Database Indexes

Connection Pooling

Request Timeouts

Security

CORS Configuration

Rate Limiting

Example Configurations

Development

Production

Docker Compose Production

Troubleshooting

Configuration Not Applied

Database Connection Failed

Port Conflicts

Next Steps

Getting Help