alex
4cc433a1b8
Old instances may have auto-generated Docker Compose container names that don't match instance.name.lower(), causing DNS resolution failures for the tunnel. Also, old instances may not be on the backend network. - apps/api/src/services/docker.py: add get_container_ip_on_network() and is_container_on_network() helpers - apps/api/src/services/tunnel.py: start_tunnel() and recreate_tunnel() now accept an optional target_url parameter to override the default name-based URL - apps/api/src/api/tool_instances.py: recreate_tunnel_endpoint now: 1. Looks up the tool container (by stored container_id or name) 2. Ensures it's connected to the backend network 3. Gets the container's IP on that network 4. Passes the IP as the explicit tunnel target This guarantees the tunnel can reach the tool container regardless of naming or network state. 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]