From 2312952c2aa4e39756bced0e2e90a477010b03f9 Mon Sep 17 00:00:00 2001 From: Giteabot Date: Wed, 19 Jul 2023 05:48:54 -0400 Subject: [PATCH] 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 --- doc/administration/backup-and-restore.en-us.md | 14 ++------------ doc/administration/command-line.en-us.md | 6 +++--- doc/administration/config-cheat-sheet.en-us.md | 16 ++++++++-------- doc/administration/customizing-gitea.en-us.md | 2 +- .../environment-variables.en-us.md | 5 +---- doc/help/faq.en-us.md | 8 +++----- 6 files changed, 18 insertions(+), 33 deletions(-) diff --git a/doc/administration/backup-and-restore.en-us.md b/doc/administration/backup-and-restore.en-us.md index 7dee038b..5a722f49 100644 --- a/doc/administration/backup-and-restore.en-us.md +++ b/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 , 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: diff --git a/doc/administration/command-line.en-us.md b/doc/administration/command-line.en-us.md index d7e74ee2..2ac74896 100644 --- a/doc/administration/command-line.en-us.md +++ b/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). diff --git a/doc/administration/config-cheat-sheet.en-us.md b/doc/administration/config-cheat-sheet.en-us.md index 417f617c..dd59a4b9 100644 --- a/doc/administration/config-cheat-sheet.en-us.md +++ b/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`) diff --git a/doc/administration/customizing-gitea.en-us.md b/doc/administration/customizing-gitea.en-us.md index 4c8b1c90..8ab0d355 100644 --- a/doc/administration/customizing-gitea.en-us.md +++ b/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 diff --git a/doc/administration/environment-variables.en-us.md b/doc/administration/environment-variables.en-us.md index 92dbeb80..261d1bea 100644 --- a/doc/administration/environment-variables.en-us.md +++ b/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 diff --git a/doc/help/faq.en-us.md b/doc/help/faq.en-us.md index f609b6c8..f67c5a05 100644 --- a/doc/help/faq.en-us.md +++ b/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.