Getting started

Deploy Hivetrack with Docker Compose in under five minutes.

Prerequisites

Docker 24+ with the Compose plugin (or docker-compose v2)
PostgreSQL 16+ — or use the Compose file below which includes one
An OIDC provider — Hivetrack uses OIDC for all authentication. Any spec-compliant provider works: Keycloak, Zitadel, Auth0, Keyline, or any other. You need a client with Authorization Code + PKCE flow enabled and the redirect URI set to https://your-hivetrack-url/oidc/callback.

Quick start

Generate Docker Compose, Docker CLI, or Kubernetes manifests with your values pre-filled. Includes optional Keyline OIDC provider and MCP server add-ons.

1. Create a `config.yaml`

Hivetrack is configured via a YAML file. Create config.yaml in the same directory as your docker-compose.yml and fill in your values.

config.yaml

server:
  host: 0.0.0.0
  port: 8086
  external_url: https://hivetrack.example.com
  allowed_origins:
    - https://hivetrack.example.com

database:
  url: postgres://hivetrack:changeme@postgres:5432/hivetrack?sslmode=disable

oidc:
  authority: https://your-oidc-provider.example.com
  client_id: hivetrack

initial_admin:
  email: admin@example.com

# Optional: email notifications
# email:
#   smtp_host: smtp.example.com
#   smtp_port: 587
#   smtp_user: noreply@example.com
#   smtp_password: secret
#   from_address: "Hivetrack <noreply@example.com>"

2. Create a `docker-compose.yml`

The compose file mounts your config into the container.

docker-compose.yml

services:
  postgres:
    image: postgres:17-alpine
    restart: unless-stopped
    environment:
      POSTGRES_USER: hivetrack
      POSTGRES_PASSWORD: changeme
      POSTGRES_DB: hivetrack
    volumes:
      - postgres_data:/var/lib/postgresql/data
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U hivetrack"]
      interval: 5s
      timeout: 5s
      retries: 10

  hivetrack:
    image: ghcr.io/the127/hivetrack:latest
    restart: unless-stopped
    ports:
      - "8086:8086"
    volumes:
      - ./config.yaml:/app/config.yaml
    depends_on:
      postgres:
        condition: service_healthy

volumes:
  postgres_data:

3. Start the stack

shell

docker compose up -d

4. Open Hivetrack

Navigate to http://localhost:8086 (or your configured external URL). Sign in via your OIDC provider. The first user whose email matches initial_admin.email automatically receives the instance_admin role.

5. Create your first project

Once signed in, click New project. Choose an archetype:

Software — for internal engineering teams. Includes sprints, backlog, milestones, and a kanban board.
Support — for customer-facing issue tracking. Enables public email submission and token-based issue tracking for external users.

Configuration reference

All configuration is set via a config.yaml file mounted at /app/config.yaml inside the container.

Note on environment variables: Hivetrack supports env var overrides using the HIVETRACK_ prefix, where underscores replace dots (e.g. server.port → HIVETRACK_SERVER_PORT). However, config keys that themselves contain underscores (like external_url, client_id, smtp_host) cannot be set via env vars because the underscore in the key collides with the nesting separator. Use config.yaml for these fields.

Config path	Description	Default
`server.host`	Interface to bind to	0.0.0.0
`server.port`	HTTP port to listen on	8086
`server.external_url` required	Publicly reachable URL (used in email links)	—
`server.allowed_origins`	CORS allowed origins (list)	(same as external_url)
`database.url` required	PostgreSQL connection string	—
`oidc.authority` required	OIDC provider authority URL (issuer)	—
`oidc.client_id` required	OIDC client ID for this Hivetrack instance	—
`oidc.claim_mappings.email`	JWT claim for user email	email
`oidc.claim_mappings.name`	JWT claim for display name	name
`oidc.claim_mappings.avatar`	JWT claim for avatar URL	picture
`initial_admin.email` required	First user with this email gets instance_admin	—
`email.smtp_host`	SMTP server hostname (leave empty to disable)	—
`email.smtp_port`	SMTP server port	587
`email.smtp_user`	SMTP username	—
`email.smtp_password`	SMTP password	—
`email.from_address`	Sender address for outgoing emails	—
`mcp.api_token`	Static API token for MCP server auth	—
`mcp.user_email`	Email to associate with MCP server actions	—

MCP server

Hivetrack ships with an MCP server that lets AI agents (Claude, etc.) interact with your issues, sprints, and projects. There are two ways to run it: locally for development, or self-hosted alongside Hivetrack.

Option A: Self-hosted (recommended for teams)

Add the MCP container to your Docker Compose stack. It connects to the Hivetrack API internally and serves the MCP protocol over HTTP. Auth is pass-through — each caller's OIDC Bearer token flows straight through to the Hivetrack API.

docker-compose.yml (add to existing)

  hivetrack-mcp:
    image: ghcr.io/the127/hivetrack-mcp:latest
    restart: unless-stopped
    ports:
      - "8080:8080"
    environment:
      HIVETRACK_URL: http://hivetrack:8086
    depends_on:
      - hivetrack

AI tools connect to http://your-host:8080/mcp using the MCP Streamable HTTP transport, passing their OIDC Bearer token in the Authorization header. No secrets or service accounts needed — the MCP server has zero credentials of its own.

Use the deployment config generator and check "Include MCP server" to get a complete Compose file.

Option B: Local binary (for individual developers)

Download the binary from the latest release, or install via Homebrew:

shell

brew install The127/tap/hivetrack-mcp

Add to your .claude/settings.json:

settings.json

{
  "mcpServers": {
    "hivetrack": {
      "command": "hivetrack-mcp",
      "env": {
        "HIVETRACK_URL": "https://your-hivetrack-url"
      }
    }
  }
}

On first use, the MCP server prompts you to authenticate via your OIDC provider's device flow. The local binary uses stdio transport and runs as your user.

Go client library

A typed Go client library is also available at github.com/the127/hivetrack/client for building custom integrations programmatically.