alex
b55300ff6f
- Add TerminalSessionModel DB table with instance_id FK, name, status, created_at, last_activity_at, closed_at columns - Add Alembic migration for terminal_sessions table - Refactor TerminalManager to use composite key (instance_id, session_id) supporting up to 5 concurrent sessions per instance - Add create_session, get_session, get_sessions_for_instance, close_session - Preserve get_or_create_session for backward compatibility (default session) - Fix attach_websocket to only close sockets within same session - Add name (auto-generated 'Session N') and status tracking to TerminalSession - Add 7 unit tests for multi-session logic Quality gates: pytest (7 new passed, 174 total passed, 51 pre-existing failures)
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]