alex
2e156fc534
The post-creation 'docker network connect' was failing silently for unknown reasons (race condition, container state, or Docker internals). Instead of fighting with this, we now inject the backend network directly into the compose file before 'docker compose up'. Docker Compose then attaches the container to the network atomically during creation. - apps/api/src/api/tool_instances.py: new _ensure_backend_network_in_compose() adds 'networks: [backend_name]' to the service and declares the network as external at the top level - apps/api/src/api/tool_instances.py: call _ensure_backend_network_in_compose() in both start_instance and restart_instance, right after _ensure_container_name_in_compose() - apps/api/src/api/tool_instances.py: removed connect_container_to_network import and call entirely - apps/api/src/api/tool_instances.py: import get_backend_network_name from docker module for use in the new helper Quality gates: ruff clean
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]