# 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.