134 lines
4.8 KiB
Markdown
134 lines
4.8 KiB
Markdown
# Headquarter
|
|
|
|
Headquarter is a self-hosted workspace for managing projects, Git repositories, development-tool instances, SSH keys, and user preferences. It has a FastAPI API, a React frontend, PostgreSQL and Redis, and Authentik OAuth2/session authentication. Built-in tool definitions include code-server and Jupyter.
|
|
|
|
## Prerequisites
|
|
|
|
- Docker and Docker Compose for the provided local and production Compose stacks.
|
|
- Git for repository workflows.
|
|
- Python 3.11 or newer for manual API development.
|
|
- Node.js and npm for manual frontend development.
|
|
- An Authentik configuration for the authenticated deployment.
|
|
|
|
Production additionally requires an existing Traefik network and host Docker access for tool-instance management.
|
|
|
|
## Local Compose setup
|
|
|
|
1. Create a local environment file from the template and replace placeholder credentials before using a shared or production-like environment:
|
|
|
|
```bash
|
|
cp .env.example .env
|
|
```
|
|
|
|
2. Start the local stack:
|
|
|
|
```bash
|
|
docker compose up -d
|
|
```
|
|
|
|
The local Compose stack starts PostgreSQL, Redis, the API, and the web frontend. It publishes the web frontend at <http://localhost:3000>, the API at <http://localhost:8000>, and API documentation at <http://localhost:8000/docs>. PostgreSQL and Redis are also published on ports 5432 and 6379 respectively.
|
|
|
|
> **Authentication limitation:** this command does not configure the `AUTHENTIK_*`, `API_DOMAIN`, or `WEB_DOMAIN` values required for a verified authenticated flow. Treat authenticated local use as unsupported until those values are supplied through a documented local configuration.
|
|
|
|
Useful operational commands:
|
|
|
|
```bash
|
|
make up # Start services
|
|
make down # Stop services
|
|
make logs # Follow Compose logs
|
|
make migrate # Apply database migrations in the API container
|
|
make health # Show Compose service status
|
|
```
|
|
|
|
## Production deployment
|
|
|
|
The production Compose file is [`docker-compose.traefik.yml`](docker-compose.traefik.yml). It expects an existing external Traefik network (named `traefik` by default), configured domains, an Authentik client secret, and host paths for repositories, working copies, and tool instances.
|
|
|
|
After preparing `.env` with production values, deploy with:
|
|
|
|
```bash
|
|
docker compose -f docker-compose.traefik.yml up -d
|
|
```
|
|
|
|
The production API container mounts `/var/run/docker.sock` so it can manage tool instances. Treat this as privileged host access and restrict it appropriately. The deployment guide and supporting material are under [`docs/deployment/`](docs/deployment/).
|
|
|
|
## Manual development
|
|
|
|
### API
|
|
|
|
```bash
|
|
cd apps/api
|
|
python -m venv .venv
|
|
source .venv/bin/activate
|
|
pip install -e ".[dev]"
|
|
uvicorn src.main:app --reload
|
|
```
|
|
|
|
### Web
|
|
|
|
```bash
|
|
cd apps/web
|
|
npm install
|
|
npm run dev
|
|
```
|
|
|
|
## Tests and quality checks
|
|
|
|
The Make targets run commands in the Compose services:
|
|
|
|
```bash
|
|
make test
|
|
make test-unit
|
|
make test-integration
|
|
make test-system
|
|
make test-e2e
|
|
make lint
|
|
make typecheck
|
|
make build
|
|
```
|
|
|
|
The frontend test command is run directly from its package directory:
|
|
|
|
```bash
|
|
cd apps/web
|
|
npm run test
|
|
```
|
|
|
|
`make lint` runs API Ruff and mypy checks plus frontend linting; `make typecheck` runs API mypy and frontend typechecking. Neither target runs frontend tests.
|
|
|
|
## Configuration
|
|
|
|
Copy [`.env.example`](.env.example) to `.env` and replace its placeholder values rather than committing credentials. Key settings include:
|
|
|
|
| Setting | Purpose |
|
|
| --- | --- |
|
|
| `POSTGRES_USER`, `POSTGRES_PASSWORD`, `POSTGRES_DB` | PostgreSQL connection settings |
|
|
| `REDIS_URL` | Redis connection URL |
|
|
| `SESSION_SECRET`, `SESSION_TTL_HOURS` | Session signing and lifetime |
|
|
| `API_DOMAIN`, `WEB_DOMAIN` | Public API and web domains |
|
|
| `AUTHENTIK_DOMAIN`, `AUTHENTIK_CLIENT_ID`, `AUTHENTIK_CLIENT_SECRET` | Authentik OAuth configuration |
|
|
| `AUTHENTIK_APPLICATION_SLUG` | Authentik application path component |
|
|
| `VITE_API_BASE_URL`, `VITE_APP_URL` | Frontend build-time public URLs |
|
|
| `REPO_BASE_PATH` | Repository storage path |
|
|
| `TRAEFIK_NETWORK` | Existing Traefik network for the production Compose stack |
|
|
|
|
The API reads `.env` settings and has development defaults, but defaults such as local credentials and session secrets are not suitable for production.
|
|
|
|
## Repository layout
|
|
|
|
```text
|
|
.
|
|
├── apps/
|
|
│ ├── api/ # FastAPI API, migrations, and tests
|
|
│ └── web/ # React/Vite frontend
|
|
├── docs/ # Architecture, API, feature, deployment, and development docs
|
|
├── e2e/ # Playwright end-to-end tests
|
|
├── docker-compose.yml # Local Compose stack
|
|
├── docker-compose.traefik.yml # Traefik deployment stack
|
|
└── Makefile # Compose, test, quality, and build commands
|
|
```
|
|
|
|
## License
|
|
|
|
No license file or declared license was found in this checkout.
|