From 0f54f42646ca08a98b9b07ea069ff8e6236967d4 Mon Sep 17 00:00:00 2001
From: nodiscc <nodiscc@gmail.com>
Date: Thu, 4 Apr 2019 14:21:54 +0000
Subject: docs: document setup with read-only config (#6348)
---
docs/content/doc/installation/from-binary.en-us.md | 1 +
docs/content/doc/usage/command-line.en-us.md | 195 +++++++++++++++++++++
docs/content/doc/usage/command-line.md | 195 ---------------------
3 files changed, 196 insertions(+), 195 deletions(-)
create mode 100644 docs/content/doc/usage/command-line.en-us.md
delete mode 100644 docs/content/doc/usage/command-line.md
(limited to 'docs')
diff --git a/docs/content/doc/installation/from-binary.en-us.md b/docs/content/doc/installation/from-binary.en-us.md
index 8fa96bd96e..7e795029db 100644
--- a/docs/content/doc/installation/from-binary.en-us.md
+++ b/docs/content/doc/installation/from-binary.en-us.md
@@ -82,6 +82,7 @@ chmod 770 /etc/gitea
chmod 750 /etc/gitea
chmod 644 /etc/gitea/app.ini
```
+If you don't want the web installer to be able to write the config file at all, it is also possible to make the config file read-only for the gitea user (owner/group `root:root`, mode `0660`), and set `INSTALL_LOCK = true`. In that case all database configuration details must be set beforehand in the config file, as well as the `SECRET_KEY` and `INTERNAL_TOKEN` values. See the [command line documentation]({{< relref "doc/usage/command-line.en-us.md" >}}) for information on using `gitea generate secret INTERNAL_TOKEN`.
### Configure Gitea's working directory
diff --git a/docs/content/doc/usage/command-line.en-us.md b/docs/content/doc/usage/command-line.en-us.md
new file mode 100644
index 0000000000..510e90f954
--- /dev/null
+++ b/docs/content/doc/usage/command-line.en-us.md
@@ -0,0 +1,195 @@
+---
+date: "2017-01-01T16:00:00+02:00"
+title: "Usage: Command Line"
+slug: "command-line"
+weight: 10
+toc: true
+draft: false
+menu:
+ sidebar:
+ parent: "usage"
+ name: "Command Line"
+ weight: 10
+ identifier: "command-line"
+---
+
+## Command Line
+
+### Usage
+
+`gitea [global options] command [command 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.
+ - `--version`, `-v`: Show version and exit. Optional. (example: `Gitea version
+ 1.1.0+218-g7b907ed built with: bindata, sqlite`).
+
+### Commands
+
+#### web
+
+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`
+ - `gitea web --port 80`
+ - `gitea web --config /etc/gitea.ini --pid /var/run/gitea.pid`
+- Notes:
+ - Gitea should not be run as root. To bind to a port below 1000, you can use setcap on
+ Linux: `sudo setcap 'cap_net_bind_service=+ep' /path/to/gitea`. This will need to be
+ redone every time you update Gitea.
+
+#### admin
+
+Admin operations:
+
+- Commands:
+ - `create-user`
+ - Options:
+ - `--name value`: Username. Required.
+ - `--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
+ the created user. The value of `--password` will be discarded. Optional.
+ - `--random-password-length`: If provided, it will be used to configure the length of the randomly
+ generated password. Optional. (default: 12)
+ - Examples:
+ - `gitea admin create-user --name myname --password asecurepassword --email me@example.com`
+ - `change-password`
+ - 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`
+ - Options:
+ - `hooks`: Regenerate git-hooks for all repositories
+ - `keys`: Regenerate authorized_keys file
+ - Examples:
+ - `gitea admin regenerate hooks`
+ - `gitea admin regenerate keys`
+ - `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).
+ - `--secret`: Client Secret.
+ - `--auto-discover-url`: OpenID Connect Auto Discovery URL (only required when using OpenID Connect as provider).
+ - `--use-custom-urls`: Use custom URLs for GitLab/GitHub OAuth endpoints.
+ - `--custom-auth-url`: Use a custom Authorization URL (option for GitLab/GitHub).
+ - `--custom-token-url`: Use a custom Token URL (option for GitLab/GitHub).
+ - `--custom-profile-url`: Use a custom Profile URL (option for GitLab/GitHub).
+ - `--custom-email-url`: Use a custom Email URL (option for GitHub).
+ - Examples:
+ - `gitea admin auth add-oauth --name external-github --provider github --key OBTAIN_FROM_SOURCE --secret OBTAIN_FROM_SOURCE`
+ - `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).
+ - `--secret`: Client Secret.
+ - `--auto-discover-url`: OpenID Connect Auto Discovery URL (only required when using OpenID Connect as provider).
+ - `--use-custom-urls`: Use custom URLs for GitLab/GitHub OAuth endpoints.
+ - `--custom-auth-url`: Use a custom Authorization URL (option for GitLab/GitHub).
+ - `--custom-token-url`: Use a custom Token URL (option for GitLab/GitHub).
+ - `--custom-profile-url`: Use a custom Profile URL (option for GitLab/GitHub).
+ - `--custom-email-url`: Use a custom Email URL (option for GitHub).
+ - Examples:
+ - `gitea admin auth update-oauth --id 1 --name external-github-updated`
+
+#### cert
+
+Generates a self-signed SSL certificate. Outputs to `cert.pem` and `key.pem` in the current
+directory and will overwrite any existing files.
+
+- Options:
+ - `--host value`: Comma seperated hostnames and ips which this certificate is valid for.
+ Wildcards are supported. Required.
+ - `--ecdsa-curve value`: ECDSA curve to use to generate a key. Optional. Valid options
+ are P224, P256, P384, P521.
+ - `--rsa-bits value`: Size of RSA key to generate. Optional. Ignored if --ecdsa-curve is
+ set. (default: 2048).
+ - `--start-date value`: Creation date. Optional. (format: `Jan 1 15:04:05 2011`).
+ - `--duration value`: Duration which the certificate is valid for. Optional. (default: 8760h0m0s)
+ - `--ca`: If provided, this cert generates it's own certificate authority. Optional.
+- Examples:
+ - `gitea cert --host git.example.com,example.com,www.example.com --ca`
+
+#### dump
+
+Dumps all files and databases into a zip file. Outputs into a file like `gitea-dump-1482906742.zip`
+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.
+ - `--database`, `-d`: Specify the database SQL syntax. Optional.
+ - `--verbose`, `-v`: If provided, shows additional details. Optional.
+- Examples:
+ - `gitea dump`
+ - `gitea dump --verbose`
+
+#### generate
+
+Generates random values and tokens for usage in configuration file. Useful for generating values
+for automatic deployments.
+
+- Commands:
+ - `secret`:
+ - Options:
+ - `INTERNAL_TOKEN`: Token used for an internal API call authentication.
+ - `LFS_JWT_SECRET`: LFS authentication secret.
+ - `SECRET_KEY`: Global secret key.
+ - Examples:
+ - `gitea generate secret INTERNAL_TOKEN`
+ - `gitea generate secret LFS_JWT_SECRET`
+ - `gitea generate secret SECRET_KEY`
+
+#### keys
+
+Provides an SSHD AuthorizedKeysCommand. Needs to be configured in the sshd config file:
+
+```ini
+...
+# The value of -e and the AuthorizedKeysCommandUser should match the
+# username running gitea
+AuthorizedKeysCommandUser git
+AuthorizedKeysCommand /path/to/gitea keys -e git -u %u -t %t -k %k
+```
+
+The command will return the appropriate authorized_keys line for the
+provided key. You should also set the value
+`SSH_CREATE_AUTHORIZED_KEYS_FILE=false` in the `[server]` section of
+`app.ini`.
+
+NB: opensshd requires the gitea program to be owned by root and not
+writable by group or others. The program must be specified by an absolute
+path.
diff --git a/docs/content/doc/usage/command-line.md b/docs/content/doc/usage/command-line.md
deleted file mode 100644
index 510e90f954..0000000000
--- a/docs/content/doc/usage/command-line.md
+++ /dev/null
@@ -1,195 +0,0 @@
----
-date: "2017-01-01T16:00:00+02:00"
-title: "Usage: Command Line"
-slug: "command-line"
-weight: 10
-toc: true
-draft: false
-menu:
- sidebar:
- parent: "usage"
- name: "Command Line"
- weight: 10
- identifier: "command-line"
----
-
-## Command Line
-
-### Usage
-
-`gitea [global options] command [command 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.
- - `--version`, `-v`: Show version and exit. Optional. (example: `Gitea version
- 1.1.0+218-g7b907ed built with: bindata, sqlite`).
-
-### Commands
-
-#### web
-
-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`
- - `gitea web --port 80`
- - `gitea web --config /etc/gitea.ini --pid /var/run/gitea.pid`
-- Notes:
- - Gitea should not be run as root. To bind to a port below 1000, you can use setcap on
- Linux: `sudo setcap 'cap_net_bind_service=+ep' /path/to/gitea`. This will need to be
- redone every time you update Gitea.
-
-#### admin
-
-Admin operations:
-
-- Commands:
- - `create-user`
- - Options:
- - `--name value`: Username. Required.
- - `--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
- the created user. The value of `--password` will be discarded. Optional.
- - `--random-password-length`: If provided, it will be used to configure the length of the randomly
- generated password. Optional. (default: 12)
- - Examples:
- - `gitea admin create-user --name myname --password asecurepassword --email me@example.com`
- - `change-password`
- - 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`
- - Options:
- - `hooks`: Regenerate git-hooks for all repositories
- - `keys`: Regenerate authorized_keys file
- - Examples:
- - `gitea admin regenerate hooks`
- - `gitea admin regenerate keys`
- - `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).
- - `--secret`: Client Secret.
- - `--auto-discover-url`: OpenID Connect Auto Discovery URL (only required when using OpenID Connect as provider).
- - `--use-custom-urls`: Use custom URLs for GitLab/GitHub OAuth endpoints.
- - `--custom-auth-url`: Use a custom Authorization URL (option for GitLab/GitHub).
- - `--custom-token-url`: Use a custom Token URL (option for GitLab/GitHub).
- - `--custom-profile-url`: Use a custom Profile URL (option for GitLab/GitHub).
- - `--custom-email-url`: Use a custom Email URL (option for GitHub).
- - Examples:
- - `gitea admin auth add-oauth --name external-github --provider github --key OBTAIN_FROM_SOURCE --secret OBTAIN_FROM_SOURCE`
- - `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).
- - `--secret`: Client Secret.
- - `--auto-discover-url`: OpenID Connect Auto Discovery URL (only required when using OpenID Connect as provider).
- - `--use-custom-urls`: Use custom URLs for GitLab/GitHub OAuth endpoints.
- - `--custom-auth-url`: Use a custom Authorization URL (option for GitLab/GitHub).
- - `--custom-token-url`: Use a custom Token URL (option for GitLab/GitHub).
- - `--custom-profile-url`: Use a custom Profile URL (option for GitLab/GitHub).
- - `--custom-email-url`: Use a custom Email URL (option for GitHub).
- - Examples:
- - `gitea admin auth update-oauth --id 1 --name external-github-updated`
-
-#### cert
-
-Generates a self-signed SSL certificate. Outputs to `cert.pem` and `key.pem` in the current
-directory and will overwrite any existing files.
-
-- Options:
- - `--host value`: Comma seperated hostnames and ips which this certificate is valid for.
- Wildcards are supported. Required.
- - `--ecdsa-curve value`: ECDSA curve to use to generate a key. Optional. Valid options
- are P224, P256, P384, P521.
- - `--rsa-bits value`: Size of RSA key to generate. Optional. Ignored if --ecdsa-curve is
- set. (default: 2048).
- - `--start-date value`: Creation date. Optional. (format: `Jan 1 15:04:05 2011`).
- - `--duration value`: Duration which the certificate is valid for. Optional. (default: 8760h0m0s)
- - `--ca`: If provided, this cert generates it's own certificate authority. Optional.
-- Examples:
- - `gitea cert --host git.example.com,example.com,www.example.com --ca`
-
-#### dump
-
-Dumps all files and databases into a zip file. Outputs into a file like `gitea-dump-1482906742.zip`
-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.
- - `--database`, `-d`: Specify the database SQL syntax. Optional.
- - `--verbose`, `-v`: If provided, shows additional details. Optional.
-- Examples:
- - `gitea dump`
- - `gitea dump --verbose`
-
-#### generate
-
-Generates random values and tokens for usage in configuration file. Useful for generating values
-for automatic deployments.
-
-- Commands:
- - `secret`:
- - Options:
- - `INTERNAL_TOKEN`: Token used for an internal API call authentication.
- - `LFS_JWT_SECRET`: LFS authentication secret.
- - `SECRET_KEY`: Global secret key.
- - Examples:
- - `gitea generate secret INTERNAL_TOKEN`
- - `gitea generate secret LFS_JWT_SECRET`
- - `gitea generate secret SECRET_KEY`
-
-#### keys
-
-Provides an SSHD AuthorizedKeysCommand. Needs to be configured in the sshd config file:
-
-```ini
-...
-# The value of -e and the AuthorizedKeysCommandUser should match the
-# username running gitea
-AuthorizedKeysCommandUser git
-AuthorizedKeysCommand /path/to/gitea keys -e git -u %u -t %t -k %k
-```
-
-The command will return the appropriate authorized_keys line for the
-provided key. You should also set the value
-`SSH_CREATE_AUTHORIZED_KEYS_FILE=false` in the `[server]` section of
-`app.ini`.
-
-NB: opensshd requires the gitea program to be owned by root and not
-writable by group or others. The program must be specified by an absolute
-path.
--
cgit v1.2.3