Lunny Xiao
106a813e08
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]>
Gitea Docs 
The sources of docs.gitea.com, built with Astro and Starlight.
The site covers three products, all served from this repository:
| Product | Content | Versions | Languages |
|---|---|---|---|
| Docs | docs/, versioned_docs/, i18n/ |
next, 1.27 … 1.22 | English, 简体中文, 繁體中文 |
| API | static/swagger-*.json, static/openapi3-*.json |
next, 1.27 … 1.22 | English |
| Runner | runner-docs/, runner-docs_versioned_docs/ |
develop, 3 … 0 | English |
The enterprise documentation is built and deployed from its own repository and
reached through /enterprise/, which a Cloudflare worker maintained elsewhere
routes to that deployment.
Development
make install # pnpm install
make serve-fast # english, the version served at the root, starts in seconds
make serve # the whole matrix, every version and language
make build # production build into sites/docs/dist
make check # type checks the site and its components
Search is built by Pagefind while the site is built, so it only answers on the
built site: use make serve-built to try it. With the Algolia credentials
(PUBLIC_DOCSEARCH_APP_ID, PUBLIC_DOCSEARCH_API_KEY) set, DocSearch is used
instead and works in make serve too.
GITEA_DOCS_PRODUCTS, GITEA_DOCS_VERSIONS and GITEA_DOCS_LOCALES (comma
separated) restrict what is built, which is what make serve-fast uses.
GITEA_DOCS_STRICT_LINKS=true turns the warnings about unresolved relative
markdown links into a build error.
sites/docs/README.md documents how the sources are mapped onto the site.
Writing
Pages are plain markdown with the same frontmatter and admonitions as before:
frontmatter slug, sidebar_position and sidebar_label keep working, and so
do the :::note style admonitions and the @version@ style release variables.
Relative *.md links are rewritten to urls while the site is built.
The order of the top level sidebar groups comes from sidebars.js (and
versioned_sidebars/ for released versions), the label and order of every other
group from the _category_.json of its directory.
Cutting a version
make cut-version PRODUCT=docs VERSION=1.28
make cut-version PRODUCT=runner VERSION=4
This freezes the current tree, its translations and its sidebar. The label of
the version, its release variables (@version@, @dockerVersion@, ...) and
which version is served at the root live in
packages/content-loader/src/products.ts and are edited by hand afterwards.
That file is the single source of truth for the product, version and language
matrix.
API docs
The definitions rendered under /api/ live in static/:
swagger-latest.json (gitea main) and swagger-<minor>.json (released
versions) hold the swagger 2.0 document every gitea version ships,
openapi3-latest.json and openapi3-<minor>.json the openapi 3.0 document
gitea generates since 1.27. The openapi 3.0 document is what gets rendered
where it exists, and both are offered for download on the overview page of the
version, since code generators cannot read the rendered pages (and several of
them reject swagger 2.0).
make update-api-docs # refresh latest + every released version
make update-api-docs-latest # refresh only the documents of gitea main
The documents of gitea main are refreshed automatically: the update api spec files workflow runs every 12 hours and opens a pull request whenever gitea main
changed. Released versions are updated by hand when a new gitea version is
documented.
Runner docs
| Version | Content | URL |
|---|---|---|
| develop | runner-docs/ |
/runner/develop/ |
| current series | runner-docs_versioned_docs/version-3/ |
/runner/ |
| older series | runner-docs_versioned_docs/version-2/ |
/runner/2/ |
A version directory covers a whole release series (version-3 documents every
3.x release), so a patch release only needs a content update, not a new
folder. Use floating image tags (gitea/runner:3) and links to the runner's
main branch in those pages to keep them valid across patch releases.
Its sidebar is written by hand: runner-sidebars.js for develop, and
runner-docs_versioned_sidebars/version-<version>-sidebars.json per documented
version.
The pages under reference/ are generated from the runner sources — the command
line reference from --help, the example configuration from generate-config:
make update-runner-docs # develop docs, from the main branch of gitea/runner
make update-runner-docs-released # every series, from its newest stable tag
./update_runner_docs.sh v3.0.2 runner-docs_versioned_docs/version-3/reference
These are refreshed automatically as well: the update runner reference
workflow runs weekly and opens a pull request whenever the runner's CLI or
example configuration changed. Generating them needs Go, since the script builds
the runner binary.
Deployment
main is built and published by the Build and Publish Docs site workflow, to
S3/CloudFront and to Cloudflare Pages. cloudflare/_headers sets the cache
policy and cloudflare/_redirects keeps the urls the site used to serve; both
are copied next to the build output by that workflow.
cloudflare/docsearch-crawler.json is the Algolia crawler configuration.
/enterprise/ is served by another deployment and routed to it by a Cloudflare
worker that lives outside this repository.