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>
(cherry picked from commit ee47face12)
This commit is contained in:
Giteabot 2023-07-19 05:48:54 -04:00 committed by Earl Warren
parent 3d033a3aa7
commit f890856cf4
No known key found for this signature in database
GPG key ID: 0579CB2928A78A00
11 changed files with 31 additions and 46 deletions

View file

@ -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 =
;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;

View file

@ -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:

View file

@ -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).

View file

@ -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`)

View file

@ -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

View file

@ -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

View file

@ -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.

View file

@ -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

View file

@ -2967,9 +2967,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

View file

@ -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

View file

@ -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>