---
id: operations
title: Operations
description: Health checks, the admin reindex endpoint, a troubleshooting playbook, and running two instances on one host.
tags: [admin, operations, monitoring]
lang: en
---

# Operations

## Health and readiness

| Endpoint | Meaning |
|---|---|
| `GET /healthz` | Always `200` if the process is running — no database access. |
| `GET /readyz` | `200` if a query against Postgres succeeds, `503` otherwise. Use this for orchestration readiness probes. |
| `GET /admin/status` | Bearer-token-protected (`F451_ADMIN_TOKEN`, see [[configuration-reference]]). Returns in-memory counters (`webhookErrors`, `indexerErrors`, `driftErrors`) and a `since` timestamp. The counters reset on every process restart — treat this as "is something wrong right now", not as a historical audit log. |

## Triggering a reindex

```bash
curl -X POST https://<host>/admin/reindex \
  -H "Authorization: Bearer $F451_ADMIN_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{}'
```

An empty body reindexes every configured space; `{"space":"<space-id>"}`
reindexes just one. The response reports success or failure per space —
`200` if at least one space succeeded, `502` only if all of them failed
(check `GET /admin/status` and the `api` logs next).

> [!NOTE]
> If OIDC sign-in is active, `/admin/*` routes need a valid session **in
> addition to** the bearer token — a plain `curl` call without a browser
> session behind it gets a reproducible `401`. Run admin calls from a
> browser context where you are already signed in (developer tools'
> network/fetch panel with the session cookie present), not from a bare
> terminal.

## Troubleshooting playbook

| Symptom | Likely cause |
|---|---|
| Every API route is reachable without signing in | `F451_OIDC_ISSUER` is unset — auth is intentionally off in that state. |
| Sign-in redirects to an error page after the identity provider | `F451_OIDC_REDIRECT_URL` (or the app registration's redirect URI) doesn't match the actual callback URL exactly. |
| Every save/publish/release fails with `403` | `F451_PUBLIC_BASE_URL` doesn't match the URL users actually browse to — the CSRF origin check rejects the mismatch. See [[configuration-reference]]. |
| A webhook call fails with `401` | `F451_WEBHOOK_SECRET_FORGEJO`/`_GITHUB` doesn't match the secret configured on the repository's webhook. |
| A page edited directly in Git takes a few minutes to show up | Expected — the drift job catches up within about 5 minutes if the webhook was missed. See [[spaces-and-git-providers]]. |
| `POST /admin/reindex` / `GET /admin/status` returns `503` | `F451_ADMIN_TOKEN` is unset — both endpoints are fail-closed without it. |
| `POST /admin/reindex` returns `401` from a plain terminal call | Missing session — see the note above. |
| The rate limits seem to apply to "everyone at once" instead of per person | `F451_TRUST_PROXY` is unset or wrong for the real proxy chain — see [[configuration-reference]]. |
| The same person appears as two different users | They signed in through two different methods (e.g. OIDC once, GitHub once) — see [[github-sign-in]]. Not a bug, a consequence of having no shared identity across methods. |
| A user reports "I don't see any spaces" | Their account is signed in but has no linked Forgejo/GitHub account yet, or that account lacks repository access — see [[sign-in-options]]. |

## Running a second instance on the same host

Both the Forgejo stack and the application stack expose their ports and
cookie naming as variables, so a second instance (for example a demo or a
staging copy) can run alongside the first without conflicting:

| Variable | What it separates |
|---|---|
| `F451_COOKIE_PREFIX` | Session cookie names — without a distinct value, two instances sharing a host would overwrite each other's cookies in the browser. |
| `F451_WEB_PORT` | Host port for the web UI. |
| `F451_DRAWIO_PORT` | Host port for the diagram editor. |
| `F451_FORGEJO_HTTP_PORT` / `F451_FORGEJO_SSH_PORT` | Host ports for the second Forgejo instance. |
| `F451_FORGEJO_ROOT_URL` | The second Forgejo instance's own public URL. |

Give the second instance's Git stack its own Compose project name
(`docker compose -p <name> ...`) so its containers and volumes don't
collide with the first instance's.