Backend Modes

The proxy supports three backend modes, controlled by the BACKEND_MODE environment variable. The active backend is reported at the /health endpoint under the "backend" key.

curl https://forgejo-proxy.hochguertel.work/health
# {"status": "ok", "backend": "scrape"}

Modes

scrape (default)

The proxy scrapes the Forgejo web UI using per-request credentials supplied by the API caller via X-Webui-Username and X-Webui-Password headers. HTML pages or internal UI endpoints are accessed on behalf of the caller for each request.

When to use: Standard self-hosted Forgejo installations where the proxy has network access to the Forgejo instance.

Note

No admin credentials are stored in the proxy. Callers must supply their own Forgejo credentials when calling WebUI-backed endpoints. See the authentication guide for details.

Required config:

Variable	Description
FORGEJO_URL	Base URL of your Forgejo instance

environment:
  BACKEND_MODE: scrape
  FORGEJO_URL: https://forgejo.example.com

---

sqlite

The proxy reads Forgejo’s SQLite database file directly. This is faster than scraping but requires the proxy container to have filesystem access to the database.

When to use: Self-hosted Forgejo with a shared volume, or when scraping is unreliable due to UI changes.

Required config:

Variable	Description
FORGEJO_DB_PATH	Absolute path to Forgejo’s forgejo.db SQLite file

environment:
  BACKEND_MODE: sqlite
  FORGEJO_DB_PATH: /data/forgejo/forgejo.db
volumes:
  - forgejo_data:/data/forgejo:ro

---

adminer

The proxy uses the Adminer web UI to query a MariaDB database. This is designed for Forgejo instances hosted on PikaPods where direct database access isn’t available but Adminer is exposed.

When to use: PikaPods-hosted Forgejo, or any setup where Forgejo uses MariaDB and Adminer is accessible.

Required config:

Variable	Description
ADMINER_URL	URL of the Adminer instance
ADMINER_SERVER	Database server hostname
ADMINER_USER	Database username
ADMINER_PASSWORD	Database password
ADMINER_DB	Database name

environment:
  BACKEND_MODE: adminer
  ADMINER_URL: https://adminer.example.com
  ADMINER_SERVER: db
  ADMINER_USER: forgejo
  ADMINER_PASSWORD: secret
  ADMINER_DB: forgejo

Checking the Active Backend

curl -H 'Authorization: token YOUR_TOKEN' \
  'https://forgejo-proxy.hochguertel.work/health'

Response:

{
  "status": "ok",
  "backend": "scrape",
  "forgejo_url": "https://forgejo.example.com"
}