Make CustomPath, CustomConf and AppWorkPath configurable at build (#6631)

doc/advanced/customizing-gitea.en-us.md

@@ -15,19 +15,28 @@ menu:
 
 # Customizing Gitea
 
-Customizing Gitea is typically done using the `custom` folder. This is the central
+Customizing Gitea is typically done using the `CustomPath` folder - by default this is
-place to override configuration settings, templates, etc.
+the `custom` folder from the running directory, 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 override
+the `CustomPath` by setting either the `GITEA_CUSTOM` environment variable or by
+using the `--custom-path` option on the `gitea` binary. (The option will override the
+environment variable.)
 
 If Gitea is deployed from binary, all default paths will be relative to the Gitea
 binary. If installed from a distribution, these paths will likely be modified to
-the Linux Filesystem Standard. Gitea will create required folders, including `custom/`.
+the Linux Filesystem Standard. Gitea will attempt to create required folders, including
-Application settings are configured in `custom/conf/app.ini`. Distributions may
+`custom/`. Distributions may provide a symlink for `custom` using `/etc/gitea/`.
-provide a symlink for `custom` using `/etc/gitea/`.
+
+Application settings can be found in file `CustomConf` which is by default,
+`CustomPath/conf/app.ini` but may be different if your build has set this differently.
+Again `gitea help` will allow you review this variable and you can override it using the
+`--config` option on the `gitea` binary.
 
 - [Quick Cheat Sheet](https://docs.gitea.io/en-us/config-cheat-sheet/)
 - [Complete List](https://github.com/go-gitea/gitea/blob/master/custom/conf/app.ini.sample)
 
-If the `custom` folder can't be found next to the binary, check the `GITEA_CUSTOM`
+If the `CustomPath` folder can't be found despite checking `gitea help`, check the `GITEA_CUSTOM`
 environment variable; this can be used to override the default path to something else.
 `GITEA_CUSTOM` might, for example, be set by an init script.
 
@@ -38,7 +47,8 @@ environment variable; this can be used to override the default path to something
 ## Customizing /robots.txt
 
 To make Gitea serve a custom `/robots.txt` (default: empty 404), create a file called
-`robots.txt` in the `custom` folder with [expected contents](http://www.robotstxt.org/).
+`robots.txt` in the `custom` folder (or `CustomPath`) with
+[expected contents](http://www.robotstxt.org/).
 
 ## Serving custom public files
 

doc/installation/from-source.en-us.md

@@ -117,3 +117,26 @@ launched manually from command line, it can be killed by pressing `Ctrl + C`.
 ```bash
 ./gitea web
 ```
+
+## Changing the default CustomPath, CustomConf and AppWorkDir
+
+Gitea will search for a number of things from the `CustomPath`. By default this is
+the `custom/` directory in the current working directory when running Gitea. It will also
+look for its configuration file `CustomConf` in `$CustomPath/conf/app.ini`, and will use the
+current working directory as the relative base path `AppWorkDir` for a number configurable
+values.
+
+These values, although useful when developing, may conflict with downstream users preferences.
+
+One option is to use a script file to shadow the `gitea` binary and create an appropriate
+environment before running Gitea. However, when building you can change these defaults
+using the `LDFLAGS` environment variable for `make`. The appropriate settings are as follows
+
+* To set the `CustomPath` use `LDFLAGS="-X \"code.gitea.io/gitea/modules/setting.CustomPath=custom-path\""`
+* For `CustomConf` you should use `-X \"code.gitea.io/gitea/modules/setting.CustomConf=conf.ini\"`
+* For `AppWorkDir` you should use `-X \"code.gitea.io/gitea/modules/setting.AppWorkDir=working-directory\"`
+
+Add as many of the strings with their preceding `-X` to the `LDFLAGS` variable and run `make build`
+with the appropriate `TAGS` as above.
+
+Running `gitea help` will allow you to review what the computed settings will be for your `gitea`.

doc/usage/command-line.en-us.md

@@ -17,13 +17,16 @@ menu:
 
 ### Usage
 
-`gitea [global options] command [command options] [arguments...]`
+`gitea [global options] command [command or global options] [arguments...]`
 
 ### Global options
- - `--help`, `-h`: Show help text and exit. Optional. This can be used with any of the
+
-   subcommands to see help text for it.
+All global options can be placed at the command level.
- - `--version`, `-v`: Show version and exit. Optional. (example: `Gitea version
+
-   1.1.0+218-g7b907ed built with: bindata, sqlite`).
+- `--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: $PWD/custom).
+- `--config path`, `-c path`: Gitea configuration file path. Optional. (default: custom/conf/app.ini).
 
 ### Commands
 
@@ -33,7 +36,6 @@ Starts the server:
 
 - Options:
     - `--port number`, `-p number`: Port number. Optional. (default: 3000). Overrides configuration file.
-    - `--config path`, `-c path`: Gitea configuration file path. Optional. (default: custom/conf/app.ini).
     - `--pid path`, `-P path`: Pidfile path. Optional.
 - Examples:
     - `gitea web`
@@ -56,7 +58,6 @@ Admin operations:
             - `--password value`: Password. Required.
             - `--email value`: Email. Required.
             - `--admin`: If provided, this makes the user an admin. Optional.
-            - `--config path`: Gitea configuration file path. Optional. (default: custom/conf/app.ini).
             - `--must-change-password`: If provided, the created user will be required to choose a newer password after
 	    the initial login. Optional. (default: true).
             - ``--random-password``: If provided, a randomly generated password will be used as the password of
@@ -69,7 +70,6 @@ Admin operations:
         - Options:
             - `--username value`, `-u value`: Username. Required.
             - `--password value`, `-p value`: New password. Required.
-            - `--config path`: Gitea configuration file path. Optional. (default: custom/conf/app.ini).
         - Examples:
             - `gitea admin change-password --username myname --password asecurepassword`
     - `regenerate`
@@ -82,19 +82,15 @@ Admin operations:
     - `auth`:
         - `list`:
             - Description: lists all external authentication sources that exist
-            - Options:
-                - `--config path`: Gitea configuration file path. Optional. (default: custom/conf/app.ini).
             - Examples:
                 - `gitea admin auth list`
         - `delete`:
             - Options:
                 - `--id`: ID of source to be deleted. Required.
-                - `--config path`: Gitea configuration file path. Optional. (default: custom/conf/app.ini).
             - Examples:
                 - `gitea admin auth delete --id 1`
         - `add-oauth`:
             - Options:
-                - `--config path`: Gitea configuration file path. Optional. (default: custom/conf/app.ini).
                 - `--name`: Application Name.
                 - `--provider`: OAuth2 Provider.
                 - `--key`: Client ID (Key).
@@ -110,7 +106,6 @@ Admin operations:
         - `update-oauth`:
             - Options:
                 - `--id`: ID of source to be updated. Required.
-                - `--config path`: Gitea configuration file path. Optional. (default: custom/conf/app.ini).
                 - `--name`: Application Name.
                 - `--provider`: OAuth2 Provider.
                 - `--key`: Client ID (Key).
@@ -148,7 +143,6 @@ Dumps all files and databases into a zip file. Outputs into a file like `gitea-d
 in the current directory.
 
 - Options:
-    - `--config path`, `-c path`: Gitea configuration file path. Optional. (default: custom/conf/app.ini).
     - `--file name`, `-f name`: Name of the dump file with will be created. Optional. (default: gitea-dump-[timestamp].zip).
     - `--tempdir path`, `-t path`: Path to the temporary directory used. Optional. (default: /tmp).
     - `--skip-repository`, `-R`: Skip the repository dumping. Optional.