Attempt clarify AppWorkPath etc. (#21656)

Attempt clarify the AppWorkPath in the documentation by using different
notation and adding a section to the start of the cheat sheet.

Fix #21523

Signed-off-by: Andrew Thornton <art27@cantab.net>

Signed-off-by: Andrew Thornton <art27@cantab.net>

1 files changed, 48 insertions, 14 deletions

diff --git a/custom/conf/app.example.ini b/custom/conf/app.example.ini
index b46dfc20a..9f41fdb08 100644
--- a/custom/conf/app.example.ini
+++ b/custom/conf/app.example.ini
@@ -8,6 +8,38 @@
 
 
 ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
+;; Default Configuration (non-`app.ini` configuration)
+;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
+;;
+;; These values are environment-dependent but form the basis of a lot of values. They will be
+;; reported as part of the default configuration when running `gitea --help` or on start-up. The order they are emitted there is slightly different but we will list them here in the order they are set-up.
+;;
+;; - _`AppPath`_: This is the absolute path of the running gitea binary.
+;; - _`AppWorkPath`_: This refers to "working path" of the `gitea` binary. It is determined by using the first set thing in the following hierarchy:
+;;   - The `--work-path` flag passed to the binary
+;;   - The environment variable `$GITEA_WORK_DIR`
+;;   - A built-in value set at build time (see building from source)
+;;   - Otherwise it defaults to the directory of the _`AppPath`_
+;;   - If any of the above are relative paths then they are made absolute against the
+;; the directory of the _`AppPath`_
+;; - _`CustomPath`_: This is the base directory for custom templates and other options.
+;; It is determined by using the first set thing in the following hierarchy:
+;;   - The `--custom-path` flag passed to the binary
+;;   - The environment variable `$GITEA_CUSTOM`
+;;   - A built-in value set at build time (see building from source)
+;;   - Otherwise it defaults to _`AppWorkPath`_`/custom`
+;;   - If any of the above are relative paths then they are made absolute against the
+;; the directory of the _`AppWorkPath`_
+;; - _`CustomConf`_: This is the path to the `app.ini` file.
+;;   - The `--config` flag passed to the binary
+;;   - A built-in value set at build time (see building from source)
+;;   - Otherwise it defaults to _`CustomPath`_`/conf/app.ini`
+;;   - If any of the above are relative paths then they are made absolute against the
+;; the directory of the _`CustomPath`_
+;;
+;; In addition there is _`StaticRootPath`_ which can be set as a built-in at build time, but will otherwise default to _`AppWorkPath`_
+
+;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
 ;; General Settings
 ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
 ;;
@@ -26,7 +58,7 @@ RUN_MODE = ; prod
 ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
 ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
 ;;
-;; The protocol the server listens on. One of 'http', 'https', 'unix' or 'fcgi'. Defaults to 'http'
+;; The protocol the server listens on. One of 'http', 'https', 'http+unix', 'fcgi' or 'fcgi+unix'. Defaults to 'http'
 ;PROTOCOL = http
 ;;
 ;; Expect PROXY protocol headers on connections
@@ -51,6 +83,8 @@ RUN_MODE = ; prod
 ;STATIC_URL_PREFIX =
 ;;
 ;; The address to listen on. Either a IPv4/IPv6 address or the path to a unix socket.
+;; If PROTOCOL is set to `http+unix` or `fcgi+unix`, this should be the name of the Unix socket file to use.
+;; Relative paths will be made absolute against the _`AppWorkPath`_.
 ;HTTP_ADDR = 0.0.0.0
 ;;
 ;; The port to listen on. Leave empty when using a unix socket.
@@ -64,7 +98,7 @@ RUN_MODE = ; prod
 ;PORT_TO_REDIRECT = 80
 ;;
 ;; expect PROXY protocol header on connections to https redirector.
-;REDIRECTOR_USE_PROXY_PROTOCOL = %(USE_PROXY_PROTOCOL)
+;REDIRECTOR_USE_PROXY_PROTOCOL = %(USE_PROXY_PROTOCOL)s
 ;; Minimum and maximum supported TLS versions
 ;SSL_MIN_VERSION=TLSv1.2
 ;SSL_MAX_VERSION=
@@ -91,7 +125,7 @@ RUN_MODE = ; prod
 ;LOCAL_ROOT_URL = %(PROTOCOL)s://%(HTTP_ADDR)s:%(HTTP_PORT)s/
 ;;
 ;; When making local connections pass the PROXY protocol header.
-;LOCAL_USE_PROXY_PROTOCOL = %(USE_PROXY_PROTOCOL)
+;LOCAL_USE_PROXY_PROTOCOL = %(USE_PROXY_PROTOCOL)s
 ;;
 ;; Disable SSH feature when not available
 ;DISABLE_SSH = false
@@ -145,7 +179,7 @@ RUN_MODE = ; prod
 ;;
 ;; For the built-in SSH server, choose the keypair to offer as the host key
 ;; The private key should be at SSH_SERVER_HOST_KEY and the public SSH_SERVER_HOST_KEY.pub
-;; relative paths are made absolute relative to the APP_DATA_PATH
+;; relative paths are made absolute relative to the %(APP_DATA_PATH)s
 ;SSH_SERVER_HOST_KEYS=ssh/gitea.rsa, ssh/gogs.rsa
 ;;
 ;; Directory to create temporary files in when testing public keys using ssh-keygen,
@@ -241,10 +275,10 @@ RUN_MODE = ; prod
 ;;
 ;; Root directory containing templates and static files.
 ;; default is the path where Gitea is executed
-;STATIC_ROOT_PATH =
+;STATIC_ROOT_PATH = ; Will default to the built-in value _`StaticRootPath`_
 ;;
 ;; Default path for App data
-;APP_DATA_PATH = data
+;APP_DATA_PATH = data ; relative paths will be made absolute with _`AppWorkPath`_
 ;;
 ;; Enable gzip compression for runtime-generated content, static resources excluded
 ;ENABLE_GZIP = false
@@ -255,7 +289,7 @@ RUN_MODE = ; prod
 ;ENABLE_PPROF = false
 ;;
 ;; PPROF_DATA_PATH, use an absolute path when you start gitea as service
-;PPROF_DATA_PATH = data/tmp/pprof
+;PPROF_DATA_PATH = data/tmp/pprof ; Path is relative to _`AppWorkPath`_
 ;;
 ;; Landing page, can be "home", "explore", "organizations", "login", or any URL such as "/org/repo" or even "https://anotherwebsite.com"
 ;; The "login" choice is not a security measure but just a UI flow change, use REQUIRE_SIGNIN_VIEW to force users to log in.
@@ -633,7 +667,7 @@ ROUTER = console
 ;PATH =
 ;;
 ;; The HOME directory for Git
-;HOME_PATH = %(APP_DATA_PATH)/home
+;HOME_PATH = %(APP_DATA_PATH)s/home
 ;;
 ;; Disables highlight of added and removed changes
 ;DISABLE_DIFF_HIGHLIGHT = false
@@ -838,8 +872,8 @@ ROUTER = console
 ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
 ;[repository]
 ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
-;; Root path for storing all repository data. By default, it is set to %(APP_DATA_PATH)/gitea-repositories.
-;; A relative path is interpreted as %(GITEA_WORK_DIR)/%(ROOT)
+;; Root path for storing all repository data. By default, it is set to %(APP_DATA_PATH)s/gitea-repositories.
+;; A relative path is interpreted as _`AppWorkPath`_/%(ROOT)s
 ;ROOT =
 ;;
 ;; The script type this server supports. Usually this is `bash`, but some users report that only `sh` is available.
@@ -1296,7 +1330,7 @@ ROUTER = console
 ;ISSUE_INDEXER_TYPE = bleve
 ;;
 ;; Issue indexer storage path, available when ISSUE_INDEXER_TYPE is bleve
-;ISSUE_INDEXER_PATH = indexers/issues.bleve
+;ISSUE_INDEXER_PATH = indexers/issues.bleve ; Relative paths will be made absolute against _`AppWorkPath`_.
 ;;
 ;; Issue indexer connection string, available when ISSUE_INDEXER_TYPE is elasticsearch
 ;ISSUE_INDEXER_CONN_STR = http://elastic:changeme@localhost:9200
@@ -1314,7 +1348,7 @@ ROUTER = console
 ;; When ISSUE_INDEXER_QUEUE_TYPE is levelqueue, this will be the path where the queue will be saved.
 ;; This can be overridden by `ISSUE_INDEXER_QUEUE_CONN_STR`.
 ;; default is queues/common
-;ISSUE_INDEXER_QUEUE_DIR = queues/common; **DEPRECATED** use settings in `[queue.issue_indexer]`.
+;ISSUE_INDEXER_QUEUE_DIR = queues/common; **DEPRECATED** use settings in `[queue.issue_indexer]`. Relative paths will be made absolute against `%(APP_DATA_PATH)s`.
 ;;
 ;; When `ISSUE_INDEXER_QUEUE_TYPE` is `redis`, this will store the redis connection string.
 ;; When `ISSUE_INDEXER_QUEUE_TYPE` is `levelqueue`, this is a directory or additional options of
@@ -1370,7 +1404,7 @@ ROUTER = console
 ;TYPE = persistable-channel
 ;;
 ;; data-dir for storing persistable queues and level queues, individual queues will default to `queues/common` meaning the queue is shared.
-;DATADIR = queues/
+;DATADIR = queues/ ; Relative paths will be made absolute against `%(APP_DATA_PATH)s`.
 ;;
 ;; Default queue length before a channel queue will block
 ;LENGTH = 20
@@ -1672,7 +1706,7 @@ ROUTER = console
 ;; file: session file path, e.g. `data/sessions`
 ;; redis: network=tcp,addr=:6379,password=macaron,db=0,pool_size=100,idle_timeout=180
 ;; mysql: go-sql-driver/mysql dsn config string, e.g. `root:password@/session_table`
-;PROVIDER_CONFIG = data/sessions
+;PROVIDER_CONFIG = data/sessions ; Relative paths will be made absolute against _`AppWorkPath`_.
 ;;
 ;; Session cookie name
 ;COOKIE_NAME = i_like_gitea