Headquarter

A self-hosted platform for managing projects, git repositories, and development tools with OAuth2 authentication.

Overview

Headquarter provides a centralized workspace for development teams to:

• Manage projects and their associated git repositories
• Browse repository files and view git history
• Spawn development tools (VS Code Server, Jupyter Notebook, etc.)
• Manage SSH keys and user preferences

Features

Project Management

• Create and manage projects
• View all projects in a dashboard
• Click any project to open its workspace

Git Repository Management

• Initialize bare repositories
• Clone repositories (including mirror clones)
• Smart URL parsing (converts browser URLs to git URLs)
• View repository history and commit details

Repository Workspace

• Browse files and directories
• View file contents with syntax highlighting
• Switch between branches
• Quick file editing with automatic commits

Git History Visualization

• View commit history with branch graph
• See commit details, statistics, and diffs
• Filter by branch

Authentication

• OAuth2 via Authentik
• Session-based authentication
• User profile management

Tool Management

• Built-in tool types (code-server, jupyter-notebook)
• Create custom tool types with Docker Compose templates
• Template validation

User Settings

• Theme selection (system/light/dark)
• Git identity configuration
• Default editor preference

SSH Key Management

• Generate Ed25519 key pairs
• Copy public keys to clipboard
• Delete keys

Quick Start

Prerequisites

• Docker and Docker Compose
• Git

Local Development

1. Clone the repository:

   git clone <repository-url>
   cd headquarter
   

2. Set up environment:

   cp .env.example .env
   # Edit .env with your settings
   

3. Start services:

   docker compose up -d
   

4. Access the application:

   • Frontend: http://localhost:5173
   • API: http://localhost:8000
   • API Docs: http://localhost:8000/docs

Production Deployment

See Deployment Guide for production setup with Traefik and Authentik.

Tech Stack

Backend

• FastAPI - Python web framework
• SQLAlchemy - ORM with async PostgreSQL support
• Pydantic - Data validation
• Alembic - Database migrations
• python-jose - JWT handling

Frontend

• React - UI library
• TypeScript - Type safety
• Vite - Build tool
• React Router - Client-side routing

Infrastructure

• Docker - Containerization
• PostgreSQL - Database
• Traefik - Reverse proxy (production)
• Authentik - Identity provider

Documentation

• User Guide - Feature documentation
• API Reference - API endpoints
• Architecture - System design
• Deployment - Setup guides
• Development - Contributing

Project Structure

.
├── apps/
│   ├── api/              # FastAPI backend
│   │   ├── src/
│   │   │   ├── api/      # API routes
│   │   │   ├── auth/     # Authentication
│   │   │   ├── models/   # Database models
│   │   │   └── utils/    # Utilities
│   │   ├── tests/        # Test suite
│   │   └── Dockerfile
│   └── web/              # React frontend
│       ├── src/
│       │   ├── api/      # API clients
│       │   ├── components/# UI components
│       │   └── pages/    # Page components
│       └── Dockerfile
├── docs/                 # Documentation
├── docker-compose.yml    # Development setup
├── docker-compose.traefik.yml  # Production setup
└── Makefile             # Common commands

Development

Backend Development

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

Frontend Development

cd apps/web
npm install
npm run dev

Running Tests

# Backend tests
make test

# Frontend tests
make test-web

# All quality gates
make lint
make typecheck

Configuration

Key environment variables:

Variable	Description	Default
API_DOMAIN	API domain	localhost
WEB_DOMAIN	Web domain	localhost
AUTHENTIK_DOMAIN	Authentik domain	-
AUTHENTIK_CLIENT_ID	OAuth client ID	-
AUTHENTIK_CLIENT_SECRET	OAuth client secret	-
DATABASE_URL	PostgreSQL URL	-
JWT_SECRET	JWT signing secret	-
REPO_BASE_PATH	Repository storage path	/data/repos

See Environment Variables for complete list.

License

[License information]