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 authenticates to the Forgejo web UI using an admin session (cookie-based) and scrapes HTML pages or internal UI endpoints.

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

Required config:

Variable	Description
FORGEJO_URL	Base URL of your Forgejo instance
FORGEJO_ADMIN_USER	Admin username for web UI login
FORGEJO_ADMIN_PASSWORD	Admin password for web UI login

environment:
  BACKEND_MODE: scrape
  FORGEJO_URL: https://forgejo.example.com
  FORGEJO_ADMIN_USER: admin
  FORGEJO_ADMIN_PASSWORD: secret

---

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"
}