From eb8ade10c72f697dcc05628b9bd8b1a185f5a4c5 Mon Sep 17 00:00:00 2001
From: silverwind <2021+silverwind@noreply.gitea.com>
Date: Tue, 17 Mar 2026 18:19:18 +0000
Subject: [PATCH] Update environment variable docs, remove environment-to-ini
 references (#355)

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 <29147+wxiaoguang@noreply.gitea.com>
Reviewed-by: TheFox0x7 <95654+thefox0x7@noreply.gitea.com>
---
 docs/administration/config-cheat-sheet.md | 30 +++++++++++++++++++++--
 docs/installation/with-docker-rootless.md |  3 +--
 docs/installation/with-docker.md          |  3 +--
 3 files changed, 30 insertions(+), 6 deletions(-)

diff --git a/docs/administration/config-cheat-sheet.md b/docs/administration/config-cheat-sheet.md
index 35097674..23db55dd 100644
--- a/docs/administration/config-cheat-sheet.md
+++ b/docs/administration/config-cheat-sheet.md
@@ -34,8 +34,34 @@ A full restart is required for Gitea configuration changes to take effect.
 
 ## Use environment variables to setup Gitea
 
-There is [environment-to-ini](https://github.com/go-gitea/gitea/blob/main/docker/root/usr/local/bin/environment-to-ini) to help to
-generate Gitea's `app.ini` from environment variables.
+Gitea supports setting `app.ini` values via environment variables of the form `GITEA__<section>__<KEY>`. These require running `gitea config edit-ini --in-place --apply-env` before starting Gitea to write them into `app.ini`. The official Docker images do this automatically on container startup.
+
+For example, to configure the database connection via environment variables:
+
+```
+GITEA__database__DB_TYPE=postgres
+GITEA__database__HOST=127.0.0.1:5432
+GITEA__database__NAME=gitea
+GITEA__database__USER=gitea
+GITEA__database__PASSWD=secret
+```
+
+This is equivalent to the following `app.ini` configuration:
+
+```ini
+[database]
+DB_TYPE = postgres
+HOST = 127.0.0.1:5432
+NAME = gitea
+USER = gitea
+PASSWD = secret
+```
+
+You can also load values from files by appending `__FILE` to the variable name. This is useful for Docker secrets:
+
+```
+GITEA__database__PASSWD__FILE=/run/secrets/db_password
+```
 
 ## Default Internal Variables (non-`app.ini` configuration)
 
diff --git a/docs/installation/with-docker-rootless.md b/docs/installation/with-docker-rootless.md
index 3aa67178..9b0621e8 100644
--- a/docs/installation/with-docker-rootless.md
+++ b/docs/installation/with-docker-rootless.md
@@ -288,9 +288,8 @@ docker-compose up -d
 ## Managing Deployments With Environment Variables
 
 In addition to the environment variables above, any settings in `app.ini` can be set
-or overridden with an environment variable of the form: `GITEA__SECTION_NAME__KEY_NAME`.
+or overridden with an environment variable of the form: `GITEA__<section>__<KEY>`.
 These settings are applied each time the docker container starts, and won't be passed into Gitea's sub-processes.
-Full information [here](https://github.com/go-gitea/gitea/tree/main/contrib/environment-to-ini).
 
 These environment variables can be passed to the docker container in `docker-compose.yml`.
 The following example will enable a smtp mail server if the required env variables
diff --git a/docs/installation/with-docker.md b/docs/installation/with-docker.md
index db312425..b77921db 100644
--- a/docs/installation/with-docker.md
+++ b/docs/installation/with-docker.md
@@ -277,9 +277,8 @@ docker compose up -d
 ## Managing Deployments With Environment Variables
 
 In addition to the environment variables above, any settings in `app.ini` can be set
-or overridden with an environment variable of the form: `GITEA__SECTION_NAME__KEY_NAME`.
+or overridden with an environment variable of the form: `GITEA__<section>__<KEY>`.
 These settings are applied each time the docker container starts, and won't be passed into Gitea's sub-processes.
-Full information [here](https://github.com/go-gitea/gitea/tree/master/contrib/environment-to-ini).
 
 These environment variables can be passed to the docker container in `docker-compose.yml`.
 The following example will enable an smtp mail server if the required env variables