From 50e14699d3951ece4b9eb3f72cb266056e799f63 Mon Sep 17 00:00:00 2001 From: wxiaoguang Date: Wed, 19 Jul 2023 17:22:57 +0800 Subject: [PATCH] Update path related documents (#25417) 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: Giteabot --- custom/conf/app.example.ini | 16 ++++++++-------- .../administration/backup-and-restore.en-us.md | 14 ++------------ .../doc/administration/command-line.en-us.md | 6 +++--- .../administration/config-cheat-sheet.en-us.md | 16 ++++++++-------- .../administration/customizing-gitea.en-us.md | 2 +- .../environment-variables.en-us.md | 5 +---- docs/content/doc/help/faq.en-us.md | 8 +++----- modules/setting/path.go | 2 +- options/locale/locale_en-US.ini | 2 +- routers/web/admin/config.go | 2 +- templates/admin/config.tmpl | 4 ++-- 11 files changed, 31 insertions(+), 46 deletions(-) diff --git a/custom/conf/app.example.ini b/custom/conf/app.example.ini index 029a482fc..36ea7f3d9 100644 --- a/custom/conf/app.example.ini +++ b/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 = ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;; ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;; diff --git a/docs/content/doc/administration/backup-and-restore.en-us.md b/docs/content/doc/administration/backup-and-restore.en-us.md index 7dee038b5..5a722f496 100644 --- a/docs/content/doc/administration/backup-and-restore.en-us.md +++ b/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 , 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/docs/content/doc/administration/command-line.en-us.md b/docs/content/doc/administration/command-line.en-us.md index d7e74ee24..2ac74896e 100644 --- a/docs/content/doc/administration/command-line.en-us.md +++ b/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). diff --git a/docs/content/doc/administration/config-cheat-sheet.en-us.md b/docs/content/doc/administration/config-cheat-sheet.en-us.md index 05377d6ba..a78eff252 100644 --- a/docs/content/doc/administration/config-cheat-sheet.en-us.md +++ b/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`) diff --git a/docs/content/doc/administration/customizing-gitea.en-us.md b/docs/content/doc/administration/customizing-gitea.en-us.md index fc4ded899..60fcb2314 100644 --- a/docs/content/doc/administration/customizing-gitea.en-us.md +++ b/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 diff --git a/docs/content/doc/administration/environment-variables.en-us.md b/docs/content/doc/administration/environment-variables.en-us.md index 92dbeb80c..261d1bea5 100644 --- a/docs/content/doc/administration/environment-variables.en-us.md +++ b/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 diff --git a/docs/content/doc/help/faq.en-us.md b/docs/content/doc/help/faq.en-us.md index d0c4de61f..5a2cafba4 100644 --- a/docs/content/doc/help/faq.en-us.md +++ b/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. diff --git a/modules/setting/path.go b/modules/setting/path.go index 32ed8d81f..0fdc305aa 100644 --- a/modules/setting/path.go +++ b/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 diff --git a/options/locale/locale_en-US.ini b/options/locale/locale_en-US.ini index 77003351f..d00a2d838 100644 --- a/options/locale/locale_en-US.ini +++ b/options/locale/locale_en-US.ini @@ -2962,9 +2962,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 diff --git a/routers/web/admin/config.go b/routers/web/admin/config.go index 1c233ae85..b7d997681 100644 --- a/routers/web/admin/config.go +++ b/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 diff --git a/templates/admin/config.tmpl b/templates/admin/config.tmpl index c51f9cb0b..36d9bcb8a 100644 --- a/templates/admin/config.tmpl +++ b/templates/admin/config.tmpl @@ -34,10 +34,10 @@
+
{{.locale.Tr "admin.config.app_data_path"}}
+
{{.AppDataPath}}
{{.locale.Tr "admin.config.repo_root_path"}}
{{.RepoRootPath}}
-
{{.locale.Tr "admin.config.static_file_root_path"}}
-
{{.StaticRootPath}}
{{.locale.Tr "admin.config.custom_file_root_path"}}
{{.CustomRootPath}}
{{.locale.Tr "admin.config.log_file_root_path"}}