Headquarter

Headquarter is a self-hosted workspace for managing projects, Git repositories, development-tool instances, SSH keys, and user preferences. It has a FastAPI API, a React frontend, PostgreSQL and Redis, and Authentik OAuth2/session authentication. Built-in tool definitions include code-server and Jupyter.

Prerequisites

• Docker and Docker Compose for the provided local and production Compose stacks.
• Git for repository workflows.
• Python 3.11 or newer for manual API development.
• Node.js and npm for manual frontend development.
• An Authentik configuration for the authenticated deployment.

Production additionally requires an existing Traefik network and host Docker access for tool-instance management.

Local Compose setup

1. Create a local environment file from the template and replace placeholder credentials before using a shared or production-like environment:

   cp .env.example .env
   

2. Start the local stack:

   docker compose up -d
   

The local Compose stack starts PostgreSQL, Redis, the API, and the web frontend. It publishes the web frontend at http://localhost:3000, the API at http://localhost:8000, and API documentation at http://localhost:8000/docs. PostgreSQL and Redis are also published on ports 5432 and 6379 respectively.

Authentication limitation: this command does not configure the AUTHENTIK_*, API_DOMAIN, or WEB_DOMAIN values required for a verified authenticated flow. Treat authenticated local use as unsupported until those values are supplied through a documented local configuration.

Useful operational commands:

make up        # Start services
make down      # Stop services
make logs      # Follow Compose logs
make migrate   # Apply database migrations in the API container
make health    # Show Compose service status

Production deployment

The production Compose file is docker-compose.traefik.yml. It expects an existing external Traefik network (named traefik by default), configured domains, an Authentik client secret, and host paths for repositories, working copies, and tool instances.

After preparing .env with production values, deploy with:

docker compose -f docker-compose.traefik.yml up -d

The production API container mounts /var/run/docker.sock so it can manage tool instances. Treat this as privileged host access and restrict it appropriately. The deployment guide and supporting material are under docs/deployment/.

Manual development

API

cd apps/api
python -m venv .venv
source .venv/bin/activate
pip install -e ".[dev]"
uvicorn src.main:app --reload

Web

cd apps/web
npm install
npm run dev

Tests and quality checks

The Make targets run commands in the Compose services:

make test
make test-unit
make test-integration
make test-system
make test-e2e
make lint
make typecheck
make build

The frontend test command is run directly from its package directory:

cd apps/web
npm run test

make lint runs API Ruff and mypy checks plus frontend linting; make typecheck runs API mypy and frontend typechecking. Neither target runs frontend tests.

Configuration

Copy .env.example to .env and replace its placeholder values rather than committing credentials. Key settings include:

Setting	Purpose
POSTGRES_USER, POSTGRES_PASSWORD, POSTGRES_DB	PostgreSQL connection settings
REDIS_URL	Redis connection URL
SESSION_SECRET, SESSION_TTL_HOURS	Session signing and lifetime
API_DOMAIN, WEB_DOMAIN	Public API and web domains
AUTHENTIK_DOMAIN, AUTHENTIK_CLIENT_ID, AUTHENTIK_CLIENT_SECRET	Authentik OAuth configuration
AUTHENTIK_APPLICATION_SLUG	Authentik application path component
VITE_API_BASE_URL, VITE_APP_URL	Frontend build-time public URLs
REPO_BASE_PATH	Repository storage path
TRAEFIK_NETWORK	Existing Traefik network for the production Compose stack

The API reads .env settings and has development defaults, but defaults such as local credentials and session secrets are not suitable for production.

Repository layout

.
├── apps/
│   ├── api/                  # FastAPI API, migrations, and tests
│   └── web/                  # React/Vite frontend
├── docs/                     # Architecture, API, feature, deployment, and development docs
├── e2e/                      # Playwright end-to-end tests
├── docker-compose.yml        # Local Compose stack
├── docker-compose.traefik.yml # Traefik deployment stack
└── Makefile                  # Compose, test, quality, and build commands

License

No license file or declared license was found in this checkout.