alex
d2b6bba15c
The API container used a named Docker volume (repo_data:/data/repos) for storing repositories. When creating tool instances with direct mount mode, the API told Docker to bind-mount /data/repos/<repo>:/workspace into the tool container. But the Docker daemon resolves bind-mount paths on the HOST filesystem, not inside the API container. Since the host had no /data/repos (the repos only existed inside the named volume), tool containers mounted empty directories. Changed both compose files to use a host bind mount (/data/repos:/data/repos) instead of a named volume. This ensures: - The API container and tool containers both see the same /data/repos path - Bind mounts from /data/repos into tool containers work correctly For existing installations: repos previously stored in the repo_data named volume should be copied to /data/repos on the host before restarting the stack. Quality gates: compose file syntax valid
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
-
Clone the repository:
git clone <repository-url> cd headquarter -
Set up environment:
cp .env.example .env # Edit .env with your settings -
Start services:
docker compose up -d -
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]