Fusion
875594d66d
- Add CommitPanel component for viewing changed files and committing - Show file status indicators (M/A/D/?) in file tree - Integrate git status with workspace for real-time updates - Add CSS styles for commit panel and status badges Part of git-control change implementation.
196 lines
4.7 KiB
Markdown
196 lines
4.7 KiB
Markdown
# 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
|
|
|
|
1. **Clone the repository:**
|
|
```bash
|
|
git clone <repository-url>
|
|
cd headquarter
|
|
```
|
|
|
|
2. **Set up environment:**
|
|
```bash
|
|
cp .env.example .env
|
|
# Edit .env with your settings
|
|
```
|
|
|
|
3. **Start services:**
|
|
```bash
|
|
docker compose up -d
|
|
```
|
|
|
|
4. **Access the application:**
|
|
- Frontend: http://localhost:5173
|
|
- API: http://localhost:8000
|
|
- API Docs: http://localhost:8000/docs
|
|
|
|
### Production Deployment
|
|
|
|
See [Deployment Guide](docs/deployment/) 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](docs/features/) - Feature documentation
|
|
- [API Reference](docs/api/) - API endpoints
|
|
- [Architecture](docs/architecture/) - System design
|
|
- [Deployment](docs/deployment/) - Setup guides
|
|
- [Development](docs/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
|
|
```bash
|
|
cd apps/api
|
|
python -m venv .venv
|
|
source .venv/bin/activate
|
|
pip install -e ".[dev]"
|
|
uvicorn src.main:app --reload
|
|
```
|
|
|
|
### Frontend Development
|
|
```bash
|
|
cd apps/web
|
|
npm install
|
|
npm run dev
|
|
```
|
|
|
|
### Running Tests
|
|
```bash
|
|
# 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](docs/deployment/environment.md) for complete list.
|
|
|
|
## License
|
|
|
|
[License information]
|