alex
37ccaa4fdc
Service organization (19 files moved into 6 subpackages): - services/instance/ — event_bus, health_monitor, lifecycle_hooks - services/config/ — config_profile_resolver - services/git/ — clone, git_operations, git_service - services/build/ — docker_build, manifest_compiler - services/terminal/ — terminal_manager, terminal_session - services/shared/ — correlation, file_service, notification_service, permission_fixer, readiness_probe, ssh_keys, tunnel, workspace_manager API router organization (16 files moved into 6 subpackages): - api/tool/ — tool_instances, tool_types, tool_definitions, tool_types_validation, sessions (extracted from tool_instances) - api/config/ — config_profiles, user_config - api/workspace/ — workspaces, workspace_files, workspace_git, workspace_instances - api/user/ — users, auth, ssh_keys - api/project/ — projects, git_repositories - api/system/ — health, events, notifications, dashboard, terminal, instance_proxy Updated main.py imports and all __init__.py re-exports. Sessions router extracted from tool_instances.py into api/tool/sessions.py. Quality gates: py_compile passed, ruff passed.
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]