proxmox/docs/04-configuration/GITEA_PLATFORM_AND_UPGRADE_RUNBOOK.md

Gitea as a platform — layout, operations, and upgrades

Last updated: 2026-04-05
Status: Active operator documentation

---

1. Where Gitea runs in this project

Role	VMID / host	LAN	Public edge
Org forge (primary)	104 on r630-01	192.168.11.31 — HTTP 80 / HTTPS 443	https://gitea.d-bis.org via NPMplus (GITEA_PUBLIC_UPSTREAM_* in config/ip-addresses.conf)
Dev / GitOps (optional)	5700	192.168.11.59 — Gitea on :3000 if installed via scripts/setup-dev-vm-users-and-gitea.sh	Only if you point gitea.d-bis.org at the dev VM (not default)

Single source for IPs: ALL_VMIDS_ENDPOINTS.md. NPM automation: scripts/nginx-proxy-manager/update-npmplus-proxy-hosts-api.sh and update-npmplus-fourth-proxy-hosts.sh. IP conflict notes: GITEA_IP_CONFLICT_CHECK.md.

---

2. Platform shape (VMID 104)

Typical install matches the community-scripts / tteck LXC pattern vendored under ProxmoxVE/install/gitea-install.sh:

• Binary: /usr/local/bin/gitea (single static binary from dl.gitea.com)
• Config: /etc/gitea/app.ini (often chmod 770 and root:gitea)
• Data: /var/lib/gitea/ (custom, data, log; repos and DB live under data unless external DB)
• Service user: gitea (system user)
• systemd: gitea.service → gitea web --config /etc/gitea/app.ini

Actions / CI: Gitea Actions runners are optional; there is no stable unauthenticated API across all versions for umbrella checks — use ./scripts/verify/print-gitea-actions-urls.sh and verify in the UI.

Integrations in this repo: Webhooks and tokens for Phoenix Deploy API — PHOENIX_DEPLOY_API_GITEA_INTEGRATION.md. Submodule / remote hygiene — ../00-meta/SUBMODULE_HYGIENE.md.

---

3. Upgrade strategy (binary install)

Official guidance: Upgrade Gitea (read the minor vs major notes and backup expectations).

Before any upgrade

1. Snapshot the CT (Proxmox) or at least backup /var/lib/gitea and /etc/gitea/app.ini.
2. Announce a short maintenance window if users push during the stop.
3. Note current version: pct exec 104 -- /usr/local/bin/gitea --version.

Recommended path (automated from LAN)

# Preview (no stop, no download on CT beyond version probe)
./scripts/operator/upgrade-gitea-lxc.sh --dry-run

# Latest release from GitHub “latest”
./scripts/operator/upgrade-gitea-lxc.sh

# Pin a version (see https://dl.gitea.com/gitea/ for folders)
GITEA_VERSION=1.22.6 ./scripts/operator/upgrade-gitea-lxc.sh

The script stops gitea, backs up the binary, downloads the chosen release for linux-amd64 (override with GITEA_ARCH=linux-arm64 on ARM LXCs), runs gitea migrate, then starts the service.

Manual path inside CT (if SSH to Proxmox is enough but you prefer hands-on)

systemctl stop gitea
cp -a /usr/local/bin/gitea /usr/local/bin/gitea.bak.$(date +%Y%m%d%H%M%S)
curl -fsSL -o /tmp/gitea https://dl.gitea.com/gitea/<VERSION>/gitea-<VERSION>-linux-amd64
chmod +x /tmp/gitea && install -m 755 /tmp/gitea /usr/local/bin/gitea
sudo -u gitea env GITEA_WORK_DIR=/var/lib/gitea HOME=/var/lib/gitea/data \
  /usr/local/bin/gitea migrate --config /etc/gitea/app.ini
systemctl start gitea
/usr/local/bin/gitea --version

tteck LXC “update” command
If the CT was created with the Proxmox helper that installs update in the container menu, that flow also replaces /usr/local/bin/gitea from GitHub releases (see ProxmoxVE/ct/gitea.sh update_script). Keep that in mind if operators are used to update inside the CT — it should align with the same binary layout.

---

4. After upgrade

• Open https://gitea.d-bis.org (or http://192.168.11.31) and confirm login, orgs, and a sample git fetch.
• Run gitea doctor if the release notes ask for it (often as the gitea user, same app.ini).
• Watch journalctl -u gitea -f for migration or hook errors.

---

5. Security and platform roadmap (short list)

• Stay on supported Gitea versions; subscribe to Gitea security releases.
• Prefer SSH deploy keys or tokens over passwords; rotate GITEA_TOKEN used by automation (.env.master.example).
• For larger teams or HA, evaluate PostgreSQL, reverse-proxy hardening, and read replicas per upstream docs — the default SQLite single-node CT is fine for many lab/small-org workloads until scale demands it.

---

6. Add-ons, plugins, and extensions (what exists today)

There is no WordPress-style plugin marketplace inside Gitea. The server is a single Go binary; “extending” it is done by turning on built-in modules in app.ini, using webhooks + external services, Gitea Actions (with runners), OAuth apps, and custom branding — not by dropping .so plugins into the core.

6.1 Built-in features to enable in configuration (most common “add-ons”)

These ship with Gitea and are toggled via app.ini / admin UI (exact section names vary slightly by version — use Config Cheat Sheet for yours):

Capability	What it gives you
Gitea Actions	CI/CD like GitHub Actions (.gitea/workflows/*.yml); requires act_runner (or compatible) on a separate host/VM
Packages	npm, Maven, NuGet, PyPI, generic packages, etc.
Container registry	OCI images (often paired with Docker/Podman push)
OAuth2 / OpenID	Sign-in via Keycloak, Google, GitHub, etc.
LDAP / SMTP	Directory login and mail for notifications
Webhooks	Drive Phoenix Deploy, Slack, Matrix, custom HTTP receivers (PHOENIX_DEPLOY_API_GITEA_INTEGRATION.md)
Issue dependencies / time tracking	Project-management style features (version-dependent)

In this workspace: workflows already exist in some repos (e.g. .gitea/workflows/ci.yml per RECOMMENDATIONS_TTS_GITEA_PHOENIX.md); ensure Actions + a runner are enabled if you want them on gitea.d-bis.org.

6.2 External “plugins” (integrate via API / webhooks / CI)

Community tools are not loaded into the Gitea process; they run beside it:

• Awesome Gitea — curated list (Actions, bots, migrations, IDE extensions, themes, Pages-style hosting, SDKs).
• CI/CD: Woodpecker CI, Drone (Gitea as auth + repo source), or Gitea Actions + act_runner.
• Dependency updates: Renovate with Gitea provider (see RENOVATE_GITEA_SETUP.md if present in tree).
• Bots: tea CLI, release automation (gitea-release-action, etc. — see Awesome list).
• AI / review helpers: GITEA_AI_REVIEW_SETUP.md (pattern: webhook or CI calling an LLM API).

6.3 Customization without “plugins”

• custom/ directory: templates, extra static assets, logos (Customizing Gitea).
• Branch protection, deploy keys, commit signing — org/repo settings (GITEA_BRANCH_PROTECTION.md).

6.4 Experimental / future

Upstream has discussed richer extensibility (e.g. dynamic renderers); nothing replaces webhooks + Actions + external tools today for most teams. For a Forgejo-centric plugin narrative, check Forgejo’s own docs if you ever fork/migrate.

---

7. Related scripts and config

Asset	Purpose
scripts/operator/upgrade-gitea-lxc.sh	Binary upgrade via pct exec on VMID 104
config/ip-addresses.conf	IP_GITEA_INFRA, GITEA_PUBLIC_UPSTREAM_*
scripts/nginx-proxy-manager/update-npmplus-proxy-hosts-api.sh	Primary NPMplus row for gitea.d-bis.org
scripts/nginx-proxy-manager/update-npmplus-fourth-proxy-hosts.sh	Fourth NPMplus dev/Gitea hostnames
scripts/setup-dev-vm-users-and-gitea.sh	Dev VM Gitea on :3000
scripts/dev-vm/gitea-create-orgs-and-repos.sh	API automation (needs GITEA_TOKEN)