Skip to content

Commit

Permalink
Attempt clarify AppWorkPath etc. (go-gitea#21656)
Browse files Browse the repository at this point in the history 
Attempt clarify the AppWorkPath in the documentation by using different
notation and adding a section to the start of the cheat sheet.

Fix go-gitea#21523

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

Signed-off-by: Andrew Thornton <art27@cantab.net>
  • Loading branch information
@zeripath
zeripath committed Nov 10, 2022
1 parent 5a6cba4 commit 99688ef
Show file tree
Hide file tree
Showing 5 changed files with 126 additions and 54 deletions.
62 changes: 48 additions & 14 deletions custom/conf/app.example.ini
View file
Original file line number Diff line number Diff line change
Expand Up @@ -7,6 +7,38 @@
;; see https://docs.gitea.io/en-us/config-cheat-sheet/ for additional documentation.


;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
;; 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
;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
Expand All @@ -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
Expand All @@ -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.
Expand All @@ -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=
Expand All @@ -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
Expand Down Expand Up @@ -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,
Expand Down Expand Up @@ -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
Expand All @@ -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.
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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.
Expand Down Expand Up @@ -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
Expand All @@ -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
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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
Expand Down

0 comments on commit 99688ef

Please sign in to comment.