Update path related documents (#25417) (#25982)

Backport #25417 by @wxiaoguang

Update WorkPath/WORK_PATH related documents, remove out-dated
information.

Remove "StaticRootPath" on the admin config display page, because few
end user really need it, it only causes misconfiguration.


![image](https://github.com/go-gitea/gitea/assets/2114189/8095afa4-da76-436b-9e89-2a92c229c01d)

Co-authored-by: wxiaoguang <wxiaoguang@gmail.com>

custom/conf/app.example.ini

@@ -16,26 +16,23 @@
 ;;
 ;; - _`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" option in "app.ini" file
 ;;   - 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 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:
+;;   - If any of the above are relative paths then they are made absolute against 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`_
+;;   - If any of the above are relative paths then they are made absolute against 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`_
+;;   - If any of the above are relative paths then they are made absolute against 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`_
 
@@ -52,6 +49,9 @@ RUN_USER = ; git
 ;; Application run mode, affects performance and debugging: "dev" or "prod", default is "prod"
 ;; Mode "dev" makes Gitea easier to develop and debug, values other than "dev" are treated as "prod" which is for production use.
 ;RUN_MODE = prod
+;;
+;; The working directory, see the comment of AppWorkPath above
+;WORK_PATH =
 
 ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
 ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;

docs/content/doc/administration/backup-and-restore.en-us.md

@@ -46,9 +46,9 @@ directory. There should be some output similar to the following:
 
 Inside the `gitea-dump-1482906742.zip` file, will be the following:
 
-- `app.ini` - Optional copy of configuration file if originally stored outside of the default `custom/` directory
+- `app.ini` - Optional copy of configuration file if originally stored outside the default `custom/` directory
 - `custom` - All config or customization files in `custom/`.
-- `data` - Data directory in <GITEA_WORK_DIR>, except sessions if you are using file session. This directory includes `attachments`, `avatars`, `lfs`, `indexers`, SQLite file if you are using SQLite.
+- `data` - Data directory (APP_DATA_PATH), except sessions if you are using file session. This directory includes `attachments`, `avatars`, `lfs`, `indexers`, SQLite file if you are using SQLite.
 - `gitea-db.sql` - SQL dump of database
 - `gitea-repo.zip` - Complete copy of the repository directory.
 - `log/` - Various logs. They are not needed for a recovery or migration.
@@ -139,16 +139,6 @@ chown -R git:git /data
 
 The default user in the gitea container is `git` (1000:1000). Please replace `2a83b293548e` with your gitea container id or name.
 
-These are the default paths used in the container:
-
-```text
-DEFAULT CONFIGURATION:
-     CustomPath:  /data/gitea (GITEA_CUSTOM)
-     CustomConf:  /data/gitea/conf/app.ini
-     AppPath:     /usr/local/bin/gitea
-     AppWorkPath: /usr/local/bin
-```
-
 ### Using Docker-rootless (`restore`)
 
 The restore workflow in Docker-rootless containers differs only in the directories to be used:

docs/content/doc/administration/command-line.en-us.md

@@ -31,9 +31,9 @@ All global options can be placed at the command level.
 
 - `--help`, `-h`: Show help text and exit. Optional.
 - `--version`, `-v`: Show version and exit. Optional. (example: `Gitea version 1.1.0+218-g7b907ed built with: bindata, sqlite`).
-- `--custom-path path`, `-C path`: Location of the Gitea custom folder. Optional. (default: `AppWorkPath`/custom or `$GITEA_CUSTOM`).
-- `--config path`, `-c path`: Gitea configuration file path. Optional. (default: `custom`/conf/app.ini).
-- `--work-path path`, `-w path`: Gitea `AppWorkPath`. Optional. (default: LOCATION_OF_GITEA_BINARY or `$GITEA_WORK_DIR`)
+- `--work-path path`, `-w path`: Gitea's work path. Optional. (default: the binary's path or `$GITEA_WORK_DIR`)
+- `--custom-path path`, `-C path`: Gitea's custom folder path. Optional. (default: `WorkPath`/custom or `$GITEA_CUSTOM`).
+- `--config path`, `-c path`: Gitea configuration file path. Optional. (default: `CustomPath`/conf/app.ini).
 
 NB: The defaults custom-path, config and work-path can also be
 changed at build time (if preferred).

docs/content/doc/administration/config-cheat-sheet.en-us.md

@@ -44,28 +44,27 @@ reported as part of the default configuration when running `gitea --help` or on
 
 - _`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` option in `app.ini`
   - 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 directory of the _`AppPath`_
+  - Otherwise, it defaults to the directory of the _`AppPath`_
+  - If any of the above are relative paths then they are made absolute against 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`
+  - 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`_
+  - Otherwise, it defaults to _`CustomPath`_`/conf/app.ini`
+  - If any of the above are relative paths then they are made absolute against 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`_
+In addition, there is _`StaticRootPath`_ which can be set as a built-in at build time, but will otherwise default to _`AppWorkPath`_
 
 ## Overall (`DEFAULT`)
 
@@ -74,6 +73,7 @@ In addition there is _`StaticRootPath`_ which can be set as a built-in at build
    This should be a dedicated system (non-user) account. Setting this incorrectly will cause Gitea
    to not start.
 - `RUN_MODE`: **prod**: Application run mode, affects performance and debugging: `dev` or `prod`, default is `prod`. Mode `dev` makes Gitea easier to develop and debug, values other than `dev` are treated as `prod` which is for production use.
+- `WORK_PATH`: **_the-work-path_**: The working directory, see the comment of AppWorkPath above.
 
 ## Repository (`repository`)
 

docs/content/doc/administration/customizing-gitea.en-us.md

@@ -18,7 +18,7 @@ menu:
 # Customizing Gitea
 
 Customizing Gitea is typically done using the `CustomPath` folder - by default this is
-the `custom` folder from the running directory, but may be different if your build has
+the `custom` folder from the working directory (WorkPath), but may be different if your build has
 set this differently. This is the central place to override configuration settings,
 templates, etc. You can check the `CustomPath` using `gitea help`. You can also find
 the path on the _Configuration_ tab in the _Site Administration_ page. You can override

docs/content/doc/administration/environment-variables.en-us.md

@@ -43,10 +43,7 @@ For documentation about each of the variables available, refer to the
 ## Gitea files
 
 - `GITEA_WORK_DIR`: Absolute path of working directory.
-- `GITEA_CUSTOM`: Gitea uses `GITEA_WORK_DIR`/custom folder by default. Use this variable
-  to change _custom_ directory.
-- `GOGS_WORK_DIR`: Deprecated, use `GITEA_WORK_DIR`
-- `GOGS_CUSTOM`: Deprecated, use `GITEA_CUSTOM`
+- `GITEA_CUSTOM`: Gitea uses `WorkPath`/custom folder by default. Use this variable to change _custom_ directory.
 
 ## Operating system specifics
 

docs/content/doc/help/faq.en-us.md

@@ -59,11 +59,12 @@ https://github.com/loganinak/MigrateGitlabToGogs
 ## Where does Gitea store what file
 
 - _`AppWorkPath`_
-  - The `--work-path` flag
+  - The `WORK_PATH` option in `app.ini`
+  - Else the `--work-path` flag
   - Else Environment variable `GITEA_WORK_DIR`
   - Else a built-in value set at build time
   - Else the directory that contains the Gitea binary
-- `%(APP_DATA_PATH)` (default for database, indexers, etc.)
+- `AppDataPath` (default for database, indexers, etc.)
   - `APP_DATA_PATH` from `app.ini`
   - Else _`AppWorkPath`_`/data`
 - _`CustomPath`_ (custom templates)
@@ -112,9 +113,6 @@ Gitea's custom templates must be added to the correct location or Gitea will not
 The correct path for the template(s) will be relative to the `CustomPath`
 
 1. To find `CustomPath`, look for Custom File Root Path in Site Administration -> Configuration
-
-    If that doesn't exist, you can try `echo $GITEA_CUSTOM`
-
 2. If you are still unable to find a path, the default can be [calculated above](#where-does-gitea-store-what-file)
 3. Once you have figured out the correct custom path, you can refer to the [customizing Gitea]({{< relref "doc/administration/customizing-gitea.en-us.md" >}}) page to add your template to the correct location.
 

modules/setting/path.go

@@ -17,7 +17,7 @@ var (
 	// AppPath represents the path to the gitea binary
 	AppPath string
 
-	// AppWorkPath is the "working directory" of Gitea. It maps to the environment variable GITEA_WORK_DIR.
+	// AppWorkPath is the "working directory" of Gitea. It maps to the: WORK_PATH in app.ini, "--work-path" flag, environment variable GITEA_WORK_DIR.
 	// If that is not set it is the default set here by the linker or failing that the directory of AppPath.
 	// It is used as the base path for several other paths.
 	AppWorkPath string

options/locale/locale_en-US.ini

@@ -2950,9 +2950,9 @@ config.disable_router_log = Disable Router Log
 config.run_user = Run As Username
 config.run_mode = Run Mode
 config.git_version = Git Version
+config.app_data_path = App Data Path
 config.repo_root_path = Repository Root Path
 config.lfs_root_path = LFS Root Path
-config.static_file_root_path = Static File Root Path
 config.log_file_root_path = Log Path
 config.script_type = Script Type
 config.reverse_auth_user = Reverse Authentication User

routers/web/admin/config.go

@@ -120,9 +120,9 @@ func Config(ctx *context.Context) {
 	ctx.Data["RunMode"] = util.ToTitleCase(setting.RunMode)
 	ctx.Data["GitVersion"] = git.VersionInfo()
 
+	ctx.Data["AppDataPath"] = setting.AppDataPath
 	ctx.Data["RepoRootPath"] = setting.RepoRootPath
 	ctx.Data["CustomRootPath"] = setting.CustomPath
-	ctx.Data["StaticRootPath"] = setting.StaticRootPath
 	ctx.Data["LogRootPath"] = setting.Log.RootPath
 	ctx.Data["ScriptType"] = setting.ScriptType
 	ctx.Data["ReverseProxyAuthUser"] = setting.ReverseProxyAuthUser

templates/admin/config.tmpl

@@ -34,10 +34,10 @@
 
 				<div class="ui divider"></div>
 
+				<dt>{{.locale.Tr "admin.config.app_data_path"}}</dt>
+				<dd>{{.AppDataPath}}</dd>
 				<dt>{{.locale.Tr "admin.config.repo_root_path"}}</dt>
 				<dd>{{.RepoRootPath}}</dd>
-				<dt>{{.locale.Tr "admin.config.static_file_root_path"}}</dt>
-				<dd>{{.StaticRootPath}}</dd>
 				<dt>{{.locale.Tr "admin.config.custom_file_root_path"}}</dt>
 				<dd>{{.CustomRootPath}}</dd>
 				<dt>{{.locale.Tr "admin.config.log_file_root_path"}}</dt>