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. The server includes an OAuth proxy — MCP clients authenticate through a browser redirect to your OIDC provider, no manual token management needed.

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
      HIVETRACK_MCP_TRANSPORT: http
      HIVETRACK_MCP_EXTERNAL_URL: https://your-mcp-url
    depends_on:
      - hivetrack

AI tools connect to https://your-mcp-url/mcp using the MCP Streamable HTTP transport. The server handles OAuth automatically — clients are redirected to your OIDC provider to authenticate in the browser. Callers with an existing Bearer token (CI, service accounts) can also pass it directly via the Authorization header.

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 (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.