Five documentation fixes that do not depend on anything upstream.
**PostgreSQL version in the docker guide** (closes#224)
The compose example pinned `postgres:14`, the oldest version Gitea still tests against, and PostgreSQL does not upgrade its data directory on its own, so every new deployment that copies the example is one major upgrade behind from day one. The example now uses `postgres:18`, with a note about why the major version is pinned and a pointer to the supported range.
**SELinux** (closes#211)
`setcap 'cap_net_bind_service=+ep'` is what the docs suggest for binding to a port below 1024, but it is denied under SELinux depending on the label of the binary, and it is lost on every upgrade because the capability lives in an extended attribute of the file. A new page describes granting the capability through the systemd unit instead (`AmbientCapabilities`, plus `PrivateUsers=false` when the sandboxing gets in the way), the `semanage fcontext` / `restorecon` labels for the binary and the data directory, and how to read the denials with `ausearch` and `audit2allow`. It is linked from the binary and source installation pages and from the `gitea web` notes.
**OAuth2 and OpenID Connect** (closes#106)
The authentication page documented LDAP, PAM, SMTP, FreeIPA, SPNEGO and the reverse proxy, but not that Gitea can log users in against an external OAuth2 or OpenID Connect provider, which made it look like the only OAuth2 support is Gitea acting as the provider. The new section covers the fields of the authentication source, the callback URL to register at the provider, the group and claim mappings, and the `[oauth2_client]` settings, and separates it from the older OpenID 2.0 sign-in.
**IIS reverse proxy** (closes#39)
Application Request Routing rewrites the host of the `Location` header back to the internal one while "Reverse rewrite host in response headers" is on, which sends the browser to `127.0.0.1:3000` after a sign-in. The IIS section now says to turn it off and where the setting lives.
**ACME in containers** (closes#292)
`ACME_DIRECTORY` defaults to the relative path `https`, which is resolved against the working directory of the process. In the official image that is `/app/gitea`, outside the `/data` volume, so a recreated container asks the CA for a new certificate and runs into the Let's Encrypt limit of 5 certificates per week for the same domains. The HTTPS page now warns about it and shows an absolute path inside the volume; the cheat sheet entry points at the warning. The default itself is being changed in https://github.com/go-gitea/gitea/pull/35851, the note stays useful for every released version.
Only `docs/` is touched, the released versions keep their content.
<!-- cloudflare-preview --> Preview: https://pr-513.docs-gitea-com.pages.dev
Reviewed-on: https://gitea.com/gitea/docs/pulls/513
Reviewed-by: bircni <[email protected]>
Co-authored-by: Lunny Xiao <[email protected]>
The standalone `environment-to-ini` tool was removed in https://github.com/go-gitea/gitea/pull/35735 and its functionality is now built into the Gitea binary. This PR:
- Removes outdated links to the removed `contrib/environment-to-ini` directory
- Updates the "Use environment variables to setup Gitea" section in the config cheat sheet
- Adds examples showing how env vars map to `app.ini` settings and the `__FILE` suffix for secrets
*This PR was authored by Claude.*
Reviewed-on: https://gitea.com/gitea/docs/pulls/355
Reviewed-by: wxiaoguang <[email protected]>
Reviewed-by: TheFox0x7 <[email protected]>
- Always use a relative markdown link so that we can jump even if we edit it in local env or read it in code hosting server.
Reviewed-on: https://gitea.com/gitea/docs/pulls/1
Lunny Xiao
wxiaoguang
kmanwar89andwxiaoguang
silverwind
iqre8
techknowlogick
DiegoBMandDiego de Blas Mateo
Schallbert
ManInDarkandtechknowlogick
TheFox0x7