# Local development

## Start the foundation

Requirements: Docker with Compose v2, Go 1.26 or newer for host-side tests, and
ports 3000, 8080, and 2222 available.

```sh
cp .env.example .env
make up
```

Open Gitea at <http://localhost:3000>. The Hop control plane exposes health at
<http://localhost:8080/healthz> and readiness at
<http://localhost:8080/readyz>.

Gitea self-registration is enabled for this local stack. After creating the
first account, create an access token in Gitea and set `GITEA_API_TOKEN` in
`.env`, then restart the control plane:

```sh
docker compose up -d --force-recreate control-plane
```

## Link a repository

Create a repository in Gitea, then ask Hop to verify it through the Gitea API
and record the link:

```sh
set -a
. ./.env
set +a

curl --fail-with-body \
  -H "Authorization: Bearer $HOP_ADMIN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"owner":"YOUR_USER","name":"YOUR_REPOSITORY"}' \
  http://localhost:8080/api/v1/repositories/link
```

## Configure a webhook

In the Gitea repository, create a Gitea webhook with:

- target URL: `http://control-plane:8080/api/v1/gitea/webhooks`
- content type: `application/json`
- secret: the value of `HOP_GITEA_WEBHOOK_SECRET` in `.env`
- events: all events

The control plane verifies `X-Gitea-Signature` against the raw request body,
records each delivery exactly once, and refreshes repository metadata from the
signed payload.

## Useful commands

```sh
make test
make config
make logs
make down
```

To destroy local data as well as containers, run `docker compose down -v`.