From af79677a44aec3924823d90f42e5cc2e6e1b2961 Mon Sep 17 00:00:00 2001 From: Patrick Schratz Date: Wed, 9 Dec 2020 07:47:06 +0100 Subject: [PATCH] Reformat docs (#13897) Co-authored-by: 6543 <6543@obermui.de> Co-authored-by: Lauris BH --- .../doc/advanced/cmd-embedded.en-us.md | 20 +- .../doc/advanced/customizing-gitea.en-us.md | 66 +-- .../advanced/environment-variables.en-us.md | 48 +- .../doc/advanced/external-renderers.en-us.md | 16 +- .../advanced/logging-documentation.en-us.md | 184 ++++---- .../content/doc/advanced/mail-templates-us.md | 116 ++--- docs/content/doc/advanced/make.fr-fr.md | 2 +- docs/content/doc/advanced/make.zh-cn.md | 2 +- .../doc/advanced/repo-indexer.en-us.md | 22 +- .../search-engines-indexation.en-us.md | 2 +- docs/content/doc/advanced/signing.en-us.md | 72 +-- .../doc/advanced/third-party-tools.zh-cn.md | 2 +- .../content/doc/developers/api-usage.en-us.md | 27 +- .../content/doc/developers/api-usage.zh-cn.md | 2 +- .../doc/developers/hacking-on-gitea.en-us.md | 8 +- .../doc/developers/integrations.en-us.md | 2 +- .../doc/developers/migrations.en-us.md | 2 +- .../content/doc/developers/oauth2-provider.md | 86 ++-- .../doc/features/authentication.en-us.md | 100 ++-- .../doc/features/authentication.zh-cn.md | 2 +- .../doc/features/authentication.zh-tw.md | 2 +- docs/content/doc/features/comparison.en-us.md | 215 ++++----- docs/content/doc/features/comparison.zh-cn.md | 2 +- .../doc/features/localization.en-us.md | 2 +- .../doc/features/localization.zh-cn.md | 2 +- .../doc/features/localization.zh-tw.md | 2 +- docs/content/doc/features/webhooks.en-us.md | 2 +- docs/content/doc/features/webhooks.zh-cn.md | 2 +- docs/content/doc/features/webhooks.zh-tw.md | 2 +- docs/content/doc/help/faq.en-us.md | 160 ++++--- docs/content/doc/help/search.en-us.md | 2 +- docs/content/doc/help/search.fr-fr.md | 2 +- docs/content/doc/help/search.zh-cn.md | 2 +- docs/content/doc/help/search.zh-tw.md | 2 +- docs/content/doc/help/seek-help.en-us.md | 2 +- docs/content/doc/help/seek-help.zh-cn.md | 2 +- .../database-preparation.en-us.md | 29 +- .../doc/installation/from-binary.en-us.md | 4 +- .../doc/installation/from-binary.fr-fr.md | 2 +- .../doc/installation/from-binary.zh-cn.md | 2 +- .../doc/installation/from-binary.zh-tw.md | 2 +- .../doc/installation/from-package.en-us.md | 5 +- .../doc/installation/from-package.fr-fr.md | 2 +- .../doc/installation/from-package.zh-cn.md | 2 +- .../doc/installation/from-package.zh-tw.md | 2 +- .../doc/installation/from-source.en-us.md | 20 +- .../doc/installation/from-source.fr-fr.md | 2 +- .../doc/installation/from-source.zh-cn.md | 2 +- .../doc/installation/from-source.zh-tw.md | 2 +- .../doc/installation/on-kubernetes.en-us.md | 2 +- .../run-as-service-in-ubuntu.en-us.md | 2 +- .../run-as-service-in-ubuntu.zh-cn.md | 2 +- .../doc/installation/windows-service.en-us.md | 2 +- .../doc/installation/windows-service.fr-fr.md | 2 +- .../doc/installation/windows-service.zh-cn.md | 2 +- .../doc/installation/windows-service.zh-tw.md | 2 +- .../with-docker-rootless.en-us.md | 2 +- .../doc/installation/with-docker.en-us.md | 68 +-- .../doc/installation/with-docker.fr-fr.md | 2 +- .../doc/installation/with-docker.zh-cn.md | 2 +- .../doc/installation/with-docker.zh-tw.md | 2 +- docs/content/doc/upgrade/from-gogs.en-us.md | 6 +- docs/content/doc/upgrade/from-gogs.fr-fr.md | 2 +- docs/content/doc/upgrade/from-gogs.zh-cn.md | 2 +- docs/content/doc/upgrade/from-gogs.zh-tw.md | 2 +- .../doc/usage/backup-and-restore.en-us.md | 22 +- .../doc/usage/backup-and-restore.zh-cn.md | 2 +- .../doc/usage/backup-and-restore.zh-tw.md | 2 +- docs/content/doc/usage/command-line.en-us.md | 435 +++++++++--------- docs/content/doc/usage/email-setup.en-us.md | 9 +- .../content/doc/usage/fail2ban-setup.en-us.md | 2 +- docs/content/doc/usage/git-lfs-support.md | 2 +- docs/content/doc/usage/https-support.md | 15 +- .../issue-pull-request-templates.en-us.md | 64 +-- .../issue-pull-request-templates.zh-cn.md | 2 +- .../doc/usage/linked-references.en-us.md | 70 +-- docs/content/doc/usage/pull-request.en-us.md | 4 +- docs/content/doc/usage/pull-request.zh-cn.md | 2 +- docs/content/doc/usage/push-options.en-us.md | 2 +- .../doc/usage/reverse-proxies.en-us.md | 53 ++- .../doc/usage/reverse-proxies.zh-cn.md | 2 +- .../doc/usage/template-repositories.md | 40 +- docs/content/page/index.en-us.md | 2 +- docs/content/page/index.fr-fr.md | 2 +- docs/content/page/index.zh-cn.md | 2 +- docs/content/page/index.zh-tw.md | 2 +- 86 files changed, 1128 insertions(+), 970 deletions(-) diff --git a/docs/content/doc/advanced/cmd-embedded.en-us.md b/docs/content/doc/advanced/cmd-embedded.en-us.md index 7144aed4d..3bd80d134 100644 --- a/docs/content/doc/advanced/cmd-embedded.en-us.md +++ b/docs/content/doc/advanced/cmd-embedded.en-us.md @@ -3,7 +3,7 @@ date: "2020-01-25T21:00:00-03:00" title: "Embedded data extraction tool" slug: "cmd-embedded" weight: 40 -toc: true +toc: false draft: false menu: sidebar: @@ -15,6 +15,10 @@ menu: # Embedded data extraction tool +**Table of Contents** + +{{< toc >}} + Gitea's executable contains all the resources required to run: templates, images, style-sheets and translations. Any of them can be overridden by placing a replacement in a matching path inside the `custom` directory (see [Customizing Gitea]({{< relref "doc/advanced/customizing-gitea.en-us.md" >}})). @@ -28,7 +32,7 @@ can be used from the OS shell interface. To list resources embedded in Gitea's executable, use the following syntax: -``` +```sh gitea embedded list [--include-vendored] [patterns...] ``` @@ -48,11 +52,11 @@ a special meaning for your command shell. If no pattern is provided, all files are listed. -#### Example +### Example Listing all embedded files with `openid` in their path: -``` +```sh $ gitea embedded list '**openid**' public/img/auth/openid_connect.svg public/img/openid-16x16.png @@ -68,7 +72,7 @@ templates/user/settings/security_openid.tmpl To extract resources embedded in Gitea's executable, use the following syntax: -``` +```sh gitea [--config {file}] embedded extract [--destination {dir}|--custom] [--overwrite|--rename] [--include-vendored] {patterns...} ``` @@ -91,7 +95,7 @@ as `filename.bak`. Previous `.bak` files are overwritten. At least one file search pattern must be provided; see `list` subcomand above for pattern syntax and examples. -#### Important notice +### Important notice Make sure to **only extract those files that require customization**. Files that are present in the `custom` directory are not upgraded by Gitea's upgrade process. @@ -99,11 +103,11 @@ When Gitea is upgraded to a new version (by replacing the executable), many of t embedded files will suffer changes. Gitea will honor and use any files found in the `custom` directory, even if they are old and incompatible. -#### Example +### Example Extracting mail templates to a temporary directory: -``` +```sh $ mkdir tempdir $ gitea embedded extract --destination tempdir 'templates/mail/**.tmpl' Extracting to tempdir: diff --git a/docs/content/doc/advanced/customizing-gitea.en-us.md b/docs/content/doc/advanced/customizing-gitea.en-us.md index 718e3c6d9..118d5f2e6 100644 --- a/docs/content/doc/advanced/customizing-gitea.en-us.md +++ b/docs/content/doc/advanced/customizing-gitea.en-us.md @@ -45,7 +45,7 @@ environment variable; this can be used to override the default path to something **Note:** Gitea must perform a full restart to see configuration changes. -# Table of Contents +**Table of Contents** {{< toc >}} @@ -127,8 +127,8 @@ copy javascript files from https://gitea.com/davidsvantesson/plantuml-code-highl {{end}} ``` @@ -148,38 +148,50 @@ The script will detect tags with `class="language-plantuml"`, but you can change #### Example: STL Preview You can display STL file directly in Gitea by adding: + ```html ``` + to the file `templates/custom/footer.tmpl` You also need to download the content of the library [Madeleine.js](https://jinjunho.github.io/Madeleine.js/) and place it under `custom/public/` folder. You should end-up with a folder structucture similar to: + ``` custom/templates -- custom @@ -267,7 +279,7 @@ To add a custom license, add a file with the license text to `custom/options/lic Locales are managed via our [crowdin](https://crowdin.com/project/gitea). You can override a locale by placing an altered locale file in `custom/options/locale`. -Gitea's default locale files can be found in the [`options/locale`](https://github.com/go-gitea/gitea/tree/master/options/locale) source folder and these should be used as examples for your changes. +Gitea's default locale files can be found in the [`options/locale`](https://github.com/go-gitea/gitea/tree/master/options/locale) source folder and these should be used as examples for your changes. To add a completely new locale, as well as placing the file in the above location, you will need to add the new lang and name to the `[i18n]` section in your `app.ini`. Keep in mind that Gitea will use those settings as **overrides**, so if you want to keep the other languages as well you will need to copy/paste the default values and add your own to them. @@ -289,10 +301,12 @@ currently there are `{Name}` (name of repository), `{Description}`, `{CloneURL.S ### Reactions To change reaction emoji's you can set allowed reactions at app.ini + ``` [ui] REACTIONS = +1, -1, laugh, confused, heart, hooray, eyes ``` + A full list of supported emoji's is at [emoji list](https://gitea.com/gitea/gitea.com/issues/8) ## Customizing the look of Gitea diff --git a/docs/content/doc/advanced/environment-variables.en-us.md b/docs/content/doc/advanced/environment-variables.en-us.md index bfc5fedcf..deb195aeb 100644 --- a/docs/content/doc/advanced/environment-variables.en-us.md +++ b/docs/content/doc/advanced/environment-variables.en-us.md @@ -15,11 +15,15 @@ menu: # Environment variables +**Table of Contents** + +{{< toc >}} + This is an inventory of Gitea environment variables. They change Gitea behaviour. Initialize them before Gitea command to be effective, for example: -``` +```sh GITEA_CUSTOM=/home/gitea/custom ./gitea web ``` @@ -27,42 +31,42 @@ GITEA_CUSTOM=/home/gitea/custom ./gitea web As Gitea is written in Go, it uses some Go variables, such as: - * `GOOS` - * `GOARCH` - * [`GOPATH`](https://golang.org/cmd/go/#hdr-GOPATH_environment_variable) +- `GOOS` +- `GOARCH` +- [`GOPATH`](https://golang.org/cmd/go/#hdr-GOPATH_environment_variable) For documentation about each of the variables available, refer to the [official Go documentation](https://golang.org/cmd/go/#hdr-Environment_variables). ## 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_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` ## Operating system specifics - * `USER`: System user that Gitea will run as. Used for some repository access strings. - * `USERNAME`: if no `USER` found, Gitea will use `USERNAME` - * `HOME`: User home directory path. The `USERPROFILE` environment variable is used in Windows. +- `USER`: System user that Gitea will run as. Used for some repository access strings. +- `USERNAME`: if no `USER` found, Gitea will use `USERNAME` +- `HOME`: User home directory path. The `USERPROFILE` environment variable is used in Windows. ### Only on Windows - * `USERPROFILE`: User home directory path. If empty, uses `HOMEDRIVE` + `HOMEPATH` - * `HOMEDRIVE`: Main drive path used to access the home directory (C:) - * `HOMEPATH`: Home relative path in the given home drive path +- `USERPROFILE`: User home directory path. If empty, uses `HOMEDRIVE` + `HOMEPATH` +- `HOMEDRIVE`: Main drive path used to access the home directory (C:) +- `HOMEPATH`: Home relative path in the given home drive path ## Macaron (framework used by Gitea) - * `HOST`: Host Macaron will listen on - * `PORT`: Port Macaron will listen on - * `MACARON_ENV`: global variable to provide special functionality for development environments - vs. production environments. If MACARON_ENV is set to "" or "development", then templates will - be recompiled on every request. For more performance, set the MACARON_ENV environment variable - to "production". +- `HOST`: Host Macaron will listen on +- `PORT`: Port Macaron will listen on +- `MACARON_ENV`: global variable to provide special functionality for development environments + vs. production environments. If MACARON_ENV is set to "" or "development", then templates will + be recompiled on every request. For more performance, set the MACARON_ENV environment variable + to "production". ## Miscellaneous - * `SKIP_MINWINSVC`: If set to 1, do not run as a service on Windows. +- `SKIP_MINWINSVC`: If set to 1, do not run as a service on Windows. diff --git a/docs/content/doc/advanced/external-renderers.en-us.md b/docs/content/doc/advanced/external-renderers.en-us.md index 19a065911..11e7f73ae 100644 --- a/docs/content/doc/advanced/external-renderers.en-us.md +++ b/docs/content/doc/advanced/external-renderers.en-us.md @@ -3,7 +3,7 @@ date: "2018-11-23:00:00+02:00" title: "External renderers" slug: "external-renderers" weight: 40 -toc: true +toc: false draft: false menu: sidebar: @@ -15,12 +15,16 @@ menu: # Custom files rendering configuration +**Table of Contents** + +{{< toc >}} + Gitea supports custom file renderings (i.e., Jupyter notebooks, asciidoc, etc.) through external binaries, it is just a matter of: -* installing external binaries -* add some configuration to your `app.ini` file -* restart your Gitea instance +- installing external binaries +- add some configuration to your `app.ini` file +- restart your Gitea instance This supports rendering of whole files. If you want to render code blocks in markdown you would need to do something with javascript. See some examples on the [Customizing Gitea](../customizing-gitea) page. @@ -29,7 +33,7 @@ This supports rendering of whole files. If you want to render code blocks in mar In order to get file rendering through external binaries, their associated packages must be installed. If you're using a Docker image, your `Dockerfile` should contain something along this lines: -``` +```docker FROM gitea/gitea:{{< version >}} [...] @@ -49,7 +53,7 @@ RUN pip3 install jupyter docutils add one `[markup.XXXXX]` section per external renderer on your custom `app.ini`: -``` +```ini [markup.asciidoc] ENABLED = true FILE_EXTENSIONS = .adoc,.asciidoc diff --git a/docs/content/doc/advanced/logging-documentation.en-us.md b/docs/content/doc/advanced/logging-documentation.en-us.md index 8f6a5b79b..bf9fc4888 100644 --- a/docs/content/doc/advanced/logging-documentation.en-us.md +++ b/docs/content/doc/advanced/logging-documentation.en-us.md @@ -3,7 +3,7 @@ date: "2019-04-02T17:06:00+01:00" title: "Advanced: Logging Configuration" slug: "logging-configuration" weight: 55 -toc: true +toc: false draft: false menu: sidebar: @@ -17,6 +17,8 @@ menu: The logging framework has been revamped in Gitea 1.9.0. +**Table of Contents** + {{< toc >}} ## Log Groups @@ -24,11 +26,11 @@ The logging framework has been revamped in Gitea 1.9.0. The fundamental thing to be aware of in Gitea is that there are several log groups: -* The "Default" logger -* The Macaron logger -* The Router logger -* The Access logger -* The XORM logger +- The "Default" logger +- The Macaron logger +- The Router logger +- The Access logger +- The XORM logger There is also the go log logger. @@ -55,11 +57,11 @@ which inherits from the sublogger `[log.sublogger]` section and from the generic `[log]` section, but there are certain default values. These will not be inherited from the `[log]` section: -* `FLAGS` is `stdflags` (Equal to -`date,time,medfile,shortfuncname,levelinitial`) -* `FILE_NAME` will default to `%(ROOT_PATH)/gitea.log` -* `EXPRESSION` will default to `""` -* `PREFIX` will default to `""` +- `FLAGS` is `stdflags` (Equal to + `date,time,medfile,shortfuncname,levelinitial`) +- `FILE_NAME` will default to `%(ROOT_PATH)/gitea.log` +- `EXPRESSION` will default to `""` +- `PREFIX` will default to `""` The provider type of the sublogger can be set using the `MODE` value in its subsection, but will default to the name. This allows you to have @@ -82,11 +84,11 @@ Each output sublogger for this logger is configured in which will not be inherited from the `[log]` or relevant `[log.sublogger]` sections: -* `FLAGS` is `stdflags` (Equal to -`date,time,medfile,shortfuncname,levelinitial`) -* `FILE_NAME` will default to `%(ROOT_PATH)/macaron.log` -* `EXPRESSION` will default to `""` -* `PREFIX` will default to `""` +- `FLAGS` is `stdflags` (Equal to + `date,time,medfile,shortfuncname,levelinitial`) +- `FILE_NAME` will default to `%(ROOT_PATH)/macaron.log` +- `EXPRESSION` will default to `""` +- `PREFIX` will default to `""` NB: You can redirect the macaron logger to send its events to the gitea log using the value: `MACARON = ,` @@ -113,10 +115,10 @@ Each output sublogger for this logger is configured in which will not be inherited from the `[log]` or relevant `[log.sublogger]` sections: -* `FILE_NAME` will default to `%(ROOT_PATH)/router.log` -* `FLAGS` defaults to `date,time` -* `EXPRESSION` will default to `""` -* `PREFIX` will default to `""` +- `FILE_NAME` will default to `%(ROOT_PATH)/router.log` +- `FLAGS` defaults to `date,time` +- `EXPRESSION` will default to `""` +- `PREFIX` will default to `""` NB: You can redirect the router logger to send its events to the Gitea log using the value: `ROUTER = ,` @@ -138,10 +140,10 @@ Each output sublogger for this logger is configured in which will not be inherited from the `[log]` or relevant `[log.sublogger]` sections: -* `FILE_NAME` will default to `%(ROOT_PATH)/access.log` -* `FLAGS` defaults to `` or None -* `EXPRESSION` will default to `""` -* `PREFIX` will default to `""` +- `FILE_NAME` will default to `%(ROOT_PATH)/access.log` +- `FLAGS` defaults to `` or None +- `EXPRESSION` will default to `""` +- `PREFIX` will default to `""` If desired the format of the Access logger can be changed by changing the value of the `ACCESS_LOG_TEMPLATE`. @@ -160,11 +162,11 @@ This value represent a go template. It's default value is: The template is passed following options: -* `Ctx` is the `macaron.Context` -* `Identity` is the `SignedUserName` or `"-"` if the user is not logged -in -* `Start` is the start time of the request -* `ResponseWriter` is the `macaron.ResponseWriter` +- `Ctx` is the `macaron.Context` +- `Identity` is the `SignedUserName` or `"-"` if the user is not logged + in +- `Start` is the start time of the request +- `ResponseWriter` is the `macaron.ResponseWriter` Caution must be taken when changing this template as it runs outside of the standard panic recovery trap. The template should also be as simple @@ -187,31 +189,31 @@ Each output sublogger for this logger is configured in which will not be inherited from the `[log]` or relevant `[log.sublogger]` sections: -* `FILE_NAME` will default to `%(ROOT_PATH)/xorm.log` -* `FLAGS` defaults to `date,time` -* `EXPRESSION` will default to `""` -* `PREFIX` will default to `""` +- `FILE_NAME` will default to `%(ROOT_PATH)/xorm.log` +- `FLAGS` defaults to `date,time` +- `EXPRESSION` will default to `""` +- `PREFIX` will default to `""` ## Log outputs Gitea provides 4 possible log outputs: -* `console` - Log to `os.Stdout` or `os.Stderr` -* `file` - Log to a file -* `conn` - Log to a keep-alive TCP connection -* `smtp` - Log via email +- `console` - Log to `os.Stdout` or `os.Stderr` +- `file` - Log to a file +- `conn` - Log to a keep-alive TCP connection +- `smtp` - Log via email Certain configuration is common to all modes of log output: -* `LEVEL` is the lowest level that this output will log. This value -is inherited from `[log]` and in the case of the non-default loggers -from `[log.sublogger]`. -* `STACKTRACE_LEVEL` is the lowest level that this output will print -a stacktrace. This value is inherited. -* `MODE` is the mode of the log output. It will default to the sublogger -name. Thus `[log.console.macaron]` will default to `MODE = console`. -* `COLORIZE` will default to `true` for `console` as -described, otherwise it will default to `false`. +- `LEVEL` is the lowest level that this output will log. This value + is inherited from `[log]` and in the case of the non-default loggers + from `[log.sublogger]`. +- `STACKTRACE_LEVEL` is the lowest level that this output will print + a stacktrace. This value is inherited. +- `MODE` is the mode of the log output. It will default to the sublogger + name. Thus `[log.console.macaron]` will default to `MODE = console`. +- `COLORIZE` will default to `true` for `console` as + described, otherwise it will default to `false`. ### Non-inherited default values @@ -233,23 +235,23 @@ printed before each message. It is a comma-separated string set. The order of va Possible values are: -* `none` or `,` - No flags. -* `date` - the date in the local time zone: `2009/01/23`. -* `time` - the time in the local time zone: `01:23:23`. -* `microseconds` - microsecond resolution: `01:23:23.123123`. Assumes -time. -* `longfile` - full file name and line number: `/a/b/c/d.go:23`. -* `shortfile` - final file name element and line number: `d.go:23`. -* `funcname` - function name of the caller: `runtime.Caller()`. -* `shortfuncname` - last part of the function name. Overrides -`funcname`. -* `utc` - if date or time is set, use UTC rather than the local time -zone. -* `levelinitial` - Initial character of the provided level in brackets eg. `[I]` for info. -* `level` - Provided level in brackets `[INFO]` -* `medfile` - Last 20 characters of the filename - equivalent to -`shortfile,longfile`. -* `stdflags` - Equivalent to `date,time,medfile,shortfuncname,levelinitial` +- `none` or `,` - No flags. +- `date` - the date in the local time zone: `2009/01/23`. +- `time` - the time in the local time zone: `01:23:23`. +- `microseconds` - microsecond resolution: `01:23:23.123123`. Assumes + time. +- `longfile` - full file name and line number: `/a/b/c/d.go:23`. +- `shortfile` - final file name element and line number: `d.go:23`. +- `funcname` - function name of the caller: `runtime.Caller()`. +- `shortfuncname` - last part of the function name. Overrides + `funcname`. +- `utc` - if date or time is set, use UTC rather than the local time + zone. +- `levelinitial` - Initial character of the provided level in brackets eg. `[I]` for info. +- `level` - Provided level in brackets `[INFO]` +- `medfile` - Last 20 characters of the filename - equivalent to + `shortfile,longfile`. +- `stdflags` - Equivalent to `date,time,medfile,shortfuncname,levelinitial` ### Console mode @@ -267,30 +269,30 @@ to the provided `ROOT_PATH` in the master `[log]` section. Other values: -* `LOG_ROTATE`: **true**: Rotate the log files. -* `MAX_SIZE_SHIFT`: **28**: Maximum size shift of a single file, 28 represents 256Mb. -* `DAILY_ROTATE`: **true**: Rotate logs daily. -* `MAX_DAYS`: **7**: Delete the log file after n days -* `COMPRESS`: **true**: Compress old log files by default with gzip -* `COMPRESSION_LEVEL`: **-1**: Compression level +- `LOG_ROTATE`: **true**: Rotate the log files. +- `MAX_SIZE_SHIFT`: **28**: Maximum size shift of a single file, 28 represents 256Mb. +- `DAILY_ROTATE`: **true**: Rotate logs daily. +- `MAX_DAYS`: **7**: Delete the log file after n days +- `COMPRESS`: **true**: Compress old log files by default with gzip +- `COMPRESSION_LEVEL`: **-1**: Compression level ### Conn mode -* `RECONNECT_ON_MSG`: **false**: Reconnect host for every single message. -* `RECONNECT`: **false**: Try to reconnect when connection is lost. -* `PROTOCOL`: **tcp**: Set the protocol, either "tcp", "unix" or "udp". -* `ADDR`: **:7020**: Sets the address to connect to. +- `RECONNECT_ON_MSG`: **false**: Reconnect host for every single message. +- `RECONNECT`: **false**: Try to reconnect when connection is lost. +- `PROTOCOL`: **tcp**: Set the protocol, either "tcp", "unix" or "udp". +- `ADDR`: **:7020**: Sets the address to connect to. ### SMTP mode It is not recommended to use this logger to send general logging messages. However, you could perhaps set this logger to work on `FATAL`. -* `USER`: User email address to send from. -* `PASSWD`: Password for the smtp server. -* `HOST`: **127.0.0.1:25**: The SMTP host to connect to. -* `RECEIVERS`: Email addresses to send to. -* `SUBJECT`: **Diagnostic message from Gitea** +- `USER`: User email address to send from. +- `PASSWD`: Password for the smtp server. +- `HOST`: **127.0.0.1:25**: The SMTP host to connect to. +- `RECEIVERS`: Email addresses to send to. +- `SUBJECT`: **Diagnostic message from Gitea** ## Debugging problems @@ -386,7 +388,7 @@ Windows. Terminal sniffing will occur on Windows and if it is determined that we are running on a terminal capable of color we will colorize. -Further, on *nix it is becoming common to have file logs that are +Further, on \*nix it is becoming common to have file logs that are colored by default. Therefore file logs will be colorised by default when not running on Windows. @@ -404,14 +406,14 @@ string of bytes which should represent a color and second set of reset bytes. Pointers were chosen to prevent copying of large numbers of values. There are several helper methods: -* `log.NewColoredValue` takes a value and 0 or more color attributes -that represent the color. If 0 are provided it will default to a cached -bold. Note, it is recommended that color bytes constructed from -attributes should be cached if this is a commonly used log message. -* `log.NewColoredValuePointer` takes a pointer to a value, and -0 or more color attributes that represent the color. -* `log.NewColoredValueBytes` takes a value and a pointer to an array -of bytes representing the color. +- `log.NewColoredValue` takes a value and 0 or more color attributes + that represent the color. If 0 are provided it will default to a cached + bold. Note, it is recommended that color bytes constructed from + attributes should be cached if this is a commonly used log message. +- `log.NewColoredValuePointer` takes a pointer to a value, and + 0 or more color attributes that represent the color. +- `log.NewColoredValueBytes` takes a value and a pointer to an array + of bytes representing the color. These functions will not double wrap a `log.ColoredValue`. They will also set the `resetBytes` to the cached `resetBytes`. @@ -467,9 +469,9 @@ You should then add `newOneLogService` to `NewServices()` in Gitea includes built-in log rotation, which should be enough for most deployments. However, if you instead want to use the `logrotate` utility: -- Disable built-in log rotation by setting `LOG_ROTATE` to `false` in your `app.ini`. -- Install `logrotate`. -- Configure `logrotate` to match your deployment requirements, see `man 8 logrotate` for configuration syntax details. In the `postrotate/endscript` block send Gitea a `USR1` signal via `kill -USR1` or `kill -10`, or run `gitea manager logging release-and-reopen` (with the appropriate environment). Ensure that your configurations apply to all files emitted by Gitea loggers as described in the above sections. -- Always do `logrotate /etc/logrotate.conf --debug` to test your configurations. +- Disable built-in log rotation by setting `LOG_ROTATE` to `false` in your `app.ini`. +- Install `logrotate`. +- Configure `logrotate` to match your deployment requirements, see `man 8 logrotate` for configuration syntax details. In the `postrotate/endscript` block send Gitea a `USR1` signal via `kill -USR1` or `kill -10`, or run `gitea manager logging release-and-reopen` (with the appropriate environment). Ensure that your configurations apply to all files emitted by Gitea loggers as described in the above sections. +- Always do `logrotate /etc/logrotate.conf --debug` to test your configurations. The next `logrotate` jobs will include your configurations, so no restart is needed. You can also immediately reload `logrotate` with `logrotate /etc/logrotate.conf --force`. diff --git a/docs/content/doc/advanced/mail-templates-us.md b/docs/content/doc/advanced/mail-templates-us.md index 1d1423122..247f31f68 100644 --- a/docs/content/doc/advanced/mail-templates-us.md +++ b/docs/content/doc/advanced/mail-templates-us.md @@ -3,7 +3,7 @@ date: "2019-10-23T17:00:00-03:00" title: "Mail templates" slug: "mail-templates" weight: 45 -toc: true +toc: false draft: false menu: sidebar: @@ -15,41 +15,44 @@ menu: # Mail templates +**Table of Contents** + +{{< toc >}} + To craft the e-mail subject and contents for certain operations, Gitea can be customized by using templates. The templates for these functions are located under the [`custom` directory](https://docs.gitea.io/en-us/customizing-gitea/). Gitea has an internal template that serves as default in case there's no custom alternative. Custom templates are loaded when Gitea starts. Changes made to them are not recognized until Gitea is restarted again. -{{< toc >}} - ## Mail notifications supporting templates Currently, the following notification events make use of templates: -| Action name | Usage | -|---------------|--------------------------------------------------------------------------------------------------------------| -| `new` | A new issue or pull request was created. | -| `comment` | A new comment was created in an existing issue or pull request. | -| `close` | An issue or pull request was closed. | -| `reopen` | An issue or pull request was reopened. | -| `review` | The head comment of a review in a pull request. | -| `approve` | The head comment of a approving review for a pull request. | -| `reject` | The head comment of a review requesting changes for a pull request. | -| `code` | A single comment on the code of a pull request. | -| `assigned` | Used was assigned to an issue or pull request. | -| `default` | Any action not included in the above categories, or when the corresponding category template is not present. | +| Action name | Usage | +| ----------- | ------------------------------------------------------------------------------------------------------------ | +| `new` | A new issue or pull request was created. | +| `comment` | A new comment was created in an existing issue or pull request. | +| `close` | An issue or pull request was closed. | +| `reopen` | An issue or pull request was reopened. | +| `review` | The head comment of a review in a pull request. | +| `approve` | The head comment of a approving review for a pull request. | +| `reject` | The head comment of a review requesting changes for a pull request. | +| `code` | A single comment on the code of a pull request. | +| `assigned` | Used was assigned to an issue or pull request. | +| `default` | Any action not included in the above categories, or when the corresponding category template is not present. | The path for the template of a particular message type is: -``` +```sh custom/templates/mail/{action type}/{action name}.tmpl ``` Where `{action type}` is one of `issue` or `pull` (for pull requests), and `{action name}` is one of the names listed above. For example, the specific template for a mail regarding a comment in a pull request is: -``` + +```sh custom/templates/mail/pull/comment.tmpl ``` @@ -57,10 +60,10 @@ However, creating templates for each and every action type/name combination is n A fallback system is used to choose the appropriate template for an event. The _first existing_ template on this list is used: -* The specific template for the desired **action type** and **action name**. -* The template for action type `issue` and the desired **action name**. -* The template for the desired **action type**, action name `default`. -* The template for action type `issue`, action name `default`. +- The specific template for the desired **action type** and **action name**. +- The template for action type `issue` and the desired **action name**. +- The template for the desired **action type**, action name `default`. +- The template for action type `issue`, action name `default`. The only mandatory template is action type `issue`, action name `default`, which is already embedded in Gitea unless it's overridden by the user in the `custom` directory. @@ -84,27 +87,26 @@ Text and macros for the mail body Specifying a _subject_ section is optional (and therefore also the dash line separator). When used, the separator between _subject_ and _mail body_ templates requires at least three dashes; no other characters are allowed in the separator line. - _Subject_ and _mail body_ are parsed by [Golang's template engine](https://golang.org/pkg/text/template/) and are provided with a _metadata context_ assembled for each notification. The context contains the following elements: -| Name | Type | Available | Usage | -|--------------------|------------------|---------------|------------------------------------------------------------------------------------------------------------------------------------------------------| -| `.FallbackSubject` | string | Always | A default subject line. See Below. | -| `.Subject` | string | Only in body | The _subject_, once resolved. | -| `.Body` | string | Always | The message of the issue, pull request or comment, parsed from Markdown into HTML and sanitized. Do not confuse with the _mail body_. | -| `.Link` | string | Always | The address of the originating issue, pull request or comment. | -| `.Issue` | models.Issue | Always | The issue (or pull request) originating the notification. To get data specific to a pull request (e.g. `HasMerged`), `.Issue.PullRequest` can be used, but care should be taken as this field will be `nil` if the issue is *not* a pull request. | -| `.Comment` | models.Comment | If applicable | If the notification is from a comment added to an issue or pull request, this will contain the information about the comment. | -| `.IsPull` | bool | Always | `true` if the mail notification is associated with a pull request (i.e. `.Issue.PullRequest` is not `nil`). | -| `.Repo` | string | Always | Name of the repository, including owner name (e.g. `mike/stuff`) | -| `.User` | models.User | Always | Owner of the repository from which the event originated. To get the user name (e.g. `mike`),`.User.Name` can be used. | -| `.Doer` | models.User | Always | User that executed the action triggering the notification event. To get the user name (e.g. `rhonda`), `.Doer.Name` can be used. | -| `.IsMention` | bool | Always | `true` if this notification was only generated because the user was mentioned in the comment, while not being subscribed to the source. It will be `false` if the recipient was subscribed to the issue or repository. | -| `.SubjectPrefix` | string | Always | `Re: ` if the notification is about other than issue or pull request creation; otherwise an empty string. | -| `.ActionType` | string | Always | `"issue"` or `"pull"`. Will correspond to the actual _action type_ independently of which template was selected. | -| `.ActionName` | string | Always | It will be one of the action types described above (`new`, `comment`, etc.), and will correspond to the actual _action name_ independently of which template was selected. | -| `.ReviewComments` | []models.Comment | Always | List of code comments in a review. The comment text will be in `.RenderedContent` and the referenced code will be in `.Patch`. | +| Name | Type | Available | Usage | +| ------------------ | ---------------- | ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `.FallbackSubject` | string | Always | A default subject line. See Below. | +| `.Subject` | string | Only in body | The _subject_, once resolved. | +| `.Body` | string | Always | The message of the issue, pull request or comment, parsed from Markdown into HTML and sanitized. Do not confuse with the _mail body_. | +| `.Link` | string | Always | The address of the originating issue, pull request or comment. | +| `.Issue` | models.Issue | Always | The issue (or pull request) originating the notification. To get data specific to a pull request (e.g. `HasMerged`), `.Issue.PullRequest` can be used, but care should be taken as this field will be `nil` if the issue is _not_ a pull request. | +| `.Comment` | models.Comment | If applicable | If the notification is from a comment added to an issue or pull request, this will contain the information about the comment. | +| `.IsPull` | bool | Always | `true` if the mail notification is associated with a pull request (i.e. `.Issue.PullRequest` is not `nil`). | +| `.Repo` | string | Always | Name of the repository, including owner name (e.g. `mike/stuff`) | +| `.User` | models.User | Always | Owner of the repository from which the event originated. To get the user name (e.g. `mike`),`.User.Name` can be used. | +| `.Doer` | models.User | Always | User that executed the action triggering the notification event. To get the user name (e.g. `rhonda`), `.Doer.Name` can be used. | +| `.IsMention` | bool | Always | `true` if this notification was only generated because the user was mentioned in the comment, while not being subscribed to the source. It will be `false` if the recipient was subscribed to the issue or repository. | +| `.SubjectPrefix` | string | Always | `Re: ` if the notification is about other than issue or pull request creation; otherwise an empty string. | +| `.ActionType` | string | Always | `"issue"` or `"pull"`. Will correspond to the actual _action type_ independently of which template was selected. | +| `.ActionName` | string | Always | It will be one of the action types described above (`new`, `comment`, etc.), and will correspond to the actual _action name_ independently of which template was selected. | +| `.ReviewComments` | []models.Comment | Always | List of code comments in a review. The comment text will be in `.RenderedContent` and the referenced code will be in `.Patch`. | All names are case sensitive. @@ -115,19 +117,19 @@ Please refer to the linked documentation for details about its syntax. The _subject_ is built using the following steps: -* A template is selected according to the type of notification and to what templates are present. -* The template is parsed and resolved (e.g. `{{.Issue.Index}}` is converted to the number of the issue +- A template is selected according to the type of notification and to what templates are present. +- The template is parsed and resolved (e.g. `{{.Issue.Index}}` is converted to the number of the issue or pull request). -* All space-like characters (e.g. `TAB`, `LF`, etc.) are converted to normal spaces. -* All leading, trailing and redundant spaces are removed. -* The string is truncated to its first 256 runes (characters). +- All space-like characters (e.g. `TAB`, `LF`, etc.) are converted to normal spaces. +- All leading, trailing and redundant spaces are removed. +- The string is truncated to its first 256 runes (characters). If the end result is an empty string, **or** no subject template was available (i.e. the selected template did not include a subject part), Gitea's **internal default** will be used. The internal default (fallback) subject is the equivalent of: -``` +```sh {{.SubjectPrefix}}[{{.Repo}}] {{.Issue.Title}} (#.Issue.Index) ``` @@ -171,7 +173,7 @@ Please check [Gitea's logs](https://docs.gitea.io/en-us/logging-configuration/) `custom/templates/mail/issue/default.tmpl`: -``` +```html [{{.Repo}}] @{{.Doer.Name}} {{if eq .ActionName "new"}} created @@ -247,10 +249,10 @@ This template produces something along these lines: > > #### Message content: > -> \__________________________________________________________________ +> \_********************************\_******************************** > > Mike, I think we should tone down the blues a little. -> \__________________________________________________________________ +> \_********************************\_******************************** > > [View it on Gitea](#). @@ -259,18 +261,18 @@ This template produces something along these lines: The template system contains several functions that can be used to further process and format the messages. Here's a list of some of them: -| Name | Parameters | Available | Usage | -|----------------------|-------------|-----------|------------------------------------------------------------------------------| -| `AppUrl` | - | Any | Gitea's URL | -| `AppName` | - | Any | Set from `app.ini`, usually "Gitea" | -| `AppDomain` | - | Any | Gitea's host name | -| `EllipsisString` | string, int | Any | Truncates a string to the specified length; adds ellipsis as needed | -| `Str2html` | string | Body only | Sanitizes text by removing any HTML tags from it. | -| `Safe` | string | Body only | Takes the input as HTML; can be used for `.ReviewComments.RenderedContent`. | +| Name | Parameters | Available | Usage | +| ---------------- | ----------- | --------- | --------------------------------------------------------------------------- | +| `AppUrl` | - | Any | Gitea's URL | +| `AppName` | - | Any | Set from `app.ini`, usually "Gitea" | +| `AppDomain` | - | Any | Gitea's host name | +| `EllipsisString` | string, int | Any | Truncates a string to the specified length; adds ellipsis as needed | +| `Str2html` | string | Body only | Sanitizes text by removing any HTML tags from it. | +| `Safe` | string | Body only | Takes the input as HTML; can be used for `.ReviewComments.RenderedContent`. | These are _functions_, not metadata, so they have to be used: -``` +```html Like this: {{Str2html "Escapetext"}} Or this: {{"Escapetext" | Str2html}} Or this: {{AppUrl}} diff --git a/docs/content/doc/advanced/make.fr-fr.md b/docs/content/doc/advanced/make.fr-fr.md index 626ad8005..e8ba1912e 100644 --- a/docs/content/doc/advanced/make.fr-fr.md +++ b/docs/content/doc/advanced/make.fr-fr.md @@ -3,7 +3,7 @@ date: "2017-08-23T09:00:00+02:00" title: "Make" slug: "make" weight: 10 -toc: true +toc: false draft: false menu: sidebar: diff --git a/docs/content/doc/advanced/make.zh-cn.md b/docs/content/doc/advanced/make.zh-cn.md index 04a971a37..2491dbe23 100644 --- a/docs/content/doc/advanced/make.zh-cn.md +++ b/docs/content/doc/advanced/make.zh-cn.md @@ -3,7 +3,7 @@ date: "2017-01-14T11:00:00-02:00" title: "Make 安装" slug: "make" weight: 10 -toc: true +toc: false draft: false menu: sidebar: diff --git a/docs/content/doc/advanced/repo-indexer.en-us.md b/docs/content/doc/advanced/repo-indexer.en-us.md index 11ed28377..4b81bd27e 100644 --- a/docs/content/doc/advanced/repo-indexer.en-us.md +++ b/docs/content/doc/advanced/repo-indexer.en-us.md @@ -3,7 +3,7 @@ date: "2019-09-06T01:35:00-03:00" title: "Repository indexer" slug: "repo-indexer" weight: 45 -toc: true +toc: false draft: false menu: sidebar: @@ -15,11 +15,15 @@ menu: # Repository indexer +**Table of Contents** + +{{< toc >}} + ## Setting up the repository indexer Gitea can search through the files of the repositories by enabling this function in your [`app.ini`](https://docs.gitea.io/en-us/config-cheat-sheet/): -``` +```ini [indexer] ; ... REPO_INDEXER_ENABLED = true @@ -49,10 +53,10 @@ Limiting the list of files prevents the indexes from becoming polluted with deri Pattern matching works as follows: -* To match all files with a `.txt` extension no matter what directory, use `**.txt`. -* To match all files with a `.txt` extension _only at the root level of the repository_, use `*.txt`. -* To match all files inside `resources/bin` and below, use `resources/bin/**`. -* To match all files _immediately inside_ `resources/bin`, use `resources/bin/*`. -* To match all files named `Makefile`, use `**Makefile`. -* Matching a directory has no effect; the pattern `resources/bin` will not include/exclude files inside that directory; `resources/bin/**` will. -* All files and patterns are normalized to lower case, so `**Makefile`, `**makefile` and `**MAKEFILE` are equivalent. +- To match all files with a `.txt` extension no matter what directory, use `**.txt`. +- To match all files with a `.txt` extension _only at the root level of the repository_, use `*.txt`. +- To match all files inside `resources/bin` and below, use `resources/bin/**`. +- To match all files _immediately inside_ `resources/bin`, use `resources/bin/*`. +- To match all files named `Makefile`, use `**Makefile`. +- Matching a directory has no effect; the pattern `resources/bin` will not include/exclude files inside that directory; `resources/bin/**` will. +- All files and patterns are normalized to lower case, so `**Makefile`, `**makefile` and `**MAKEFILE` are equivalent. diff --git a/docs/content/doc/advanced/search-engines-indexation.en-us.md b/docs/content/doc/advanced/search-engines-indexation.en-us.md index f6dc498e1..5d5e4dab5 100644 --- a/docs/content/doc/advanced/search-engines-indexation.en-us.md +++ b/docs/content/doc/advanced/search-engines-indexation.en-us.md @@ -3,7 +3,7 @@ date: "2019-12-31T13:55:00+05:00" title: "Advanced: Search Engines Indexation" slug: "search-engines-indexation" weight: 30 -toc: true +toc: false draft: false menu: sidebar: diff --git a/docs/content/doc/advanced/signing.en-us.md b/docs/content/doc/advanced/signing.en-us.md index 1de67f234..926f6b1f4 100644 --- a/docs/content/doc/advanced/signing.en-us.md +++ b/docs/content/doc/advanced/signing.en-us.md @@ -15,6 +15,10 @@ menu: # GPG Commit Signatures +**Table of Contents** + +{{< toc >}} + Gitea will verify GPG commit signatures in the provided tree by checking if the commits are signed by a key within the gitea database, or if the commit matches the default key for git. @@ -36,10 +40,10 @@ this requires git >= 2.0.0. There are a number of places where Gitea will generate commits itself: -* Repository Initialisation -* Wiki Changes -* CRUD actions using the editor or the API -* Merges from Pull Requests +- Repository Initialisation +- Wiki Changes +- CRUD actions using the editor or the API +- Merges from Pull Requests Depending on configuration and server trust you may want Gitea to sign these commits. @@ -78,12 +82,12 @@ MERGES = pubkey, twofa, basesigned, commitssigned The first option to discuss is the `SIGNING_KEY`. There are three main options: -* `none` - this prevents Gitea from signing any commits -* `default` - Gitea will default to the key configured within -`git config` -* `KEYID` - Gitea will sign commits with the gpg key with the ID -`KEYID`. In this case you should provide a `SIGNING_NAME` and -`SIGNING_EMAIL` to be displayed for this key. +- `none` - this prevents Gitea from signing any commits +- `default` - Gitea will default to the key configured within + `git config` +- `KEYID` - Gitea will sign commits with the gpg key with the ID + `KEYID`. In this case you should provide a `SIGNING_NAME` and + `SIGNING_EMAIL` to be displayed for this key. The `default` option will interrogate `git config` for `commit.gpgsign` option - if this is set, then it will use the results @@ -99,10 +103,10 @@ ideal UI and therefore subject to change. This option determines whether Gitea should sign the initial commit when creating a repository. The possible values are: -* `never`: Never sign -* `pubkey`: Only sign if the user has a public key -* `twofa`: Only sign if the user logs in with two factor authentication -* `always`: Always sign +- `never`: Never sign +- `pubkey`: Only sign if the user has a public key +- `twofa`: Only sign if the user logs in with two factor authentication +- `always`: Always sign Options other than `never` and `always` can be combined as a comma separated list. @@ -112,11 +116,11 @@ separated list. This options determines if Gitea should sign commits to the Wiki. The possible values are: -* `never`: Never sign -* `pubkey`: Only sign if the user has a public key -* `twofa`: Only sign if the user logs in with two factor authentication -* `parentsigned`: Only sign if the parent commit is signed. -* `always`: Always sign +- `never`: Never sign +- `pubkey`: Only sign if the user has a public key +- `twofa`: Only sign if the user logs in with two factor authentication +- `parentsigned`: Only sign if the parent commit is signed. +- `always`: Always sign Options other than `never` and `always` can be combined as a comma separated list. @@ -126,11 +130,11 @@ separated list. This option determines if Gitea should sign commits from the web editor or API CRUD actions. The possible values are: -* `never`: Never sign -* `pubkey`: Only sign if the user has a public key -* `twofa`: Only sign if the user logs in with two factor authentication -* `parentsigned`: Only sign if the parent commit is signed. -* `always`: Always sign +- `never`: Never sign +- `pubkey`: Only sign if the user has a public key +- `twofa`: Only sign if the user logs in with two factor authentication +- `parentsigned`: Only sign if the parent commit is signed. +- `always`: Always sign Options other than `never` and `always` can be combined as a comma separated list. @@ -140,14 +144,14 @@ separated list. This option determines if Gitea should sign merge commits from PRs. The possible options are: -* `never`: Never sign -* `pubkey`: Only sign if the user has a public key -* `twofa`: Only sign if the user logs in with two factor authentication -* `basesigned`: Only sign if the parent commit in the base repo is signed. -* `headsigned`: Only sign if the head commit in the head branch is signed. -* `commitssigned`: Only sign if all the commits in the head branch to the merge point are signed. -* `approved`: Only sign approved merges to a protected branch. -* `always`: Always sign +- `never`: Never sign +- `pubkey`: Only sign if the user has a public key +- `twofa`: Only sign if the user logs in with two factor authentication +- `basesigned`: Only sign if the parent commit in the base repo is signed. +- `headsigned`: Only sign if the head commit in the head branch is signed. +- `commitssigned`: Only sign if all the commits in the head branch to the merge point are signed. +- `approved`: Only sign approved merges to a protected branch. +- `always`: Always sign Options other than `never` and `always` can be combined as a comma separated list. @@ -156,12 +160,12 @@ separated list. The public key used to sign Gitea's commits can be obtained from the API at: -``` +```sh /api/v1/signing-key.gpg ``` In cases where there is a repository specific key this can be obtained from: -``` +```sh /api/v1/repos/:username/:reponame/signing-key.gpg ``` diff --git a/docs/content/doc/advanced/third-party-tools.zh-cn.md b/docs/content/doc/advanced/third-party-tools.zh-cn.md index be7b17c76..d25bc400e 100644 --- a/docs/content/doc/advanced/third-party-tools.zh-cn.md +++ b/docs/content/doc/advanced/third-party-tools.zh-cn.md @@ -3,7 +3,7 @@ date: "2019-03-11T21:45:00+00:00" title: "高级: 第三方工具" slug: "third-party-tools" weight: 50 -toc: true +toc: false draft: false menu: sidebar: diff --git a/docs/content/doc/developers/api-usage.en-us.md b/docs/content/doc/developers/api-usage.en-us.md index 7dc6406a2..5253cbaa1 100644 --- a/docs/content/doc/developers/api-usage.en-us.md +++ b/docs/content/doc/developers/api-usage.en-us.md @@ -3,7 +3,7 @@ date: "2018-06-24:00:00+02:00" title: "API Usage" slug: "api-usage" weight: 40 -toc: true +toc: false draft: false menu: sidebar: @@ -15,12 +15,14 @@ menu: # API Usage +**Table of Contents** + {{< toc >}} ## Enabling/configuring API access By default, `ENABLE_SWAGGER` is true, and -`MAX_RESPONSE_ITEMS` is set to 50. See [Config Cheat +`MAX_RESPONSE_ITEMS` is set to 50. See [Config Cheat Sheet](https://docs.gitea.io/en-us/config-cheat-sheet/) for more information. @@ -33,7 +35,7 @@ Gitea supports these methods of API authentication: - `access_token=...` parameter in URL query string - `Authorization: token ...` header in HTTP headers -All of these methods accept the same API key token type. You can +All of these methods accept the same API key token type. You can better understand this by looking at the code -- as of this writing, Gitea parses queries and headers to find the token in [modules/auth/auth.go](https://github.com/go-gitea/gitea/blob/6efdcaed86565c91a3dc77631372a9cc45a58e89/modules/auth/auth.go#L47). @@ -54,13 +56,13 @@ Access tokens obtained from Gitea's [OAuth2 provider](https://docs.gitea.io/en-u For historical reasons, Gitea needs the word `token` included before the API key token in an authorization header, like this: -``` +```sh Authorization: token 65eaa9c8ef52460d22a93307fe0aee76289dc675 ``` In a `curl` command, for instance, this would look like: -``` +```sh curl -X POST "http://localhost:4000/api/v1/repos/test1/test1/issues" \ -H "accept: application/json" \ -H "Authorization: token 65eaa9c8ef52460d22a93307fe0aee76289dc675" \ @@ -73,10 +75,9 @@ the `token=` string in a GET request. ## API Guide: API Reference guide is auto-generated by swagger and available on: - `https://gitea.your.host/api/swagger` - or on - [gitea demo instance](https://try.gitea.io/api/swagger) - +`https://gitea.your.host/api/swagger` +or on +[gitea demo instance](https://try.gitea.io/api/swagger) ## Listing your issued tokens via the API @@ -87,14 +88,14 @@ using BasicAuth, as follows: ### Using basic authentication: -``` +```sh $ curl --request GET --url https://yourusername:yourpassword@gitea.your.host/api/v1/users/yourusername/tokens [{"name":"test","sha1":"..."},{"name":"dev","sha1":"..."}] ``` As of v1.8.0 of Gitea, if using basic authentication with the API and your user has two factor authentication enabled, you'll need to send an additional header that contains the one time password (6 digit rotating token). An example of the header is `X-Gitea-OTP: 123456` where `123456` is where you'd place the code from your authenticator. Here is how the request would look like in curl: -``` +```sh $ curl -H "X-Gitea-OTP: 123456" --request GET --url https://yourusername:yourpassword@gitea.your.host/api/v1/users/yourusername/tokens ``` @@ -104,5 +105,5 @@ The API allows admin users to sudo API requests as another user. Simply add eith ## SDKs -* [Official go-sdk](https://gitea.com/gitea/go-sdk) -* [more](https://gitea.com/gitea/awesome-gitea#user-content-sdk) +- [Official go-sdk](https://gitea.com/gitea/go-sdk) +- [more](https://gitea.com/gitea/awesome-gitea#user-content-sdk) diff --git a/docs/content/doc/developers/api-usage.zh-cn.md b/docs/content/doc/developers/api-usage.zh-cn.md index cfea23176..17a1cf110 100644 --- a/docs/content/doc/developers/api-usage.zh-cn.md +++ b/docs/content/doc/developers/api-usage.zh-cn.md @@ -3,7 +3,7 @@ date: "2018-06-24:00:00+02:00" title: "API 使用指南" slug: "api-usage" weight: 40 -toc: true +toc: false draft: false menu: sidebar: diff --git a/docs/content/doc/developers/hacking-on-gitea.en-us.md b/docs/content/doc/developers/hacking-on-gitea.en-us.md index 2c331faf6..875a4818e 100644 --- a/docs/content/doc/developers/hacking-on-gitea.en-us.md +++ b/docs/content/doc/developers/hacking-on-gitea.en-us.md @@ -15,6 +15,8 @@ menu: # Hacking on Gitea +**Table of Contents** + {{< toc >}} ## Installing go @@ -127,9 +129,9 @@ See `make help` for all available `make` targets. Also see [`.drone.yml`](https: To run and continously rebuild when source files change: -````bash +```bash make watch -```` +``` On macOS, watching all backend source files may hit the default open files limit which can be increased via `ulimit -n 12288` for the current shell or in your shell startup file for all future shells. @@ -268,7 +270,7 @@ TAGS="bindata sqlite sqlite_unlock_notify" make build test-sqlite ``` will run the integration tests in an sqlite environment. Integration tests -require `git lfs` to be installed. Other database tests are available but +require `git lfs` to be installed. Other database tests are available but may need adjustment to the local environment. Look at diff --git a/docs/content/doc/developers/integrations.en-us.md b/docs/content/doc/developers/integrations.en-us.md index 3c38d16d4..a1d8f0f93 100644 --- a/docs/content/doc/developers/integrations.en-us.md +++ b/docs/content/doc/developers/integrations.en-us.md @@ -3,7 +3,7 @@ date: "2019-04-15T17:29:00+08:00" title: "Integrations" slug: "integrations" weight: 40 -toc: true +toc: false draft: false menu: sidebar: diff --git a/docs/content/doc/developers/migrations.en-us.md b/docs/content/doc/developers/migrations.en-us.md index 7af013896..6e1a7e019 100644 --- a/docs/content/doc/developers/migrations.en-us.md +++ b/docs/content/doc/developers/migrations.en-us.md @@ -3,7 +3,7 @@ date: "2019-04-15T17:29:00+08:00" title: "Migrations Interfaces" slug: "migrations-interfaces" weight: 30 -toc: true +toc: false draft: false menu: sidebar: diff --git a/docs/content/doc/developers/oauth2-provider.md b/docs/content/doc/developers/oauth2-provider.md index 81c77e680..ad2ff78e6 100644 --- a/docs/content/doc/developers/oauth2-provider.md +++ b/docs/content/doc/developers/oauth2-provider.md @@ -3,7 +3,7 @@ date: "2019-04-19:44:00+01:00" title: "OAuth2 provider" slug: "oauth2-provider" weight: 41 -toc: true +toc: false draft: false menu: sidebar: @@ -13,25 +13,25 @@ menu: identifier: "oauth2-provider" --- - # OAuth2 provider -Gitea supports acting as an OAuth2 provider to allow third party applications to access its resources with the user's consent. This feature is available since release 1.8.0. +**Table of Contents** -## Endpoints +{{< toc >}} +Gitea supports acting as an OAuth2 provider to allow third party applications to access its resources with the user's consent. This feature is available since release 1.8.0. -Endpoint | URL ------------------------|---------------------------- -Authorization Endpoint | `/login/oauth/authorize` -Access Token Endpoint | `/login/oauth/access_token` +## Endpoints +| Endpoint | URL | +| ---------------------- | --------------------------- | +| Authorization Endpoint | `/login/oauth/authorize` | +| Access Token Endpoint | `/login/oauth/access_token` | ## Supported OAuth2 Grants At the moment Gitea only supports the [**Authorization Code Grant**](https://tools.ietf.org/html/rfc6749#section-1.3.1) standard with additional support of the [Proof Key for Code Exchange (PKCE)](https://tools.ietf.org/html/rfc7636) extension. - To use the Authorization Code Grant as a third party application it is required to register a new application via the "Settings" (`/user/settings/applications`) section of the settings. ## Scopes @@ -44,49 +44,49 @@ Currently Gitea does not support scopes (see [#4300](https://github.com/go-gitea 1. Redirect to user to the authorization endpoint in order to get his/her consent for accessing the resources: -```curl -https://[YOUR-GITEA-URL]/login/oauth/authorize?client_id=CLIENT_ID&redirect_uri=REDIRECT_URI& response_type=code&state=STATE -``` + ```curl + https://[YOUR-GITEA-URL]/login/oauth/authorize?client_id=CLIENT_ID&redirect_uri=REDIRECT_URI& response_type=code&state=STATE + ``` -The `CLIENT_ID` can be obtained by registering an application in the settings. The `STATE` is a random string that will be send back to your application after the user authorizes. The `state` parameter is optional but should be used to prevent CSRF attacks. + The `CLIENT_ID` can be obtained by registering an application in the settings. The `STATE` is a random string that will be send back to your application after the user authorizes. The `state` parameter is optional but should be used to prevent CSRF attacks. + ![Authorization Page](/authorize.png) -![Authorization Page](/authorize.png) + The user will now be asked to authorize your application. If they authorize it, the user will be redirected to the `REDIRECT_URL`, for example: -The user will now be asked to authorize your application. If they authorize it, the user will be redirected to the `REDIRECT_URL`, for example: + ```curl + https://[REDIRECT_URI]?code=RETURNED_CODE&state=STATE + ``` -```curl -https://[REDIRECT_URI]?code=RETURNED_CODE&state=STATE -``` +2. Using the provided `code` from the redirect, you can request a new application and refresh token. The access token endpoints accepts POST requests with `application/json` and `application/x-www-form-urlencoded` body, for example: -2. Using the provided `code` from the redirect, you can request a new application and refresh token. The access token endpoints accepts POST requests with `application/json` and `application/x-www-form-urlencoded` body, for example: + ```curl + POST https://[YOUR-GITEA-URL]/login/oauth/access_token + ``` -```curl -POST https://[YOUR-GITEA-URL]/login/oauth/access_token -``` + ```json + { + "client_id": "YOUR_CLIENT_ID", + "client_secret": "YOUR_CLIENT_SECRET", + "code": "RETURNED_CODE", + "grant_type": "authorization_code", + "redirect_uri": "REDIRECT_URI" + } + ``` -```json -{ - "client_id": "YOUR_CLIENT_ID", - "client_secret": "YOUR_CLIENT_SECRET", - "code": "RETURNED_CODE", - "grant_type": "authorization_code", - "redirect_uri": "REDIRECT_URI" -} -``` + Response: -Response: -```json -{ -"access_token":"eyJhbGciOiJIUzUxMiIsInR5cCI6IkpXVCJ9.eyJnbnQiOjIsInR0IjowLCJleHAiOjE1NTUxNzk5MTIsImlhdCI6MTU1NTE3NjMxMn0.0-iFsAwBtxuckA0sNZ6QpBQmywVPz129u75vOM7wPJecw5wqGyBkmstfJHAjEOqrAf_V5Z-1QYeCh_Cz4RiKug", -"token_type":"bearer", -"expires_in":3600, -"refresh_token":"eyJhbGciOiJIUzUxMiIsInR5cCI6IkpXVCJ9.eyJnbnQiOjIsInR0IjoxLCJjbnQiOjEsImV4cCI6MTU1NzgwNDMxMiwiaWF0IjoxNTU1MTc2MzEyfQ.S_HZQBy4q9r5SEzNGNIoFClT43HPNDbUdHH-GYNYYdkRfft6XptJBkUQscZsGxOW975Yk6RbgtGvq1nkEcklOw" -} -``` + ```json + { + "access_token": "eyJhbGciOiJIUzUxMiIsInR5cCI6IkpXVCJ9.eyJnbnQiOjIsInR0IjowLCJleHAiOjE1NTUxNzk5MTIsImlhdCI6MTU1NTE3NjMxMn0.0-iFsAwBtxuckA0sNZ6QpBQmywVPz129u75vOM7wPJecw5wqGyBkmstfJHAjEOqrAf_V5Z-1QYeCh_Cz4RiKug", + "token_type": "bearer", + "expires_in": 3600, + "refresh_token": "eyJhbGciOiJIUzUxMiIsInR5cCI6IkpXVCJ9.eyJnbnQiOjIsInR0IjoxLCJjbnQiOjEsImV4cCI6MTU1NzgwNDMxMiwiaWF0IjoxNTU1MTc2MzEyfQ.S_HZQBy4q9r5SEzNGNIoFClT43HPNDbUdHH-GYNYYdkRfft6XptJBkUQscZsGxOW975Yk6RbgtGvq1nkEcklOw" + } + ``` -The `CLIENT_SECRET` is the unique secret code generated for this application. Please note that the secret will only be visible after you created/registered the application with Gitea and cannot be recovered. If you lose the secret you must regenerate the secret via the application's settings. + The `CLIENT_SECRET` is the unique secret code generated for this application. Please note that the secret will only be visible after you created/registered the application with Gitea and cannot be recovered. If you lose the secret you must regenerate the secret via the application's settings. -The `REDIRECT_URI` in the `access_token` request must match the `REDIRECT_URI` in the `authorize` request. + The `REDIRECT_URI` in the `access_token` request must match the `REDIRECT_URI` in the `authorize` request. -3. Use the `access_token` to make [API requests](https://docs.gitea.io/en-us/api-usage#oauth2) to access the user's resources. +3. Use the `access_token` to make [API requests](https://docs.gitea.io/en-us/api-usage#oauth2) to access the user's resources. diff --git a/docs/content/doc/features/authentication.en-us.md b/docs/content/doc/features/authentication.en-us.md index d91aa68c2..0c83fa4d2 100644 --- a/docs/content/doc/features/authentication.en-us.md +++ b/docs/content/doc/features/authentication.en-us.md @@ -3,7 +3,7 @@ date: "2016-12-01T16:00:00+02:00" title: "Authentication" slug: "authentication" weight: 10 -toc: true +toc: false draft: false menu: sidebar: @@ -22,20 +22,25 @@ menu: Both the LDAP via BindDN and the simple auth LDAP share the following fields: - Authorization Name **(required)** + - A name to assign to the new method of authorization. - Host **(required)** + - The address where the LDAP server can be reached. - Example: `mydomain.com` - Port **(required)** + - The port to use when connecting to the server. - Example: `389` for LDAP or `636` for LDAP SSL - Enable TLS Encryption (optional) + - Whether to use TLS when connecting to the LDAP server. - Admin Filter (optional) + - An LDAP filter specifying if a user should be given administrator privileges. If a user account passes the filter, the user will be privileged as an administrator. @@ -43,6 +48,7 @@ Both the LDAP via BindDN and the simple auth LDAP share the following fields: - Example for Microsoft Active Directory (AD): `(memberOf=CN=admin-group,OU=example,DC=example,DC=org)` - Username attribute (optional) + - The attribute of the user's LDAP record containing the user name. Given attribute value will be used for new Gitea account user name after first successful sign-in. Leave empty to use login name given on sign-in form. @@ -53,11 +59,13 @@ Both the LDAP via BindDN and the simple auth LDAP share the following fields: - Example for Microsoft Active Directory (AD): `sAMAccountName` - First name attribute (optional) + - The attribute of the user's LDAP record containing the user's first name. This will be used to populate their account information. - Example: `givenName` - Surname attribute (optional) + - The attribute of the user's LDAP record containing the user's surname. This will be used to populate their account information. - Example: `sn` @@ -67,19 +75,24 @@ Both the LDAP via BindDN and the simple auth LDAP share the following fields: address. This will be used to populate their account information. - Example: `mail` -**LDAP via BindDN** adds the following fields: +### LDAP via BindDN + +Adds the following fields: - Bind DN (optional) + - The DN to bind to the LDAP server with when searching for the user. This may be left blank to perform an anonymous search. - Example: `cn=Search,dc=mydomain,dc=com` - Bind Password (optional) + - The password for the Bind DN specified above, if any. _Note: The password is stored in plaintext at the server. As such, ensure that the Bind DN has as few privileges as possible._ - User Search Base **(required)** + - The LDAP base at which user accounts will be searched for. - Example: `ou=Users,dc=mydomain,dc=com` @@ -96,24 +109,28 @@ Both the LDAP via BindDN and the simple auth LDAP share the following fields: - Enable user synchronization - This option enables a periodic task that synchronizes the Gitea users with the LDAP server. The default period is every 24 hours but that can be - changed in the app.ini file. See the *cron.sync_external_users* section in + changed in the app.ini file. See the _cron.sync_external_users_ section in the [sample app.ini](https://github.com/go-gitea/gitea/blob/master/custom/conf/app.example.ini) - for detailed comments about that section. The *User Search Base* and *User - Filter* settings described above will limit which users can use Gitea and - which users will be synchronized. When initially run the task will create + for detailed comments about that section. The _User Search Base_ and _User + Filter_ settings described above will limit which users can use Gitea and + which users will be synchronized. When initially run the task will create all LDAP users that match the given settings so take care if working with large Enterprise LDAP directories. -**LDAP using simple auth** adds the following fields: +### LDAP using simple auth + +Adds the following fields: - User DN **(required)** + - A template to use as the user's DN. The `%s` matching parameter will be substituted with login name given on sign-in form. - Example: `cn=%s,ou=Users,dc=mydomain,dc=com` - Example: `uid=%s,ou=Users,dc=mydomain,dc=com` -- User Search Base (optional) +- User Search Base (optional) + - The LDAP base at which user accounts will be searched for. - Example: `ou=Users,dc=mydomain,dc=com` @@ -124,23 +141,28 @@ Both the LDAP via BindDN and the simple auth LDAP share the following fields: - Example: `(&(objectClass=posixAccount)(cn=%s))` - Example: `(&(objectClass=posixAccount)(uid=%s))` -**Verify group membership in LDAP** uses the following fields: +### Verify group membership in LDAP + +Uses the following fields: + +- Group Search Base (optional) + + - The LDAP DN used for groups. + - Example: `ou=group,dc=mydomain,dc=com` + +- Group Name Filter (optional) -* Group Search Base (optional) - * The LDAP DN used for groups. - * Example: `ou=group,dc=mydomain,dc=com` + - An LDAP filter declaring how to find valid groups in the above DN. + - Example: `(|(cn=gitea_users)(cn=admins))` -* Group Name Filter (optional) - * An LDAP filter declaring how to find valid groups in the above DN. - * Example: `(|(cn=gitea_users)(cn=admins))` +- User Attribute in Group (optional) -* User Attribute in Group (optional) - * Which user LDAP attribute is listed in the group. - * Example: `uid` + - Which user LDAP attribute is listed in the group. + - Example: `uid` -* Group Attribute for User (optional) - * Which group LDAP attribute contains an array above user attribute names. - * Example: `memberUid` +- Group Attribute for User (optional) + - Which group LDAP attribute contains an array above user attribute names. + - Example: `memberUid` ## PAM (Pluggable Authentication Module) @@ -154,28 +176,35 @@ This option allows Gitea to log in to an SMTP host as a Gitea user. To configure this, set the fields below: - Authentication Name **(required)** + - A name to assign to the new method of authorization. - SMTP Authentication Type **(required)** + - Type of authentication to use to connect to SMTP host, PLAIN or LOGIN. - Host **(required)** + - The address where the SMTP host can be reached. - Example: `smtp.mydomain.com` - Port **(required)** + - The port to use when connecting to the server. - Example: `587` - Allowed Domains + - Restrict what domains can log in if using a public SMTP host or SMTP host with multiple domains. - Example: `gitea.io,mydomain.com,mydomain2.com` - Enable TLS Encryption + - Enable TLS encryption on authentication. - Skip TLS Verify + - Disable TLS verify on authentication. - This authentication is activate @@ -188,7 +217,8 @@ configure this, set the fields below: - On the FreeIPA server, create a `gitea.ldif` file, replacing `dc=example,dc=com` with your DN, and provide an appropriately secure password: -``` + + ```sh dn: uid=gitea,cn=sysaccounts,cn=etc,dc=example,dc=com changetype: add objectclass: account @@ -197,18 +227,22 @@ configure this, set the fields below: userPassword: secure password passwordExpirationTime: 20380119031407Z nsIdleTimeout: 0 -``` + ``` - Import the LDIF (change localhost to an IPA server if needed). A prompt for - Directory Manager password will be presented: -``` + Directory Manager password will be presented: + + ```sh ldapmodify -h localhost -p 389 -x -D \ "cn=Directory Manager" -W -f gitea.ldif -``` -- Add an IPA group for gitea\_users : -``` + ``` + +- Add an IPA group for gitea_users : + + ```sh ipa group-add --desc="Gitea Users" gitea_users -``` + ``` + - Note: For errors about IPA credentials, run `kinit admin` and provide the domain admin account password. @@ -224,13 +258,15 @@ Before activating SSPI single sign-on authentication (SSO) you have to prepare y - Create a separate user account in active directory, under which the `gitea.exe` process will be running (eg. `user` under domain `domain.local`): - Create a service principal name for the host where `gitea.exe` is running with class `HTTP`: + - Start `Command Prompt` or `PowerShell` as a priviledged domain user (eg. Domain Administrator) - Run the command below, replacing `host.domain.local` with the fully qualified domain name (FQDN) of the server where the web application will be running, and `domain\user` with the name of the account created in the previous step: - ``` - setspn -A HTTP/host.domain.local domain\user + + ```sh + setspn -A HTTP/host.domain.local domain\user ``` -- Sign in (*sign out if you were already signed in*) with the user created +- Sign in (_sign out if you were already signed in_) with the user created - Make sure that `ROOT_URL` in the `[server]` section of `custom/conf/app.ini` is the fully qualified domain name of the server where the web application will be running - the same you used when creating the service principal name (eg. `host.domain.local`) diff --git a/docs/content/doc/features/authentication.zh-cn.md b/docs/content/doc/features/authentication.zh-cn.md index 4ed913320..481e33441 100644 --- a/docs/content/doc/features/authentication.zh-cn.md +++ b/docs/content/doc/features/authentication.zh-cn.md @@ -3,7 +3,7 @@ date: "2016-12-01T16:00:00+02:00" title: "认证" slug: "authentication" weight: 10 -toc: true +toc: false draft: false menu: sidebar: diff --git a/docs/content/doc/features/authentication.zh-tw.md b/docs/content/doc/features/authentication.zh-tw.md index 4dd024897..da257409a 100644 --- a/docs/content/doc/features/authentication.zh-tw.md +++ b/docs/content/doc/features/authentication.zh-tw.md @@ -3,7 +3,7 @@ date: "2016-12-01T16:00:00+02:00" title: "認證" slug: "authentication" weight: 10 -toc: true +toc: false draft: false menu: sidebar: diff --git a/docs/content/doc/features/comparison.en-us.md b/docs/content/doc/features/comparison.en-us.md index 77299404c..0bd06da24 100644 --- a/docs/content/doc/features/comparison.en-us.md +++ b/docs/content/doc/features/comparison.en-us.md @@ -3,7 +3,7 @@ date: "2018-05-07T13:00:00+02:00" title: "Gitea compared to other Git hosting options" slug: "comparison" weight: 5 -toc: true +toc: false draft: false menu: sidebar: @@ -15,114 +15,117 @@ menu: # Gitea compared to other Git hosting options +**Table of Contents** + +{{< toc >}} + To help decide if Gitea is suited for your needs, here is how it compares to other Git self hosted options. Be warned that we don't regularly check for feature changes in other products, so this list may be outdated. If you find anything that needs to be updated in the table below, please report it in an [issue on GitHub](https://github.com/go-gitea/gitea/issues). _Symbols used in table:_ -* _✓ - supported_ - -* _⁄ - supported with limited functionality_ - -* _✘ - unsupported_ - -#### General Features - -| Feature | Gitea | Gogs | GitHub EE | GitLab CE | GitLab EE | BitBucket | RhodeCode CE | -|---------|-------|------|-----------|-----------|-----------|-----------|--------------| -| Open source and free | ✓ | ✓ | ✘| ✓ | ✘ | ✘ | ✓ | -| Low resource usage (RAM/CPU) | ✓ | ✓ | ✘ | ✘ | ✘ | ✘ | ✘ | -| Multiple database support | ✓ | ✓ | ✘ | ⁄ | ⁄ | ✓ | ✓ | -| Multiple OS support | ✓ | ✓ | ✘ | ✘ | ✘ | ✘ | ✓ | -| Easy upgrade process | ✓ | ✓ | ✘ | ✓ | ✓ | ✘ | ✓ | -| Markdown support | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | -| Orgmode support | ✓ | ✘ | ✓ | ✘ | ✘ | ✘ | ? | -| CSV support | ✓ | ✘ | ✓ | ✘ | ✘ | ✓ | ? | -| Third-party render tool support | ✓ | ✘ | ✘ | ✘ | ✘ | ✓ | ? | -| Static Git-powered pages | [✘](https://github.com/go-gitea/gitea/issues/302) | ✘ | ✓ | ✓ | ✓ | ✘ | ✘ | -| Integrated Git-powered wiki | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✘ | -| Deploy Tokens | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | -| Repository Tokens with write rights | ✓ | ✘ | ✓ | ✓ | ✓ | ✘ | ✓ | -| Built-in Container Registry | [✘](https://github.com/go-gitea/gitea/issues/2316) | ✘ | ✘ | ✓ | ✓ | ✘ | ✘ | -| External git mirroring | ✓ | ✓ | ✘ | ✘ | ✓ | ✓ | ✓ | -| FIDO U2F (2FA) | ✓ | ✘ | ✓ | ✓ | ✓ | ✓ | ✘ | -| Built-in CI/CD | ✘ | ✘ | ✓ | ✓ | ✓ | ✘ | ✘ | -| Subgroups: groups within groups | ✘ | ✘ | ✘ | ✓ | ✓ | ✘ | ✓ | - -#### Code management - -| Feature | Gitea | Gogs | GitHub EE | GitLab CE | GitLab EE | BitBucket | RhodeCode CE | -|---------|-------|------|-----------|-----------|-----------|-----------|--------------| -| Repository topics | ✓ | ✘ | ✓ | ✓ | ✓ | ✘ | ✘ | -| Repository code search | ✓ | ✘ | ✓ | ✓ | ✓ | ✓ | ✓ | -| Global code search | ✓ | ✘ | ✓ | ✘ | ✓ | ✓ | ✓ | -| Git LFS 2.0 | ✓ | ✘ | ✓ | ✓ | ✓ | ⁄ | ✓ | -| Group Milestones | ✘ | ✘ | ✘ | ✓ | ✓ | ✘ | ✘ | -| Granular user roles (Code, Issues, Wiki etc) | ✓ | ✘ | ✘ | ✓ | ✓ | ✘ | ✘ | -| Verified Committer | ⁄ | ✘ | ? | ✓ | ✓ | ✓ | ✘ | -| GPG Signed Commits | ✓ | ✘ | ✓ | ✓ | ✓ | ✓ | ✓ | -| Reject unsigned commits | [✓](https://github.com/go-gitea/gitea/pull/9708) | ✘ | ✓ | ✓ | ✓ | ✘ | ✓ | -| Repository Activity page | ✓ | ✘ | ✓ | ✓ | ✓ | ✓ | ✓ | -| Branch manager | ✓ | ✘ | ✓ | ✓ | ✓ | ✓ | ✓ | -| Create new branches | ✓ | ✘ | ✓ | ✓ | ✓ | ✘ | ✘ | -| Web code editor | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | -| Commit graph | ✓ | ✘ | ✓ | ✓ | ✓ | ✓ | ✓ | -| Template Repositories | [✓](https://github.com/go-gitea/gitea/pull/8768) | ✘ | ✓ | ✘ | ✓ | ✓ | ✘ | - -#### Issue Tracker - -| Feature | Gitea | Gogs | GitHub EE | GitLab CE | GitLab EE | BitBucket | RhodeCode CE | -|---------|-------|------|-----------|-----------|-----------|-----------|--------------| -| Issue tracker | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✘ | -| Issue templates | ✓ | ✓ | ✓ | ✓ | ✓ | ✘ | ✘ | -| Labels | ✓ | ✓ | ✓ | ✓ | ✓ | ✘ | ✘ | -| Time tracking | ✓ | ✘ | ✓ | ✓ | ✓ | ✘ | ✘ | -| Multiple assignees for issues | ✓ | ✘ | ✓ | ✘ | ✓ | ✘ | ✘ | -| Related issues | ✘ | ✘ | ⁄ | [✓](https://docs.gitlab.com/ce/user/project/issues/related_issues.html) | ✓ | ✘ | ✘ | -| Confidential issues | [✘](https://github.com/go-gitea/gitea/issues/3217) | ✘ | ✘ | ✓ | ✓ | ✘ | ✘ | -| Comment reactions | ✓ | ✘ | ✓ | ✓ | ✓ | ✘ | ✘ | -| Lock Discussion | ✓ | ✘ | ✓ | ✓ | ✓ | ✘ | ✘ | -| Batch issue handling | ✓ | ✘ | ✓ | ✓ | ✓ | ✘ | ✘ | -| Issue Boards (Kanban) | [✓](https://github.com/go-gitea/gitea/pull/8346) | ✘ | ✘ | ✓ | ✓ | ✘ | ✘ | -| Create new branches from issues | ✘ | ✘ | ✘ | ✓ | ✓ | ✘ | ✘ | -| Issue search | ✓ | ✘ | ✓ | ✓ | ✓ | ✓ | ✘ | -| Global issue search | [✘](https://github.com/go-gitea/gitea/issues/2434) | ✘ | ✓ | ✓ | ✓ | ✓ | ✘ | -| Issue dependency | ✓ | ✘ | ✘ | ✘ | ✘ | ✘ | ✘ | -| Create issue via email | [✘](https://github.com/go-gitea/gitea/issues/6226) | [✘](https://github.com/gogs/gogs/issues/2602) | ✘ | ✘ | ✓ | ✓ | ✘ | -| Service Desk | [✘](https://github.com/go-gitea/gitea/issues/6219) | ✘ | ✘ | [✓](https://gitlab.com/groups/gitlab-org/-/epics/3103) | ✓ | ✘ | ✘ | - -#### Pull/Merge requests - -| Feature | Gitea | Gogs | GitHub EE | GitLab CE | GitLab EE | BitBucket | RhodeCode CE | -|---------|-------|------|-----------|-----------|-----------|-----------|--------------| -| Pull/Merge requests | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | -| Squash merging | ✓ | ✘ | ✓ | [✓](https://docs.gitlab.com/ce/user/project/merge_requests/squash_and_merge.html) | ✓ | ✓ | ✓ | -| Rebase merging | ✓ | ✓ | ✓ | ✘ | ⁄ | ✘ | ✓ | -| Pull/Merge request inline comments | ✓ | ✘ | ✓ | ✓ | ✓ | ✓ | ✓ | -| Pull/Merge request approval | ✓ | ✘ | ⁄ | ✓ | ✓ | ✓ | ✓ | -| Merge conflict resolution | [✘](https://github.com/go-gitea/gitea/issues/5158) | ✘ | ✓ | ✓ | ✓ | ✓ | ✘ | -| Restrict push and merge access to certain users | ✓ | ✘ | ✓ | ⁄ | ✓ | ✓ | ✓ | -| Revert specific commits or a merge request | [✘](https://github.com/go-gitea/gitea/issues/5158) | ✘ | ✓ | ✓ | ✓ | ✓ | ✘ | -| Pull/Merge requests templates | ✓ | ✓ | ✓ | ✓ | ✓ | ✘ | ✘ | -| Cherry-picking changes | [✘](https://github.com/go-gitea/gitea/issues/5158) | ✘ | ✘ | ✓ | ✓ | ✘ | ✘ | -| Download Patch | ✓ | ✘ | ✓ | ✓ | ✓ | [/](https://jira.atlassian.com/plugins/servlet/mobile#issue/BCLOUD-8323) | ✘ | - - -#### 3rd-party integrations - -| Feature | Gitea | Gogs | GitHub EE | GitLab CE | GitLab EE | BitBucket | RhodeCode CE | -|---------|-------|------|-----------|-----------|-----------|-----------|--------------| -| Webhook support | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | -| Custom Git Hooks | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | -| AD / LDAP integration | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | -| Multiple LDAP / AD server support | ✓ | ✓ | ✘ | ✘ | ✓ | ✓ | ✓ | -| LDAP user synchronization | ✓ | ✘ | ✓ | ✓ | ✓ | ✓ | ✓ | -| OpenId Connect support | ✓ | ✘ | ✓ | ✓ | ✓ | ? | ✘ | -| OAuth 2.0 integration (external authorization) | ✓ | ✘ | ⁄ | ✓ | ✓ | ? | ✓ | -| Act as OAuth 2.0 provider | [✓](https://github.com/go-gitea/gitea/pull/5378) | ✘ | ✓ | ✓ | ✓ | ✓ | ✘ | -| Two factor authentication (2FA) | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✘ | -| Mattermost/Slack integration | ✓ | ✓ | ⁄ | ✓ | ✓ | ⁄ | ✓ | -| Discord integration | ✓ | ✓ | ✓ | ✓ | ✓ | ✘ | ✘ | -| Microsoft Teams integration | ✓ | ✘ | ✓ | ✓ | ✓ | ✓ | ✘ | -| External CI/CD status display | ✓ | ✘ | ✓ | ✓ | ✓ | ✓ | ✓ | +- _✓ - supported_ + +- _⁄ - supported with limited functionality_ + +- _✘ - unsupported_ + +## General Features + +| Feature | Gitea | Gogs | GitHub EE | GitLab CE | GitLab EE | BitBucket | RhodeCode CE | +| ----------------------------------- | -------------------------------------------------- | ---- | --------- | --------- | --------- | --------- | ------------ | +| Open source and free | ✓ | ✓ | ✘ | ✓ | ✘ | ✘ | ✓ | +| Low resource usage (RAM/CPU) | ✓ | ✓ | ✘ | ✘ | ✘ | ✘ | ✘ | +| Multiple database support | ✓ | ✓ | ✘ | ⁄ | ⁄ | ✓ | ✓ | +| Multiple OS support | ✓ | ✓ | ✘ | ✘ | ✘ | ✘ | ✓ | +| Easy upgrade process | ✓ | ✓ | ✘ | ✓ | ✓ | ✘ | ✓ | +| Markdown support | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | +| Orgmode support | ✓ | ✘ | ✓ | ✘ | ✘ | ✘ | ? | +| CSV support | ✓ | ✘ | ✓ | ✘ | ✘ | ✓ | ? | +| Third-party render tool support | ✓ | ✘ | ✘ | ✘ | ✘ | ✓ | ? | +| Static Git-powered pages | [✘](https://github.com/go-gitea/gitea/issues/302) | ✘ | ✓ | ✓ | ✓ | ✘ | ✘ | +| Integrated Git-powered wiki | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✘ | +| Deploy Tokens | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | +| Repository Tokens with write rights | ✓ | ✘ | ✓ | ✓ | ✓ | ✘ | ✓ | +| Built-in Container Registry | [✘](https://github.com/go-gitea/gitea/issues/2316) | ✘ | ✘ | ✓ | ✓ | ✘ | ✘ | +| External git mirroring | ✓ | ✓ | ✘ | ✘ | ✓ | ✓ | ✓ | +| FIDO U2F (2FA) | ✓ | ✘ | ✓ | ✓ | ✓ | ✓ | ✘ | +| Built-in CI/CD | ✘ | ✘ | ✓ | ✓ | ✓ | ✘ | ✘ | +| Subgroups: groups within groups | ✘ | ✘ | ✘ | ✓ | ✓ | ✘ | ✓ | + +## Code management + +| Feature | Gitea | Gogs | GitHub EE | GitLab CE | GitLab EE | BitBucket | RhodeCode CE | +| -------------------------------------------- | ------------------------------------------------ | ---- | --------- | --------- | --------- | --------- | ------------ | +| Repository topics | ✓ | ✘ | ✓ | ✓ | ✓ | ✘ | ✘ | +| Repository code search | ✓ | ✘ | ✓ | ✓ | ✓ | ✓ | ✓ | +| Global code search | ✓ | ✘ | ✓ | ✘ | ✓ | ✓ | ✓ | +| Git LFS 2.0 | ✓ | ✘ | ✓ | ✓ | ✓ | ⁄ | ✓ | +| Group Milestones | ✘ | ✘ | ✘ | ✓ | ✓ | ✘ | ✘ | +| Granular user roles (Code, Issues, Wiki etc) | ✓ | ✘ | ✘ | ✓ | ✓ | ✘ | ✘ | +| Verified Committer | ⁄ | ✘ | ? | ✓ | ✓ | ✓ | ✘ | +| GPG Signed Commits | ✓ | ✘ | ✓ | ✓ | ✓ | ✓ | ✓ | +| Reject unsigned commits | [✓](https://github.com/go-gitea/gitea/pull/9708) | ✘ | ✓ | ✓ | ✓ | ✘ | ✓ | +| Repository Activity page | ✓ | ✘ | ✓ | ✓ | ✓ | ✓ | ✓ | +| Branch manager | ✓ | ✘ | ✓ | ✓ | ✓ | ✓ | ✓ | +| Create new branches | ✓ | ✘ | ✓ | ✓ | ✓ | ✘ | ✘ | +| Web code editor | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | +| Commit graph | ✓ | ✘ | ✓ | ✓ | ✓ | ✓ | ✓ | +| Template Repositories | [✓](https://github.com/go-gitea/gitea/pull/8768) | ✘ | ✓ | ✘ | ✓ | ✓ | ✘ | + +## Issue Tracker + +| Feature | Gitea | Gogs | GitHub EE | GitLab CE | GitLab EE | BitBucket | RhodeCode CE | +| ------------------------------- | -------------------------------------------------- | --------------------------------------------- | --------- | ----------------------------------------------------------------------- | --------- | --------- | ------------ | +| Issue tracker | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✘ | +| Issue templates | ✓ | ✓ | ✓ | ✓ | ✓ | ✘ | ✘ | +| Labels | ✓ | ✓ | ✓ | ✓ | ✓ | ✘ | ✘ | +| Time tracking | ✓ | ✘ | ✓ | ✓ | ✓ | ✘ | ✘ | +| Multiple assignees for issues | ✓ | ✘ | ✓ | ✘ | ✓ | ✘ | ✘ | +| Related issues | ✘ | ✘ | ⁄ | [✓](https://docs.gitlab.com/ce/user/project/issues/related_issues.html) | ✓ | ✘ | ✘ | +| Confidential issues | [✘](https://github.com/go-gitea/gitea/issues/3217) | ✘ | ✘ | ✓ | ✓ | ✘ | ✘ | +| Comment reactions | ✓ | ✘ | ✓ | ✓ | ✓ | ✘ | ✘ | +| Lock Discussion | ✓ | ✘ | ✓ | ✓ | ✓ | ✘ | ✘ | +| Batch issue handling | ✓ | ✘ | ✓ | ✓ | ✓ | ✘ | ✘ | +| Issue Boards (Kanban) | [✓](https://github.com/go-gitea/gitea/pull/8346) | ✘ | ✘ | ✓ | ✓ | ✘ | ✘ | +| Create new branches from issues | ✘ | ✘ | ✘ | ✓ | ✓ | ✘ | ✘ | +| Issue search | ✓ | ✘ | ✓ | ✓ | ✓ | ✓ | ✘ | +| Global issue search | [✘](https://github.com/go-gitea/gitea/issues/2434) | ✘ | ✓ | ✓ | ✓ | ✓ | ✘ | +| Issue dependency | ✓ | ✘ | ✘ | ✘ | ✘ | ✘ | ✘ | +| Create issue via email | [✘](https://github.com/go-gitea/gitea/issues/6226) | [✘](https://github.com/gogs/gogs/issues/2602) | ✘ | ✘ | ✓ | ✓ | ✘ | +| Service Desk | [✘](https://github.com/go-gitea/gitea/issues/6219) | ✘ | ✘ | [✓](https://gitlab.com/groups/gitlab-org/-/epics/3103) | ✓ | ✘ | ✘ | + +## Pull/Merge requests + +| Feature | Gitea | Gogs | GitHub EE | GitLab CE | GitLab EE | BitBucket | RhodeCode CE | +| ----------------------------------------------- | -------------------------------------------------- | ---- | --------- | --------------------------------------------------------------------------------- | --------- | ------------------------------------------------------------------------ | ------------ | +| Pull/Merge requests | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | +| Squash merging | ✓ | ✘ | ✓ | [✓](https://docs.gitlab.com/ce/user/project/merge_requests/squash_and_merge.html) | ✓ | ✓ | ✓ | +| Rebase merging | ✓ | ✓ | ✓ | ✘ | ⁄ | ✘ | ✓ | +| Pull/Merge request inline comments | ✓ | ✘ | ✓ | ✓ | ✓ | ✓ | ✓ | +| Pull/Merge request approval | ✓ | ✘ | ⁄ | ✓ | ✓ | ✓ | ✓ | +| Merge conflict resolution | [✘](https://github.com/go-gitea/gitea/issues/5158) | ✘ | ✓ | ✓ | ✓ | ✓ | ✘ | +| Restrict push and merge access to certain users | ✓ | ✘ | ✓ | ⁄ | ✓ | ✓ | ✓ | +| Revert specific commits or a merge request | [✘](https://github.com/go-gitea/gitea/issues/5158) | ✘ | ✓ | ✓ | ✓ | ✓ | ✘ | +| Pull/Merge requests templates | ✓ | ✓ | ✓ | ✓ | ✓ | ✘ | ✘ | +| Cherry-picking changes | [✘](https://github.com/go-gitea/gitea/issues/5158) | ✘ | ✘ | ✓ | ✓ | ✘ | ✘ | +| Download Patch | ✓ | ✘ | ✓ | ✓ | ✓ | [/](https://jira.atlassian.com/plugins/servlet/mobile#issue/BCLOUD-8323) | ✘ | + +## 3rd-party integrations + +| Feature | Gitea | Gogs | GitHub EE | GitLab CE | GitLab EE | BitBucket | RhodeCode CE | +| ---------------------------------------------- | ------------------------------------------------ | ---- | --------- | --------- | --------- | --------- | ------------ | +| Webhook support | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | +| Custom Git Hooks | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | +| AD / LDAP integration | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | +| Multiple LDAP / AD server support | ✓ | ✓ | ✘ | ✘ | ✓ | ✓ | ✓ | +| LDAP user synchronization | ✓ | ✘ | ✓ | ✓ | ✓ | ✓ | ✓ | +| OpenId Connect support | ✓ | ✘ | ✓ | ✓ | ✓ | ? | ✘ | +| OAuth 2.0 integration (external authorization) | ✓ | ✘ | ⁄ | ✓ | ✓ | ? | ✓ | +| Act as OAuth 2.0 provider | [✓](https://github.com/go-gitea/gitea/pull/5378) | ✘ | ✓ | ✓ | ✓ | ✓ | ✘ | +| Two factor authentication (2FA) | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✘ | +| Mattermost/Slack integration | ✓ | ✓ | ⁄ | ✓ | ✓ | ⁄ | ✓ | +| Discord integration | ✓ | ✓ | ✓ | ✓ | ✓ | ✘ | ✘ | +| Microsoft Teams integration | ✓ | ✘ | ✓ | ✓ | ✓ | ✓ | ✘ | +| External CI/CD status display | ✓ | ✘ | ✓ | ✓ | ✓ | ✓ | ✓ | diff --git a/docs/content/doc/features/comparison.zh-cn.md b/docs/content/doc/features/comparison.zh-cn.md index b21a9b76d..8ccdebe8c 100644 --- a/docs/content/doc/features/comparison.zh-cn.md +++ b/docs/content/doc/features/comparison.zh-cn.md @@ -3,7 +3,7 @@ date: "2019-02-14T11:51:04+08:00" title: "横向对比 Gitea 与其它 Git 托管工具" slug: "comparison" weight: 5 -toc: true +toc: false draft: false menu: sidebar: diff --git a/docs/content/doc/features/localization.en-us.md b/docs/content/doc/features/localization.en-us.md index a9c9b3480..a5b7a52f8 100644 --- a/docs/content/doc/features/localization.en-us.md +++ b/docs/content/doc/features/localization.en-us.md @@ -3,7 +3,7 @@ date: "2016-12-01T16:00:00+02:00" title: "Localization" slug: "localization" weight: 10 -toc: true +toc: false draft: false menu: sidebar: diff --git a/docs/content/doc/features/localization.zh-cn.md b/docs/content/doc/features/localization.zh-cn.md index 81de966ea..6a6f63732 100644 --- a/docs/content/doc/features/localization.zh-cn.md +++ b/docs/content/doc/features/localization.zh-cn.md @@ -3,7 +3,7 @@ date: "2016-12-01T16:00:00+02:00" title: "本地化" slug: "localization" weight: 10 -toc: true +toc: false draft: false menu: sidebar: diff --git a/docs/content/doc/features/localization.zh-tw.md b/docs/content/doc/features/localization.zh-tw.md index 534ff89f4..b311cc543 100644 --- a/docs/content/doc/features/localization.zh-tw.md +++ b/docs/content/doc/features/localization.zh-tw.md @@ -3,7 +3,7 @@ date: "2016-12-01T16:00:00+02:00" title: "在地化" slug: "localization" weight: 10 -toc: true +toc: false draft: false menu: sidebar: diff --git a/docs/content/doc/features/webhooks.en-us.md b/docs/content/doc/features/webhooks.en-us.md index e75551348..5d792f5f5 100644 --- a/docs/content/doc/features/webhooks.en-us.md +++ b/docs/content/doc/features/webhooks.en-us.md @@ -3,7 +3,7 @@ date: "2016-12-01T16:00:00+02:00" title: "Webhooks" slug: "webhooks" weight: 10 -toc: true +toc: false draft: false menu: sidebar: diff --git a/docs/content/doc/features/webhooks.zh-cn.md b/docs/content/doc/features/webhooks.zh-cn.md index d3bb4797b..fe9008717 100644 --- a/docs/content/doc/features/webhooks.zh-cn.md +++ b/docs/content/doc/features/webhooks.zh-cn.md @@ -3,7 +3,7 @@ date: "2016-12-01T16:00:00+02:00" title: "Webhooks" slug: "webhooks" weight: 10 -toc: true +toc: false draft: false menu: sidebar: diff --git a/docs/content/doc/features/webhooks.zh-tw.md b/docs/content/doc/features/webhooks.zh-tw.md index d3bb4797b..fe9008717 100644 --- a/docs/content/doc/features/webhooks.zh-tw.md +++ b/docs/content/doc/features/webhooks.zh-tw.md @@ -3,7 +3,7 @@ date: "2016-12-01T16:00:00+02:00" title: "Webhooks" slug: "webhooks" weight: 10 -toc: true +toc: false draft: false menu: sidebar: diff --git a/docs/content/doc/help/faq.en-us.md b/docs/content/doc/help/faq.en-us.md index 9c7211937..bd7d808e8 100644 --- a/docs/content/doc/help/faq.en-us.md +++ b/docs/content/doc/help/faq.en-us.md @@ -3,7 +3,7 @@ date: "2019-04-05T16:00:00+02:00" title: "FAQ" slug: "faq" weight: 5 -toc: true +toc: false draft: false menu: sidebar: @@ -16,26 +16,30 @@ menu: # Frequently Asked Questions This page contains some common questions and answers. -Also see [Support Options]({{< relref "doc/help/seek-help.en-us.md" >}}) +For more help resources, check all [Support Options]({{< relref "doc/help/seek-help.en-us.md" >}}). + +**Table of Contents** {{< toc >}} ## Difference between 1.x and 1.x.x downloads + Version 1.7.x will be used for this example. -**NOTE:** this example applies to Docker images as well! +**NOTE:** this example applies to Docker images as well! On our [downloads page](https://dl.gitea.io/gitea/) you will see a 1.7 directory, as well as directories for 1.7.0, 1.7.1, 1.7.2, 1.7.3, 1.7.4, 1.7.5, and 1.7.6. The 1.7 and 1.7.0 directories are **not** the same. The 1.7 directory is built on each merged commit to the [`release/v1.7`](https://github.com/go-gitea/gitea/tree/release/v1.7) branch. -The 1.7.0 directory, however, is a build that was created when the [`v1.7.0`](https://github.com/go-gitea/gitea/releases/tag/v1.7.0) tag was created. +The 1.7.0 directory, however, is a build that was created when the [`v1.7.0`](https://github.com/go-gitea/gitea/releases/tag/v1.7.0) tag was created. This means that 1.x downloads will change as commits are merged to their respective branch (think of it as a separate "master" branch for each release). On the other hand, 1.x.x downloads should never change. ## How to migrate from Gogs/GitHub/etc. to Gitea + To migrate from Gogs to Gitea: -* [Gogs version 0.9.146 or less]({{< relref "doc/upgrade/from-gogs.en-us.md" >}}) -* [Gogs version 0.11.46.0418](https://github.com/go-gitea/gitea/issues/4286) +- [Gogs version 0.9.146 or less]({{< relref "doc/upgrade/from-gogs.en-us.md" >}}) +- [Gogs version 0.11.46.0418](https://github.com/go-gitea/gitea/issues/4286) To migrate from GitHub to Gitea, you can use Gitea's built-in migration form. In order to migrate items such as issues, pull requests, etc. you will need to input at least your username. @@ -45,29 +49,31 @@ To migrate from Gitlab to Gitea, you can use this non-affiliated tool: https://github.com/loganinak/MigrateGitlabToGogs ## Where does Gitea store what file -* WorkPath - * Environment variable `GITEA_WORK_DIR` - * Else binary location -* AppDataPath (default for database, indexers, etc.) - * `APP_DATA_PATH` from `app.ini` - * Else `%(WorkPath)/data` -* CustomPath (custom templates) - * Environment variable `GITEA_CUSTOM` - * Else `%(WorkPath)/custom` -* HomeDir - * Unix: Environment variable `HOME` - * Windows: Environment variable `USERPROFILE`, else environment variables `HOMEDRIVE`+`HOMEPATH` -* RepoRootPath - * `ROOT` in `app.ini` - * Else `%(HomeDir)/gitea-repositories` -* INI (config file) - * `-c` flag - * Else `%(CustomPath)/conf/app.ini` -* SQLite Database - * `PATH` in `database` section of `app.ini` - * Else `%(AppDataPath)/gitea.db` + +- WorkPath + - Environment variable `GITEA_WORK_DIR` + - Else binary location +- AppDataPath (default for database, indexers, etc.) + - `APP_DATA_PATH` from `app.ini` + - Else `%(WorkPath)/data` +- CustomPath (custom templates) + - Environment variable `GITEA_CUSTOM` + - Else `%(WorkPath)/custom` +- HomeDir + - Unix: Environment variable `HOME` + - Windows: Environment variable `USERPROFILE`, else environment variables `HOMEDRIVE`+`HOMEPATH` +- RepoRootPath + - `ROOT` in `app.ini` + - Else `%(HomeDir)/gitea-repositories` +- INI (config file) + - `-c` flag + - Else `%(CustomPath)/conf/app.ini` +- SQLite Database + - `PATH` in `database` section of `app.ini` + - Else `%(AppDataPath)/gitea.db` ## Not seeing a clone URL or the clone URL being incorrect + There are a few places that could make this show incorrectly. 1. If using a reverse proxy, make sure you have followed the correction directions in the [reverse proxy guide]({{< relref "doc/usage/reverse-proxies.en-us.md" >}}) @@ -77,26 +83,31 @@ If certain clone options aren't showing up (HTTP/S or SSH), the following option `DISABLE_HTTP_GIT`: if set to true, there will be no HTTP/HTTPS link `DISABLE_SSH`: if set to true, there will be no SSH link -`SSH_EXPOSE_ANONYMOUS`: if set to false, SSH links will be hidden for anonymous users - +`SSH_EXPOSE_ANONYMOUS`: if set to false, SSH links will be hidden for anonymous users ## Custom Templates not loading or working incorrectly + Gitea's custom templates must be added to the correct location or Gitea will not find and use them. 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` + +- 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-x-file) 3. Once you have figured out the correct custom path, you can refer to the [customizing Gitea]({{< relref "doc/advanced/customizing-gitea.en-us.md" >}}) page to add your template to the correct location. ## Active user vs login prohibited user + In Gitea, an "active" user refers to a user that has activated their account via email. A "login prohibited" user is a user that is not allowed to log in to Gitea anymore ## Setting up logging -* [Official Docs]({{< relref "doc/advanced/logging-documentation.en-us.md" >}}) + +- [Official Docs]({{< relref "doc/advanced/logging-documentation.en-us.md" >}}) ## What is Swagger? + [Swagger](https://swagger.io/) is what Gitea uses for its API. All Gitea instances have the built-in API, though it can be disabled by setting `ENABLE_SWAGGER` to `false` in the `api` section of your `app.ini` For more information, refer to Gitea's [API docs]({{< relref "doc/developers/api-usage.en-us.md" >}}) @@ -106,52 +117,60 @@ For more information, refer to Gitea's [API docs]({{< relref "doc/developers/api ## Adjusting your server for public/private use ### Preventing spammers -There are multiple things you can combine to prevent spammers. + +There are multiple things you can combine to prevent spammers. 1. By only whitelisting certain domains with OpenID (see below) 2. Setting `ENABLE_CAPTCHA` to `true` in your `app.ini` and properly configuring `RECAPTCHA_SECRET` and `RECAPTCHA_SITEKEY` -3. Settings `DISABLE_REGISTRATION` to `true` and creating new users via the [CLI]({{< relref "doc/usage/command-line.en-us.md" >}}), [API]({{< relref "doc/developers/api-usage.en-us.md" >}}), or Gitea's Admin UI +3. Settings `DISABLE_REGISTRATION` to `true` and creating new users via the [CLI]({{< relref "doc/usage/command-line.en-us.md" >}}), [API]({{< relref "doc/developers/api-usage.en-us.md" >}}), or Gitea's Admin UI ### Only allow certain email domains + You can configure `EMAIL_DOMAIN_WHITELIST` in your app.ini under `[service]` ### Only allow/block certain OpenID providers + You can configure `WHITELISTED_URIS` or `BLACKLISTED_URIS` under `[openid]` in your `app.ini` **NOTE:** whitelisted takes precedence, so if it is non-blank then blacklisted is ignored ### Issue only users + The current way to achieve this is to create/modify a user with a max repo creation limit of 0. ### Restricted users -Restricted users are limited to a subset of the content based on their organization/team memberships and collaborations, ignoring the public flag on organizations/repos etc.__ + +Restricted users are limited to a subset of the content based on their organization/team memberships and collaborations, ignoring the public flag on organizations/repos etc.\_\_ Example use case: A company runs a Gitea instance that requires login. Most repos are public (accessible/browseable by all co-workers). At some point, a customer or third party needs access to a specific repo and only that repo. Making such a customer account restricted and granting any needed access using team membership(s) and/or collaboration(s) is a simple way to achieve that without the need to make everything private. - ### Enable Fail2ban Use [Fail2Ban]({{< relref "doc/usage/fail2ban-setup.en-us.md" >}}) to monitor and stop automated login attempts or other malicious behavior based on log patterns ## How to add/use custom themes + Gitea supports two official themes right now, `gitea` and `arc-green` (`light` and `dark` respectively) -To add your own theme, currently the only way is to provide a complete theme (not just color overrides) +To add your own theme, currently the only way is to provide a complete theme (not just color overrides) As an example, let's say our theme is `arc-blue` (this is a real theme, and can be found [in this issue](https://github.com/go-gitea/gitea/issues/6011)) Name the `.css` file `theme-arc-blue.css` and add it to your custom folder in `custom/pulic/css` Allow users to use it by adding `arc-blue` to the list of `THEMES` in your `app.ini` ## SSHD vs built-in SSH + SSHD is the built-in SSH server on most Unix systems. Gitea also provides its own SSH server, for usage when SSHD is not available. ## Gitea is running slow + The most common culprit for this is loading federated avatars. This can be turned off by setting `ENABLE_FEDERATED_AVATAR` to `false` in your `app.ini` Another option that may need to be changed is setting `DISABLE_GRAVATAR` to `true` in your `app.ini` ## Can't create repositories/files + Make sure that Gitea has sufficient permissions to write to its home directory and data directory. See [AppDataPath and RepoRootPath](#where-does-gitea-store-x-file) @@ -160,22 +179,26 @@ See [AppDataPath and RepoRootPath](#where-does-gitea-store-x-file) Which makes all other paths non-writeable to Gitea. ## Translation is incorrect/how to add more translations + Our translations are currently crowd-sourced on our [Crowdin project](https://crowdin.com/project/gitea) Whether you want to change a translation or add a new one, it will need to be there as all translations are overwritten in our CI via the Crowdin integration. ## Hooks aren't running + If Gitea is not running hooks, a common cause is incorrect setup of SSH keys. -See [SSH Issues](#ssh-issues) for more information. +See [SSH Issues](#ssh-issues) for more information. You can also try logging into the administration panel and running the `Resynchronize pre-receive, update and post-receive hooks of all repositories.` option. ## SSH issues + If you cannot reach repositories over `ssh`, but `https` works fine, consider looking into the following. First, make sure you can access Gitea via SSH. -`ssh git@myremote.example` +`ssh git@myremote.example` If the connection is successful, you should receive an error message like the following: + ``` Hi there, You've successfully authenticated, but Gitea does not provide shell access. If this is unexpected, please log in with password and setup Gitea under another user. @@ -196,20 +219,20 @@ fatal: Could not read from remote repository. This error signifies that the server rejected a log in attempt, check the following things: -* On the client: - * Ensure the public and private ssh keys are added to the correct Gitea user. - * Make sure there are no issues in the remote url. In particular, ensure the name of the +- On the client: + - Ensure the public and private ssh keys are added to the correct Gitea user. + - Make sure there are no issues in the remote url. In particular, ensure the name of the git user (before the `@`) is spelled correctly. - * Ensure public and private ssh keys are correct on client machine. -* On the server: - * Make sure the repository exists and is correctly named. - * Check the permissions of the `.ssh` directory in the system user's home directory. - * Verify that the correct public keys are added to `.ssh/authorized_keys`. + - Ensure public and private ssh keys are correct on client machine. +- On the server: + - Make sure the repository exists and is correctly named. + - Check the permissions of the `.ssh` directory in the system user's home directory. + - Verify that the correct public keys are added to `.ssh/authorized_keys`. Try to run `Rewrite '.ssh/authorized_keys' file (for Gitea SSH keys)` on the Gitea admin panel. - * Read Gitea logs. - * Read /var/log/auth (or similar). - * Check permissions of repositories. + - Read Gitea logs. + - Read /var/log/auth (or similar). + - Check permissions of repositories. The following is an example of a missing public SSH key where authentication succeeded, but some other setting is preventing SSH from reaching the correct @@ -224,58 +247,65 @@ and the repository exists. In this case, look into the following settings: -* On the server: - * Make sure that the `git` system user has a usable shell set - * Verify this with `getent passwd git | cut -d: -f7` - * `usermod` or `chsh` can be used to modify this. - * Ensure that the `gitea serv` command in `.ssh/authorized_keys` uses the +- On the server: + - Make sure that the `git` system user has a usable shell set + - Verify this with `getent passwd git | cut -d: -f7` + - `usermod` or `chsh` can be used to modify this. + - Ensure that the `gitea serv` command in `.ssh/authorized_keys` uses the correct configuration file. ## Missing releases after migrating repository with tags -To migrate an repository *with* all tags, you need to do two things: +To migrate an repository _with_ all tags, you need to do two things: + +- Push tags to the repository: -* Push tags to the repository: ``` git push --tags - ``` +``` - * (Re-)sync tags of all repositories within Gitea: - ``` - gitea admin repo-sync-releases - ``` +- (Re-)sync tags of all repositories within Gitea: + +``` +gitea admin repo-sync-releases +``` ## LFS Issues For issues concerning LFS data upload ``` -batch response: Authentication required: Authorization error: /info/lfs/objects/batch +batch response: Authentication required: Authorization error: /info/lfs/objects/batch Check that you have proper access to the repository error: failed to push some refs to '' ``` + Check the value of `LFS_HTTP_AUTH_EXPIRY` in your `app.ini` file. By default, your LFS token will expire after 20 minutes. If you have a slow connection or a large file (or both), it may not finish uploading within the time limit. You may want to set this value to `60m` or `120m`. ## How can I create users before starting Gitea + Gitea provides a sub-command `gitea migrate` to initialize the database, after which you can use the [admin CLI commands]({{< relref "doc/usage/command-line.en-us.md#admin" >}}) to add users like normal. ## How can I enable password reset + There is no setting for password resets. It is enabled when a [mail service]({{< relref "doc/usage/email-setup.en-us.md" >}}) is configured, and disabled otherwise. ## How can a user's password be changed + - As an **admin**, you can change any user's password (and optionally force them to change it on next login)... - - By navigating to your `Site Administration -> User Accounts` page and editing a user. + - By navigating to your `Site Administration -> User Accounts` page and editing a user. - By using the [admin CLI commands]({{< relref "doc/usage/command-line.en-us.md#admin" >}}). - Keep in mind most commands will also need a [global flag]({{< relref "doc/usage/command-line.en-us.md#global-options" >}}) to point the CLI at the correct configuration. + Keep in mind most commands will also need a [global flag]({{< relref "doc/usage/command-line.en-us.md#global-options" >}}) to point the CLI at the correct configuration. - As a **user** you can change it... - In your account `Settings -> Account` page (this method **requires** you to know your current password). - By using the `Forgot Password` link. - If the `Forgot Password/Account Recovery` page is disabled, please contact your administrator to configure a [mail service]({{< relref "doc/usage/email-setup.en-us.md" >}}). + If the `Forgot Password/Account Recovery` page is disabled, please contact your administrator to configure a [mail service]({{< relref "doc/usage/email-setup.en-us.md" >}}). ## Why is my markdown broken + In Gitea version `1.11` we moved to [goldmark](https://github.com/yuin/goldmark) for markdown rendering, which is [CommonMark](https://commonmark.org/) compliant. If you have markdown that worked as you expected prior to version `1.11` and after upgrading it's not working anymore, please look through the CommonMark spec to see whether the problem is due to a bug or non-compliant syntax. If it is the latter, _usually_ there is a compliant alternative listed in the spec. diff --git a/docs/content/doc/help/search.en-us.md b/docs/content/doc/help/search.en-us.md index b24492fa2..8d4b0d20c 100644 --- a/docs/content/doc/help/search.en-us.md +++ b/docs/content/doc/help/search.en-us.md @@ -3,7 +3,7 @@ date: "2019-11-12T16:00:00+02:00" title: "Search" slug: "search" weight: 4 -toc: true +toc: false draft: false menu: sidebar: diff --git a/docs/content/doc/help/search.fr-fr.md b/docs/content/doc/help/search.fr-fr.md index b580ee374..16fff85a9 100644 --- a/docs/content/doc/help/search.fr-fr.md +++ b/docs/content/doc/help/search.fr-fr.md @@ -3,7 +3,7 @@ date: "2019-11-12T16:00:00+02:00" title: "Chercher" slug: "search" weight: 4 -toc: true +toc: false draft: false menu: sidebar: diff --git a/docs/content/doc/help/search.zh-cn.md b/docs/content/doc/help/search.zh-cn.md index 011ea817e..52fae9def 100644 --- a/docs/content/doc/help/search.zh-cn.md +++ b/docs/content/doc/help/search.zh-cn.md @@ -3,7 +3,7 @@ date: "2019-11-12T16:00:00+02:00" title: "搜索" slug: "search" weight: 4 -toc: true +toc: false draft: false menu: sidebar: diff --git a/docs/content/doc/help/search.zh-tw.md b/docs/content/doc/help/search.zh-tw.md index 011ea817e..52fae9def 100644 --- a/docs/content/doc/help/search.zh-tw.md +++ b/docs/content/doc/help/search.zh-tw.md @@ -3,7 +3,7 @@ date: "2019-11-12T16:00:00+02:00" title: "搜索" slug: "search" weight: 4 -toc: true +toc: false draft: false menu: sidebar: diff --git a/docs/content/doc/help/seek-help.en-us.md b/docs/content/doc/help/seek-help.en-us.md index 058a5bb59..56e3eb9d8 100644 --- a/docs/content/doc/help/seek-help.en-us.md +++ b/docs/content/doc/help/seek-help.en-us.md @@ -3,7 +3,7 @@ date: "2018-05-21T15:00:00+00:00" title: "Support Options" slug: "seek-help" weight: 10 -toc: true +toc: false draft: false menu: sidebar: diff --git a/docs/content/doc/help/seek-help.zh-cn.md b/docs/content/doc/help/seek-help.zh-cn.md index a2cf317e3..77973d591 100644 --- a/docs/content/doc/help/seek-help.zh-cn.md +++ b/docs/content/doc/help/seek-help.zh-cn.md @@ -3,7 +3,7 @@ date: "2017-01-20T15:00:00+08:00" title: "需要帮助" slug: "seek-help" weight: 10 -toc: true +toc: false draft: false menu: sidebar: diff --git a/docs/content/doc/installation/database-preparation.en-us.md b/docs/content/doc/installation/database-preparation.en-us.md index 32cfe1812..de2ed9caf 100644 --- a/docs/content/doc/installation/database-preparation.en-us.md +++ b/docs/content/doc/installation/database-preparation.en-us.md @@ -3,7 +3,7 @@ date: "2020-01-16" title: "Database Preparation" slug: "database-prep" weight: 10 -toc: true +toc: false draft: false menu: sidebar: @@ -19,7 +19,9 @@ You need a database to use Gitea. Gitea supports PostgreSQL, MySQL, SQLite, and Database instance can be on same machine as Gitea (local database setup), or on different machine (remote database). -Note: All steps below requires that the database engine of your choice is installed on your system. For remote database setup, install the server part on database instance and client part on your Gitea server. In addition, make sure you use same engine version for both server and client for some engine features to work. For security reason, protect `root` (MySQL) or `postgres` (PostgreSQL) database superuser with secure password. The steps assumes that you run Linux for both database and Gitea servers. +Note: All steps below requires that the database engine of your choice is installed on your system. For remote database setup, install the server part on database instance and client part on your Gitea server. In addition, make sure you use same engine version for both server and client for some engine features to work. For security reason, protect `root` (MySQL) or `postgres` (PostgreSQL) database superuser with secure password. The steps assumes that you run Linux for both database and Gitea servers. + +**Table of Contents** {{< toc >}} @@ -30,6 +32,7 @@ Note: All steps below requires that the database engine of your choice is instal ```ini bind-address = 203.0.113.3 ``` + 2. On database instance, login to database console as root: ``` @@ -58,7 +61,7 @@ Note: All steps below requires that the database engine of your choice is instal Replace username and password above as appropriate. -4. Create database with UTF-8 charset and collation. Make sure to use `utf8mb4` charset instead of `utf8` as the former supports all Unicode characters (including emojis) beyond *Basic Multilingual Plane*. Also, collation chosen depending on your expected content. When in doubt, use either `unicode_ci` or `general_ci`. +4. Create database with UTF-8 charset and collation. Make sure to use `utf8mb4` charset instead of `utf8` as the former supports all Unicode characters (including emojis) beyond _Basic Multilingual Plane_. Also, collation chosen depending on your expected content. When in doubt, use either `unicode_ci` or `general_ci`. ```sql CREATE DATABASE giteadb CHARACTER SET 'utf8mb4' COLLATE 'utf8mb4_unicode_ci'; @@ -187,9 +190,9 @@ The PostgreSQL driver used by Gitea supports two-way TLS. In two-way TLS, both d 1. On the server with the database instance, place the following credentials: - - `/path/to/postgresql.crt`: Database instance certificate - - `/path/to/postgresql.key`: Database instance private key - - `/path/to/root.crt`: CA certificate chain to validate client certificates + - `/path/to/postgresql.crt`: Database instance certificate + - `/path/to/postgresql.key`: Database instance private key + - `/path/to/root.crt`: CA certificate chain to validate client certificates 2. Add following options to `postgresql.conf`: @@ -228,9 +231,9 @@ The PostgreSQL driver used by Gitea supports two-way TLS. In two-way TLS, both d 6. On the server running the Gitea instance, place the following credentials under the home directory of the user who runs Gitea (e.g. `git`): - - `~/.postgresql/postgresql.crt`: Database client certificate - - `~/.postgresql/postgresql.key`: Database client private key - - `~/.postgresql/root.crt`: CA certificate chain to validate server certificate + - `~/.postgresql/postgresql.crt`: Database client certificate + - `~/.postgresql/postgresql.key`: Database client private key + - `~/.postgresql/root.crt`: CA certificate chain to validate server certificate Note: Those file names above are hardcoded in PostgreSQL and it is not possible to change them. @@ -249,19 +252,17 @@ The PostgreSQL driver used by Gitea supports two-way TLS. In two-way TLS, both d You should be prompted to enter password for the database user, and then be connected to the database. - ### MySQL While the MySQL driver used by Gitea also supports two-way TLS, Gitea currently supports only one-way TLS. See issue #10828 for details. In one-way TLS, the database client verifies the certificate sent from server during the connection handshake, and the server assumes that the connected client is legitimate, since client certificate verification doesn't take place. - 1. On the database instance, place the following credentials: - - `/path/to/mysql.crt`: Database instance certificate - - `/path/to/mysql.key`: Database instance key - - `/path/to/ca.crt`: CA certificate chain. This file isn't used on one-way TLS, but is used to validate client certificates on two-way TLS. + - `/path/to/mysql.crt`: Database instance certificate + - `/path/to/mysql.key`: Database instance key + - `/path/to/ca.crt`: CA certificate chain. This file isn't used on one-way TLS, but is used to validate client certificates on two-way TLS. 2. Add following options to `my.cnf`: diff --git a/docs/content/doc/installation/from-binary.en-us.md b/docs/content/doc/installation/from-binary.en-us.md index aac10d577..229a3cde4 100644 --- a/docs/content/doc/installation/from-binary.en-us.md +++ b/docs/content/doc/installation/from-binary.en-us.md @@ -3,7 +3,7 @@ date: "2017-06-19T12:00:00+02:00" title: "Installation from binary" slug: "install-from-binary" weight: 10 -toc: true +toc: false draft: false menu: sidebar: @@ -18,6 +18,8 @@ menu: All downloads come with SQLite, MySQL and PostgreSQL support, and are built with embedded assets. This can be different for older releases. +**Table of Contents** + {{< toc >}} ## Download diff --git a/docs/content/doc/installation/from-binary.fr-fr.md b/docs/content/doc/installation/from-binary.fr-fr.md index 5ba16e2d6..b92381484 100644 --- a/docs/content/doc/installation/from-binary.fr-fr.md +++ b/docs/content/doc/installation/from-binary.fr-fr.md @@ -3,7 +3,7 @@ date: "2017-08-23T09:00:00+02:00" title: "Installation avec le binaire pré-compilé" slug: "install-from-binary" weight: 10 -toc: true +toc: false draft: false menu: sidebar: diff --git a/docs/content/doc/installation/from-binary.zh-cn.md b/docs/content/doc/installation/from-binary.zh-cn.md index 186cbf572..f04166c3a 100644 --- a/docs/content/doc/installation/from-binary.zh-cn.md +++ b/docs/content/doc/installation/from-binary.zh-cn.md @@ -3,7 +3,7 @@ date: "2016-12-01T16:00:00+02:00" title: "从二进制安装" slug: "install-from-binary" weight: 10 -toc: true +toc: false draft: false menu: sidebar: diff --git a/docs/content/doc/installation/from-binary.zh-tw.md b/docs/content/doc/installation/from-binary.zh-tw.md index d5a838493..48c764fa5 100644 --- a/docs/content/doc/installation/from-binary.zh-tw.md +++ b/docs/content/doc/installation/from-binary.zh-tw.md @@ -3,7 +3,7 @@ date: "2016-12-01T16:00:00+02:00" title: "執行檔安裝" slug: "install-from-binary" weight: 10 -toc: true +toc: false draft: false menu: sidebar: diff --git a/docs/content/doc/installation/from-package.en-us.md b/docs/content/doc/installation/from-package.en-us.md index 91c57a80f..a294c9d69 100644 --- a/docs/content/doc/installation/from-package.en-us.md +++ b/docs/content/doc/installation/from-package.en-us.md @@ -3,7 +3,7 @@ date: "2016-12-01T16:00:00+02:00" title: "Installation from package" slug: "install-from-package" weight: 10 -toc: true +toc: false draft: false menu: sidebar: @@ -15,6 +15,8 @@ menu: # Installation from package +**Table of Contents** + {{< toc >}} ## Alpine Linux @@ -50,6 +52,7 @@ choco install gitea ``` Or follow the [deployment from binary]({{< relref "from-binary.en-us.md" >}}) guide. + ## macOS Currently, the only supported method of installation on MacOS is [Homebrew](http://brew.sh/). diff --git a/docs/content/doc/installation/from-package.fr-fr.md b/docs/content/doc/installation/from-package.fr-fr.md index 0ae42f93b..130dd2616 100644 --- a/docs/content/doc/installation/from-package.fr-fr.md +++ b/docs/content/doc/installation/from-package.fr-fr.md @@ -3,7 +3,7 @@ date: "2016-12-01T16:00:00+02:00" title: "Installation depuis le gestionnaire de paquets" slug: "install-from-package" weight: 10 -toc: true +toc: false draft: false menu: sidebar: diff --git a/docs/content/doc/installation/from-package.zh-cn.md b/docs/content/doc/installation/from-package.zh-cn.md index 0557cae97..dc5a283bb 100644 --- a/docs/content/doc/installation/from-package.zh-cn.md +++ b/docs/content/doc/installation/from-package.zh-cn.md @@ -3,7 +3,7 @@ date: "2016-12-01T16:00:00+02:00" title: "选择包安装" slug: "install-from-package" weight: 10 -toc: true +toc: false draft: false menu: sidebar: diff --git a/docs/content/doc/installation/from-package.zh-tw.md b/docs/content/doc/installation/from-package.zh-tw.md index 8fbb7e2a8..5b4e4c9f9 100644 --- a/docs/content/doc/installation/from-package.zh-tw.md +++ b/docs/content/doc/installation/from-package.zh-tw.md @@ -3,7 +3,7 @@ date: "2016-12-01T16:00:00+02:00" title: "套件安裝" slug: "install-from-package" weight: 10 -toc: true +toc: false draft: false menu: sidebar: diff --git a/docs/content/doc/installation/from-source.en-us.md b/docs/content/doc/installation/from-source.en-us.md index 5fc521204..e83495166 100644 --- a/docs/content/doc/installation/from-source.en-us.md +++ b/docs/content/doc/installation/from-source.en-us.md @@ -3,7 +3,7 @@ date: "2016-12-01T16:00:00+02:00" title: "Installation from source" slug: "install-from-source" weight: 10 -toc: true +toc: false draft: false menu: sidebar: @@ -36,6 +36,8 @@ obtain the same version as our continuous integration, see the advice given in Hacking on Gitea +**Table of Contents** + {{< toc >}} ## Download @@ -92,11 +94,11 @@ are provided to keep the build process as simple as possible. Depending on requirements, the following build tags can be included. -* `bindata`: Build a single monolithic binary, with all assets included. -* `sqlite sqlite_unlock_notify`: Enable support for a +- `bindata`: Build a single monolithic binary, with all assets included. +- `sqlite sqlite_unlock_notify`: Enable support for a [SQLite3](https://sqlite.org/) database. Suggested only for tiny installations. -* `pam`: Enable support for PAM (Linux Pluggable Authentication Modules). Can +- `pam`: Enable support for PAM (Linux Pluggable Authentication Modules). Can be used to authenticate local users or extend authentication to methods available to PAM. @@ -153,11 +155,11 @@ One option is to use a script file to shadow the `gitea` binary and create an ap 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 `AppWorkPath` you should use `-X \"code.gitea.io/gitea/modules/setting.AppWorkPath=working-path\"` -* For `StaticRootPath` you should use `-X \"code.gitea.io/gitea/modules/setting.StaticRootPath=static-root-path\"` -* To change the default PID file location use `-X \"code.gitea.io/gitea/modules/setting.PIDFile=/run/gitea.pid\"` +- 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 `AppWorkPath` you should use `-X \"code.gitea.io/gitea/modules/setting.AppWorkPath=working-path\"` +- For `StaticRootPath` you should use `-X \"code.gitea.io/gitea/modules/setting.StaticRootPath=static-root-path\"` +- To change the default PID file location use `-X \"code.gitea.io/gitea/modules/setting.PIDFile=/run/gitea.pid\"` Add as many of the strings with their preceding `-X` to the `LDFLAGS` variable and run `make build` with the appropriate `TAGS` as above. diff --git a/docs/content/doc/installation/from-source.fr-fr.md b/docs/content/doc/installation/from-source.fr-fr.md index 34817bdc0..4afbd1377 100644 --- a/docs/content/doc/installation/from-source.fr-fr.md +++ b/docs/content/doc/installation/from-source.fr-fr.md @@ -3,7 +3,7 @@ date: "2017-08-23T09:00:00+02:00" title: "Installation depuis le code source" slug: "install-from-source" weight: 10 -toc: true +toc: false draft: false menu: sidebar: diff --git a/docs/content/doc/installation/from-source.zh-cn.md b/docs/content/doc/installation/from-source.zh-cn.md index cbae5218a..7d0803360 100644 --- a/docs/content/doc/installation/from-source.zh-cn.md +++ b/docs/content/doc/installation/from-source.zh-cn.md @@ -3,7 +3,7 @@ date: "2016-12-01T16:00:00+02:00" title: "从源代码安装" slug: "install-from-source" weight: 10 -toc: true +toc: false draft: false menu: sidebar: diff --git a/docs/content/doc/installation/from-source.zh-tw.md b/docs/content/doc/installation/from-source.zh-tw.md index 1619c8ec0..39c987830 100644 --- a/docs/content/doc/installation/from-source.zh-tw.md +++ b/docs/content/doc/installation/from-source.zh-tw.md @@ -3,7 +3,7 @@ date: "2016-12-01T16:00:00+02:00" title: "原始碼安裝" slug: "install-from-source" weight: 10 -toc: true +toc: false draft: false menu: sidebar: diff --git a/docs/content/doc/installation/on-kubernetes.en-us.md b/docs/content/doc/installation/on-kubernetes.en-us.md index 025117f64..9fe869254 100644 --- a/docs/content/doc/installation/on-kubernetes.en-us.md +++ b/docs/content/doc/installation/on-kubernetes.en-us.md @@ -3,7 +3,7 @@ date: "2020-03-19T19:27:00+02:00" title: "Install on Kubernetes" slug: "install-on-kubernetes" weight: 10 -toc: true +toc: false draft: false menu: sidebar: diff --git a/docs/content/doc/installation/run-as-service-in-ubuntu.en-us.md b/docs/content/doc/installation/run-as-service-in-ubuntu.en-us.md index 7af062c3a..1c5551e6f 100644 --- a/docs/content/doc/installation/run-as-service-in-ubuntu.en-us.md +++ b/docs/content/doc/installation/run-as-service-in-ubuntu.en-us.md @@ -3,7 +3,7 @@ date: "2017-07-21T12:00:00+02:00" title: "Run as service in Linux" slug: "linux-service" weight: 10 -toc: true +toc: false draft: false menu: sidebar: diff --git a/docs/content/doc/installation/run-as-service-in-ubuntu.zh-cn.md b/docs/content/doc/installation/run-as-service-in-ubuntu.zh-cn.md index 364748ddc..02cd032b6 100644 --- a/docs/content/doc/installation/run-as-service-in-ubuntu.zh-cn.md +++ b/docs/content/doc/installation/run-as-service-in-ubuntu.zh-cn.md @@ -3,7 +3,7 @@ date: "2017-07-21T12:00:00+02:00" title: "在 Linux 中以 service 方式运行" slug: "linux-service" weight: 10 -toc: true +toc: false draft: false menu: sidebar: diff --git a/docs/content/doc/installation/windows-service.en-us.md b/docs/content/doc/installation/windows-service.en-us.md index 9c36786cf..430fdaabd 100644 --- a/docs/content/doc/installation/windows-service.en-us.md +++ b/docs/content/doc/installation/windows-service.en-us.md @@ -3,7 +3,7 @@ date: "2016-12-21T15:00:00-02:00" title: "Register as a Windows Service" slug: "windows-service" weight: 10 -toc: true +toc: false draft: false menu: sidebar: diff --git a/docs/content/doc/installation/windows-service.fr-fr.md b/docs/content/doc/installation/windows-service.fr-fr.md index 0a45bad20..8a6c4f44e 100644 --- a/docs/content/doc/installation/windows-service.fr-fr.md +++ b/docs/content/doc/installation/windows-service.fr-fr.md @@ -3,7 +3,7 @@ date: "2017-08-23T09:00:00+02:00" title: "Démarrer en tant que service Windows" slug: "windows-service" weight: 10 -toc: true +toc: false draft: false menu: sidebar: diff --git a/docs/content/doc/installation/windows-service.zh-cn.md b/docs/content/doc/installation/windows-service.zh-cn.md index 063c644de..1e9685286 100644 --- a/docs/content/doc/installation/windows-service.zh-cn.md +++ b/docs/content/doc/installation/windows-service.zh-cn.md @@ -3,7 +3,7 @@ date: "2016-12-21T15:00:00-02:00" title: "注册为Windows服务" slug: "windows-service" weight: 10 -toc: true +toc: false draft: false menu: sidebar: diff --git a/docs/content/doc/installation/windows-service.zh-tw.md b/docs/content/doc/installation/windows-service.zh-tw.md index 2ee886ff2..37b068c58 100644 --- a/docs/content/doc/installation/windows-service.zh-tw.md +++ b/docs/content/doc/installation/windows-service.zh-tw.md @@ -3,7 +3,7 @@ date: "2016-12-21T15:00:00-02:00" title: "註冊為 Windows 服務" slug: "windows-service" weight: 10 -toc: true +toc: false draft: false menu: sidebar: diff --git a/docs/content/doc/installation/with-docker-rootless.en-us.md b/docs/content/doc/installation/with-docker-rootless.en-us.md index b85663720..23ce3a9f2 100644 --- a/docs/content/doc/installation/with-docker-rootless.en-us.md +++ b/docs/content/doc/installation/with-docker-rootless.en-us.md @@ -3,7 +3,7 @@ date: "2020-02-09T20:00:00+02:00" title: "Installation with Docker (rootless)" slug: "install-with-docker-rootless" weight: 10 -toc: true +toc: false draft: true menu: sidebar: diff --git a/docs/content/doc/installation/with-docker.en-us.md b/docs/content/doc/installation/with-docker.en-us.md index ac085e4ef..4118d190d 100644 --- a/docs/content/doc/installation/with-docker.en-us.md +++ b/docs/content/doc/installation/with-docker.en-us.md @@ -3,7 +3,7 @@ date: "2020-03-19T19:27:00+02:00" title: "Installation with Docker" slug: "install-with-docker" weight: 10 -toc: true +toc: false draft: false menu: sidebar: @@ -23,6 +23,8 @@ This reference setup guides users through the setup based on `docker-compose`, b of `docker-compose` is out of scope of this documentation. To install `docker-compose` itself, follow the official [install instructions](https://docs.docker.com/compose/install/). +**Table of Contents** + {{< toc >}} ## Basics @@ -61,7 +63,7 @@ services: - "222:22" ``` -## Custom port +## Ports To bind the integrated openSSH daemon and the webserver on a different port, adjust the port section. It's common to just change the host port and keep the ports within @@ -95,7 +97,9 @@ services: + - "2221:22" ``` -## MySQL database +## Databases + +### MySQL database To start Gitea in combination with a MySQL database, apply these changes to the `docker-compose.yml` file created above. @@ -146,7 +150,7 @@ services: + - ./mysql:/var/lib/mysql ``` -## PostgreSQL database +### PostgreSQL database To start Gitea in combination with a PostgreSQL database, apply these changes to the `docker-compose.yml` file created above. @@ -233,7 +237,7 @@ services: MySQL or PostgreSQL containers will need to be created separately. -## Start +## Startup To start this setup based on `docker-compose`, execute `docker-compose up -d`, to launch Gitea in the background. Using `docker-compose ps` will show if Gitea @@ -245,42 +249,42 @@ and kill the containers. The volumes will still exist. Notice: if using a non-3000 port on http, change app.ini to match `LOCAL_ROOT_URL = http://localhost:3000/`. -## Install +## Installation After starting the Docker setup via `docker-compose`, Gitea should be available using a favorite browser to finalize the installation. Visit http://server-ip:3000 and follow the installation wizard. If the database was started with the `docker-compose` setup as documented above, please note that `db` must be used as the database hostname. -## Environments variables +## Environment variables You can configure some of Gitea's settings via environment variables: (Default values are provided in **bold**) -* `APP_NAME`: **"Gitea: Git with a cup of tea"**: Application name, used in the page title. -* `RUN_MODE`: **prod**: Application run mode, affects performance and debugging. Either "dev", "prod" or "test". -* `DOMAIN`: **localhost**: Domain name of this server, used for the displayed http clone URL in Gitea's UI. -* `SSH_DOMAIN`: **localhost**: Domain name of this server, used for the displayed ssh clone URL in Gitea's UI. If the install page is enabled, SSH Domain Server takes DOMAIN value in the form (which overwrite this setting on save). -* `SSH_PORT`: **22**: SSH port displayed in clone URL. -* `SSH_LISTEN_PORT`: **%(SSH\_PORT)s**: Port for the built-in SSH server. -* `DISABLE_SSH`: **false**: Disable SSH feature when it's not available. If you want to disable SSH feature, you should set SSH port to `0` when installing Gitea. -* `HTTP_PORT`: **3000**: HTTP listen port. -* `ROOT_URL`: **""**: Overwrite the automatically generated public URL. This is useful if the internal and the external URL don't match (e.g. in Docker). -* `LFS_START_SERVER`: **false**: Enables git-lfs support. -* `DB_TYPE`: **sqlite3**: The database type in use \[mysql, postgres, mssql, sqlite3\]. -* `DB_HOST`: **localhost:3306**: Database host address and port. -* `DB_NAME`: **gitea**: Database name. -* `DB_USER`: **root**: Database username. -* `DB_PASSWD`: **"\"**: Database user password. Use \`your password\` for quoting if you use special characters in the password. -* `INSTALL_LOCK`: **false**: Disallow access to the install page. -* `SECRET_KEY`: **""**: Global secret key. This should be changed. If this has a value and `INSTALL_LOCK` is empty, `INSTALL_LOCK` will automatically set to `true`. -* `DISABLE_REGISTRATION`: **false**: Disable registration, after which only admin can create accounts for users. -* `REQUIRE_SIGNIN_VIEW`: **false**: Enable this to force users to log in to view any page. -* `USER_UID`: **1000**: The UID (Unix user ID) of the user that runs Gitea within the container. Match this to the UID of the owner of the `/data` volume if using host volumes (this is not necessary with named volumes). -* `USER_GID`: **1000**: The GID (Unix group ID) of the user that runs Gitea within the container. Match this to the GID of the owner of the `/data` volume if using host volumes (this is not necessary with named volumes). - -# Customization +- `APP_NAME`: **"Gitea: Git with a cup of tea"**: Application name, used in the page title. +- `RUN_MODE`: **prod**: Application run mode, affects performance and debugging. Either "dev", "prod" or "test". +- `DOMAIN`: **localhost**: Domain name of this server, used for the displayed http clone URL in Gitea's UI. +- `SSH_DOMAIN`: **localhost**: Domain name of this server, used for the displayed ssh clone URL in Gitea's UI. If the install page is enabled, SSH Domain Server takes DOMAIN value in the form (which overwrite this setting on save). +- `SSH_PORT`: **22**: SSH port displayed in clone URL. +- `SSH_LISTEN_PORT`: **%(SSH_PORT)s**: Port for the built-in SSH server. +- `DISABLE_SSH`: **false**: Disable SSH feature when it's not available. If you want to disable SSH feature, you should set SSH port to `0` when installing Gitea. +- `HTTP_PORT`: **3000**: HTTP listen port. +- `ROOT_URL`: **""**: Overwrite the automatically generated public URL. This is useful if the internal and the external URL don't match (e.g. in Docker). +- `LFS_START_SERVER`: **false**: Enables git-lfs support. +- `DB_TYPE`: **sqlite3**: The database type in use \[mysql, postgres, mssql, sqlite3\]. +- `DB_HOST`: **localhost:3306**: Database host address and port. +- `DB_NAME`: **gitea**: Database name. +- `DB_USER`: **root**: Database username. +- `DB_PASSWD`: **"\"**: Database user password. Use \`your password\` for quoting if you use special characters in the password. +- `INSTALL_LOCK`: **false**: Disallow access to the install page. +- `SECRET_KEY`: **""**: Global secret key. This should be changed. If this has a value and `INSTALL_LOCK` is empty, `INSTALL_LOCK` will automatically set to `true`. +- `DISABLE_REGISTRATION`: **false**: Disable registration, after which only admin can create accounts for users. +- `REQUIRE_SIGNIN_VIEW`: **false**: Enable this to force users to log in to view any page. +- `USER_UID`: **1000**: The UID (Unix user ID) of the user that runs Gitea within the container. Match this to the UID of the owner of the `/data` volume if using host volumes (this is not necessary with named volumes). +- `USER_GID`: **1000**: The GID (Unix group ID) of the user that runs Gitea within the container. Match this to the GID of the owner of the `/data` volume if using host volumes (this is not necessary with named volumes). + +## Customization Customization files described [here](https://docs.gitea.io/en-us/customizing-gitea/) should be placed in `/data/gitea` directory. If using host volumes, it's quite easy to access these @@ -288,7 +292,7 @@ files; for named volumes, this is done through another container or by direct ac `/var/lib/docker/volumes/gitea_gitea/_data`. The configuration file will be saved at `/data/gitea/conf/app.ini` after the installation. -# Upgrading +## Upgrading :exclamation::exclamation: **Make sure you have volumed data to somewhere outside Docker container** :exclamation::exclamation: @@ -302,7 +306,7 @@ docker-compose pull docker-compose up -d ``` -# SSH Container Passthrough +## SSH Container Passthrough Since SSH is running inside the container, SSH needs to be passed through from the host to the container if SSH support is desired. One option would be to run the container SSH on a non-standard port (or moving the host port to a non-standard port). Another option which might be more straightforward is to forward SSH connections from the host to the container. This setup is explained in the following. diff --git a/docs/content/doc/installation/with-docker.fr-fr.md b/docs/content/doc/installation/with-docker.fr-fr.md index 418615e98..0011ba2ff 100644 --- a/docs/content/doc/installation/with-docker.fr-fr.md +++ b/docs/content/doc/installation/with-docker.fr-fr.md @@ -3,7 +3,7 @@ date: "2017-08-23T09:00:00+02:00" title: "Installation avec Docker" slug: "install-with-docker" weight: 10 -toc: true +toc: false draft: false menu: sidebar: diff --git a/docs/content/doc/installation/with-docker.zh-cn.md b/docs/content/doc/installation/with-docker.zh-cn.md index 7fe6132fb..af9b0d451 100644 --- a/docs/content/doc/installation/with-docker.zh-cn.md +++ b/docs/content/doc/installation/with-docker.zh-cn.md @@ -3,7 +3,7 @@ date: "2016-12-01T16:00:00+02:00" title: "从Docker安装" slug: "install-with-docker" weight: 10 -toc: true +toc: false draft: false menu: sidebar: diff --git a/docs/content/doc/installation/with-docker.zh-tw.md b/docs/content/doc/installation/with-docker.zh-tw.md index b4c95c1ba..0fd862614 100644 --- a/docs/content/doc/installation/with-docker.zh-tw.md +++ b/docs/content/doc/installation/with-docker.zh-tw.md @@ -3,7 +3,7 @@ date: "2016-12-01T16:00:00+02:00" title: "Docker 安裝" slug: "install-with-docker" weight: 10 -toc: true +toc: false draft: false menu: sidebar: diff --git a/docs/content/doc/upgrade/from-gogs.en-us.md b/docs/content/doc/upgrade/from-gogs.en-us.md index fbcf58d6a..794ab3e87 100644 --- a/docs/content/doc/upgrade/from-gogs.en-us.md +++ b/docs/content/doc/upgrade/from-gogs.en-us.md @@ -3,7 +3,7 @@ date: "2016-12-01T16:00:00+02:00" title: "Upgrade from Gogs" slug: "upgrade-from-gogs" weight: 10 -toc: true +toc: false draft: false menu: sidebar: @@ -15,6 +15,10 @@ menu: # Upgrade from Gogs +**Table of Contents** + +{{< toc >}} + Gogs, version 0.9.146 and older, can be easily migrated to Gitea. There are some basic steps to follow. On a Linux system run as the Gogs user: diff --git a/docs/content/doc/upgrade/from-gogs.fr-fr.md b/docs/content/doc/upgrade/from-gogs.fr-fr.md index f7dfbc612..98a8edc1a 100644 --- a/docs/content/doc/upgrade/from-gogs.fr-fr.md +++ b/docs/content/doc/upgrade/from-gogs.fr-fr.md @@ -3,7 +3,7 @@ date: "2017-08-23T09:00:00+02:00" title: "Mise à jour depuis Gogs" slug: "upgrade-from-gogs" weight: 10 -toc: true +toc: false draft: false menu: sidebar: diff --git a/docs/content/doc/upgrade/from-gogs.zh-cn.md b/docs/content/doc/upgrade/from-gogs.zh-cn.md index 39d81587f..7d391ae82 100644 --- a/docs/content/doc/upgrade/from-gogs.zh-cn.md +++ b/docs/content/doc/upgrade/from-gogs.zh-cn.md @@ -3,7 +3,7 @@ date: "2016-12-01T16:00:00+02:00" title: "从 Gogs 升级" slug: "upgrade-from-gogs" weight: 10 -toc: true +toc: false draft: false menu: sidebar: diff --git a/docs/content/doc/upgrade/from-gogs.zh-tw.md b/docs/content/doc/upgrade/from-gogs.zh-tw.md index c3d847070..1440fff54 100644 --- a/docs/content/doc/upgrade/from-gogs.zh-tw.md +++ b/docs/content/doc/upgrade/from-gogs.zh-tw.md @@ -3,7 +3,7 @@ date: "2016-12-01T16:00:00+02:00" title: "從 Gogs 升級" slug: "upgrade-from-gogs" weight: 10 -toc: true +toc: false draft: false menu: sidebar: diff --git a/docs/content/doc/usage/backup-and-restore.en-us.md b/docs/content/doc/usage/backup-and-restore.en-us.md index cefdf5d3d..5e822dc05 100644 --- a/docs/content/doc/usage/backup-and-restore.en-us.md +++ b/docs/content/doc/usage/backup-and-restore.en-us.md @@ -3,7 +3,7 @@ date: "2017-01-01T16:00:00+02:00" title: "Usage: Backup and Restore" slug: "backup-and-restore" weight: 11 -toc: true +toc: false draft: false menu: sidebar: @@ -18,6 +18,10 @@ menu: Gitea currently has a `dump` command that will save the installation to a zip file. This file can be unpacked and used to restore an instance. +**Table of Contents** + +{{< toc >}} + ## Backup Command (`dump`) Switch to the user running Gitea: `su git`. Run `./gitea dump -c /path/to/app.ini` in the Gitea installation @@ -34,12 +38,12 @@ 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 -* `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. -* `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. +- `app.ini` - Optional copy of configuration file if originally stored outside of 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. +- `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. Intermediate backup files are created in a temporary directory specified either with the `--tempdir` command-line parameter or the `TMPDIR` environment variable. @@ -56,7 +60,7 @@ Example: docker exec -u -it -w <--tempdir> $(docker ps -qf "name=") bash -c '/app/gitea/gitea dump -c ' ``` -*Note: `--tempdir` refers to the temporary directory of the docker environment used by Gitea; if you have not specified a custom `--tempdir`, then Gitea uses `/tmp` or the `TMPDIR` environment variable of the docker container. For `--tempdir` adjust your `docker exec` command options accordingly. +\*Note: `--tempdir` refers to the temporary directory of the docker environment used by Gitea; if you have not specified a custom `--tempdir`, then Gitea uses `/tmp` or the `TMPDIR` environment variable of the docker container. For `--tempdir` adjust your `docker exec` command options accordingly. The result should be a file, stored in the `--tempdir` specified, along the lines of: `gitea-dump-1482906742.zip` @@ -67,7 +71,7 @@ involves moving files to their correct locations and restoring a database dump. Example: -```none +```sh apt-get install gitea unzip gitea-dump-1482906742.zip cd gitea-dump-1482906742 diff --git a/docs/content/doc/usage/backup-and-restore.zh-cn.md b/docs/content/doc/usage/backup-and-restore.zh-cn.md index 84938967f..c3baae25e 100644 --- a/docs/content/doc/usage/backup-and-restore.zh-cn.md +++ b/docs/content/doc/usage/backup-and-restore.zh-cn.md @@ -3,7 +3,7 @@ date: "2018-06-06T09:33:00+08:00" title: "使用：备份与恢复" slug: "backup-and-restore" weight: 11 -toc: true +toc: false draft: false menu: sidebar: diff --git a/docs/content/doc/usage/backup-and-restore.zh-tw.md b/docs/content/doc/usage/backup-and-restore.zh-tw.md index 6f5485881..0dfdeede7 100644 --- a/docs/content/doc/usage/backup-and-restore.zh-tw.md +++ b/docs/content/doc/usage/backup-and-restore.zh-tw.md @@ -3,7 +3,7 @@ date: "2017-01-01T16:00:00+02:00" title: "用法: 備份與還原" slug: "backup-and-restore" weight: 11 -toc: true +toc: false draft: false menu: sidebar: diff --git a/docs/content/doc/usage/command-line.en-us.md b/docs/content/doc/usage/command-line.en-us.md index 0867b3d16..adaf3ea0d 100644 --- a/docs/content/doc/usage/command-line.en-us.md +++ b/docs/content/doc/usage/command-line.en-us.md @@ -3,7 +3,7 @@ date: "2017-01-01T16:00:00+02:00" title: "Usage: Command Line" slug: "command-line" weight: 10 -toc: true +toc: false draft: false menu: sidebar: @@ -15,6 +15,8 @@ menu: # Command Line +**Table of Contents** + {{< toc >}} ## Usage @@ -41,195 +43,183 @@ changed at build time (if preferred). Starts the server: - Options: - - `--port number`, `-p number`: Port number. Optional. (default: 3000). Overrides configuration file. - - `--install-port number`: Port number to run the install page on. Optional. (default: 3000). Overrides configuration file. - - `--pid path`, `-P path`: Pidfile path. Optional. + - `--port number`, `-p number`: Port number. Optional. (default: 3000). Overrides configuration file. + - `--install-port number`: Port number to run the install page on. Optional. (default: 3000). Overrides configuration file. + - `--pid path`, `-P path`: Pidfile path. Optional. - Examples: - - `gitea web` - - `gitea web --port 80` - - `gitea web --config /etc/gitea.ini --pid /some/custom/gitea.pid` + - `gitea web` + - `gitea web --port 80` + - `gitea web --config /etc/gitea.ini --pid /some/custom/gitea.pid` - Notes: - - Gitea should not be run as root. To bind to a port below 1024, 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. + - Gitea should not be run as root. To bind to a port below 1024, 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: - - `user`: - - `list`: - - Options: - - `--admin`: List only admin users. Optional. - - Description: lists all users that exist - - Examples: - - `gitea admin user list` - - `delete`: - - Options: - - `--id`: ID of user to be deleted. Required. - - Examples: - - `gitea admin user delete --id 1` - - `create`: - - Options: - - `--name value`: Username. Required. As of gitea 1.9.0, use the `--username` flag instead. - - `--username value`: Username. Required. New in gitea 1.9.0. - - `--password value`: Password. Required. - - `--email value`: Email. Required. - - `--admin`: If provided, this makes the user an admin. Optional. - - `--access-token`: If provided, an access token will be created for the user. Optional. (default: false). - - `--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 user create --username myname --password asecurepassword --email me@example.com` - - `change-password`: - - Options: - - `--username value`, `-u value`: Username. Required. - - `--password value`, `-p value`: New password. Required. - - Examples: - - `gitea admin user 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 - - Examples: - - `gitea admin auth list` - - `delete`: - - Options: - - `--id`: ID of source to be deleted. Required. - - Examples: - - `gitea admin auth delete --id 1` - - `add-oauth`: - - Options: - - `--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. - - `--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` - - `add-ldap`: Add new LDAP (via Bind DN) authentication source - - Options: - - `--name value`: Authentication name. Required. - - `--not-active`: Deactivate the authentication source. - - `--security-protocol value`: Security protocol name. Required. - - `--skip-tls-verify`: Disable TLS verification. - - `--host value`: The address where the LDAP server can be reached. Required. - - `--port value`: The port to use when connecting to the LDAP server. Required. - - `--user-search-base value`: The LDAP base at which user accounts will be searched for. Required. - - `--user-filter value`: An LDAP filter declaring how to find the user record that is attempting to authenticate. Required. - - `--admin-filter value`: An LDAP filter specifying if a user should be given administrator privileges. - - `--restricted-filter value`: An LDAP filter specifying if a user should be given restricted status. - - `--username-attribute value`: The attribute of the user’s LDAP record containing the user name. - - `--firstname-attribute value`: The attribute of the user’s LDAP record containing the user’s first name. - - `--surname-attribute value`: The attribute of the user’s LDAP record containing the user’s surname. - - `--email-attribute value`: The attribute of the user’s LDAP record containing the user’s email address. Required. - - `--public-ssh-key-attribute value`: The attribute of the user’s LDAP record containing the user’s public ssh key. - - `--bind-dn value`: The DN to bind to the LDAP server with when searching for the user. - - `--bind-password value`: The password for the Bind DN, if any. - - `--attributes-in-bind`: Fetch attributes in bind DN context. - - `--synchronize-users`: Enable user synchronization. - - `--page-size value`: Search page size. - - Examples: - - `gitea admin auth add-ldap --name ldap --security-protocol unencrypted --host mydomain.org --port 389 --user-search-base "ou=Users,dc=mydomain,dc=org" --user-filter "(&(objectClass=posixAccount)(uid=%s))" --email-attribute mail` - - `update-ldap`: Update existing LDAP (via Bind DN) authentication source - - Options: - - `--id value`: ID of authentication source. Required. - - `--name value`: Authentication name. - - `--not-active`: Deactivate the authentication source. - - `--security-protocol value`: Security protocol name. - - `--skip-tls-verify`: Disable TLS verification. - - `--host value`: The address where the LDAP server can be reached. - - `--port value`: The port to use when connecting to the LDAP server. - - `--user-search-base value`: The LDAP base at which user accounts will be searched for. - - `--user-filter value`: An LDAP filter declaring how to find the user record that is attempting to authenticate. - - `--admin-filter value`: An LDAP filter specifying if a user should be given administrator privileges. - - `--restricted-filter value`: An LDAP filter specifying if a user should be given restricted status. - - `--username-attribute value`: The attribute of the user’s LDAP record containing the user name. - - `--firstname-attribute value`: The attribute of the user’s LDAP record containing the user’s first name. - - `--surname-attribute value`: The attribute of the user’s LDAP record containing the user’s surname. - - `--email-attribute value`: The attribute of the user’s LDAP record containing the user’s email address. - - `--public-ssh-key-attribute value`: The attribute of the user’s LDAP record containing the user’s public ssh key. - - `--bind-dn value`: The DN to bind to the LDAP server with when searching for the user. - - `--bind-password value`: The password for the Bind DN, if any. - - `--attributes-in-bind`: Fetch attributes in bind DN context. - - `--synchronize-users`: Enable user synchronization. - - `--page-size value`: Search page size. - - Examples: - - `gitea admin auth update-ldap --id 1 --name "my ldap auth source"` - - `gitea admin auth update-ldap --id 1 --username-attribute uid --firstname-attribute givenName --surname-attribute sn` - - `add-ldap-simple`: Add new LDAP (simple auth) authentication source - - Options: - - `--name value`: Authentication name. Required. - - `--not-active`: Deactivate the authentication source. - - `--security-protocol value`: Security protocol name. Required. - - `--skip-tls-verify`: Disable TLS verification. - - `--host value`: The address where the LDAP server can be reached. Required. - - `--port value`: The port to use when connecting to the LDAP server. Required. - - `--user-search-base value`: The LDAP base at which user accounts will be searched for. - - `--user-filter value`: An LDAP filter declaring how to find the user record that is attempting to authenticate. Required. - - `--admin-filter value`: An LDAP filter specifying if a user should be given administrator privileges. - - `--restricted-filter value`: An LDAP filter specifying if a user should be given restricted status. - - `--username-attribute value`: The attribute of the user’s LDAP record containing the user name. - - `--firstname-attribute value`: The attribute of the user’s LDAP record containing the user’s first name. - - `--surname-attribute value`: The attribute of the user’s LDAP record containing the user’s surname. - - `--email-attribute value`: The attribute of the user’s LDAP record containing the user’s email address. Required. - - `--public-ssh-key-attribute value`: The attribute of the user’s LDAP record containing the user’s public ssh key. - - `--user-dn value`: The user’s DN. Required. - - Examples: - - `gitea admin auth add-ldap-simple --name ldap --security-protocol unencrypted --host mydomain.org --port 389 --user-dn "cn=%s,ou=Users,dc=mydomain,dc=org" --user-filter "(&(objectClass=posixAccount)(cn=%s))" --email-attribute mail` - - `update-ldap-simple`: Update existing LDAP (simple auth) authentication source - - Options: - - `--id value`: ID of authentication source. Required. - - `--name value`: Authentication name. - - `--not-active`: Deactivate the authentication source. - - `--security-protocol value`: Security protocol name. - - `--skip-tls-verify`: Disable TLS verification. - - `--host value`: The address where the LDAP server can be reached. - - `--port value`: The port to use when connecting to the LDAP server. - - `--user-search-base value`: The LDAP base at which user accounts will be searched for. - - `--user-filter value`: An LDAP filter declaring how to find the user record that is attempting to authenticate. - - `--admin-filter value`: An LDAP filter specifying if a user should be given administrator privileges. - - `--restricted-filter value`: An LDAP filter specifying if a user should be given restricted status. - - `--username-attribute value`: The attribute of the user’s LDAP record containing the user name. - - `--firstname-attribute value`: The attribute of the user’s LDAP record containing the user’s first name. - - `--surname-attribute value`: The attribute of the user’s LDAP record containing the user’s surname. - - `--email-attribute value`: The attribute of the user’s LDAP record containing the user’s email address. - - `--public-ssh-key-attribute value`: The attribute of the user’s LDAP record containing the user’s public ssh key. - - `--user-dn value`: The user’s DN. - - Examples: - - `gitea admin auth update-ldap-simple --id 1 --name "my ldap auth source"` - - `gitea admin auth update-ldap-simple --id 1 --username-attribute uid --firstname-attribute givenName --surname-attribute sn` + - `user`: + - `list`: + - Options: + - `--admin`: List only admin users. Optional. + - Description: lists all users that exist + - Examples: + - `gitea admin user list` + - `delete`: + - Options: + - `--id`: ID of user to be deleted. Required. + - Examples: + - `gitea admin user delete --id 1` + - `create`: - Options: - `--name value`: Username. Required. As of gitea 1.9.0, use the `--username` flag instead. - `--username value`: Username. Required. New in gitea 1.9.0. - `--password value`: Password. Required. - `--email value`: Email. Required. - `--admin`: If provided, this makes the user an admin. Optional. - `--access-token`: If provided, an access token will be created for the user. Optional. (default: false). - `--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 user create --username myname --password asecurepassword --email me@example.com` + - `change-password`: + - Options: + - `--username value`, `-u value`: Username. Required. + - `--password value`, `-p value`: New password. Required. + - Examples: + - `gitea admin user 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 + - Examples: + - `gitea admin auth list` + - `delete`: + - Options: + - `--id`: ID of source to be deleted. Required. + - Examples: + - `gitea admin auth delete --id 1` + - `add-oauth`: + - Options: + - `--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. + - `--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` + - `add-ldap`: Add new LDAP (via Bind DN) authentication source + - Options: + - `--name value`: Authentication name. Required. + - `--not-active`: Deactivate the authentication source. + - `--security-protocol value`: Security protocol name. Required. + - `--skip-tls-verify`: Disable TLS verification. + - `--host value`: The address where the LDAP server can be reached. Required. + - `--port value`: The port to use when connecting to the LDAP server. Required. + - `--user-search-base value`: The LDAP base at which user accounts will be searched for. Required. + - `--user-filter value`: An LDAP filter declaring how to find the user record that is attempting to authenticate. Required. + - `--admin-filter value`: An LDAP filter specifying if a user should be given administrator privileges. + - `--restricted-filter value`: An LDAP filter specifying if a user should be given restricted status. + - `--username-attribute value`: The attribute of the user’s LDAP record containing the user name. + - `--firstname-attribute value`: The attribute of the user’s LDAP record containing the user’s first name. + - `--surname-attribute value`: The attribute of the user’s LDAP record containing the user’s surname. + - `--email-attribute value`: The attribute of the user’s LDAP record containing the user’s email address. Required. + - `--public-ssh-key-attribute value`: The attribute of the user’s LDAP record containing the user’s public ssh key. + - `--bind-dn value`: The DN to bind to the LDAP server with when searching for the user. + - `--bind-password value`: The password for the Bind DN, if any. + - `--attributes-in-bind`: Fetch attributes in bind DN context. + - `--synchronize-users`: Enable user synchronization. + - `--page-size value`: Search page size. + - Examples: + - `gitea admin auth add-ldap --name ldap --security-protocol unencrypted --host mydomain.org --port 389 --user-search-base "ou=Users,dc=mydomain,dc=org" --user-filter "(&(objectClass=posixAccount)(uid=%s))" --email-attribute mail` + - `update-ldap`: Update existing LDAP (via Bind DN) authentication source + - Options: + - `--id value`: ID of authentication source. Required. + - `--name value`: Authentication name. + - `--not-active`: Deactivate the authentication source. + - `--security-protocol value`: Security protocol name. + - `--skip-tls-verify`: Disable TLS verification. + - `--host value`: The address where the LDAP server can be reached. + - `--port value`: The port to use when connecting to the LDAP server. + - `--user-search-base value`: The LDAP base at which user accounts will be searched for. + - `--user-filter value`: An LDAP filter declaring how to find the user record that is attempting to authenticate. + - `--admin-filter value`: An LDAP filter specifying if a user should be given administrator privileges. + - `--restricted-filter value`: An LDAP filter specifying if a user should be given restricted status. + - `--username-attribute value`: The attribute of the user’s LDAP record containing the user name. + - `--firstname-attribute value`: The attribute of the user’s LDAP record containing the user’s first name. + - `--surname-attribute value`: The attribute of the user’s LDAP record containing the user’s surname. + - `--email-attribute value`: The attribute of the user’s LDAP record containing the user’s email address. + - `--public-ssh-key-attribute value`: The attribute of the user’s LDAP record containing the user’s public ssh key. + - `--bind-dn value`: The DN to bind to the LDAP server with when searching for the user. + - `--bind-password value`: The password for the Bind DN, if any. + - `--attributes-in-bind`: Fetch attributes in bind DN context. + - `--synchronize-users`: Enable user synchronization. + - `--page-size value`: Search page size. + - Examples: + - `gitea admin auth update-ldap --id 1 --name "my ldap auth source"` + - `gitea admin auth update-ldap --id 1 --username-attribute uid --firstname-attribute givenName --surname-attribute sn` + - `add-ldap-simple`: Add new LDAP (simple auth) authentication source + - Options: + - `--name value`: Authentication name. Required. + - `--not-active`: Deactivate the authentication source. + - `--security-protocol value`: Security protocol name. Required. + - `--skip-tls-verify`: Disable TLS verification. + - `--host value`: The address where the LDAP server can be reached. Required. + - `--port value`: The port to use when connecting to the LDAP server. Required. + - `--user-search-base value`: The LDAP base at which user accounts will be searched for. + - `--user-filter value`: An LDAP filter declaring how to find the user record that is attempting to authenticate. Required. + - `--admin-filter value`: An LDAP filter specifying if a user should be given administrator privileges. + - `--restricted-filter value`: An LDAP filter specifying if a user should be given restricted status. + - `--username-attribute value`: The attribute of the user’s LDAP record containing the user name. + - `--firstname-attribute value`: The attribute of the user’s LDAP record containing the user’s first name. + - `--surname-attribute value`: The attribute of the user’s LDAP record containing the user’s surname. + - `--email-attribute value`: The attribute of the user’s LDAP record containing the user’s email address. Required. + - `--public-ssh-key-attribute value`: The attribute of the user’s LDAP record containing the user’s public ssh key. + - `--user-dn value`: The user’s DN. Required. + - Examples: + - `gitea admin auth add-ldap-simple --name ldap --security-protocol unencrypted --host mydomain.org --port 389 --user-dn "cn=%s,ou=Users,dc=mydomain,dc=org" --user-filter "(&(objectClass=posixAccount)(cn=%s))" --email-attribute mail` + - `update-ldap-simple`: Update existing LDAP (simple auth) authentication source + - Options: + - `--id value`: ID of authentication source. Required. + - `--name value`: Authentication name. + - `--not-active`: Deactivate the authentication source. + - `--security-protocol value`: Security protocol name. + - `--skip-tls-verify`: Disable TLS verification. + - `--host value`: The address where the LDAP server can be reached. + - `--port value`: The port to use when connecting to the LDAP server. + - `--user-search-base value`: The LDAP base at which user accounts will be searched for. + - `--user-filter value`: An LDAP filter declaring how to find the user record that is attempting to authenticate. + - `--admin-filter value`: An LDAP filter specifying if a user should be given administrator privileges. + - `--restricted-filter value`: An LDAP filter specifying if a user should be given restricted status. + - `--username-attribute value`: The attribute of the user’s LDAP record containing the user name. + - `--firstname-attribute value`: The attribute of the user’s LDAP record containing the user’s first name. + - `--surname-attribute value`: The attribute of the user’s LDAP record containing the user’s surname. + - `--email-attribute value`: The attribute of the user’s LDAP record containing the user’s email address. + - `--public-ssh-key-attribute value`: The attribute of the user’s LDAP record containing the user’s public ssh key. + - `--user-dn value`: The user’s DN. + - Examples: + - `gitea admin auth update-ldap-simple --id 1 --name "my ldap auth source"` + - `gitea admin auth update-ldap-simple --id 1 --username-attribute uid --firstname-attribute givenName --surname-attribute sn` ### cert @@ -237,17 +227,17 @@ Generates a self-signed SSL certificate. Outputs to `cert.pem` and `key.pem` in 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. + - `--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` + - `gitea cert --host git.example.com,example.com,www.example.com --ca` ### dump @@ -255,14 +245,14 @@ Dumps all files and databases into a zip file. Outputs into a file like `gitea-d in the current directory. - Options: - - `--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. + - `--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` + - `gitea dump` + - `gitea dump --verbose` ### generate @@ -270,15 +260,15 @@ Generates random values and tokens for usage in configuration file. Useful for g for automatic deployments. - Commands: - - `secret`: - - Options: - - `INTERNAL_TOKEN`: Token used for an internal API call authentication. - - `JWT_SECRET`: LFS & OAUTH2 JWT authentication secret (LFS_JWT_SECRET is aliased to this option for backwards compatibility). - - `SECRET_KEY`: Global secret key. - - Examples: - - `gitea generate secret INTERNAL_TOKEN` - - `gitea generate secret JWT_SECRET` - - `gitea generate secret SECRET_KEY` + - `secret`: + - Options: + - `INTERNAL_TOKEN`: Token used for an internal API call authentication. + - `JWT_SECRET`: LFS & OAUTH2 JWT authentication secret (LFS_JWT_SECRET is aliased to this option for backwards compatibility). + - `SECRET_KEY`: Global secret key. + - Examples: + - `gitea generate secret INTERNAL_TOKEN` + - `gitea generate secret JWT_SECRET` + - `gitea generate secret SECRET_KEY` ### keys @@ -303,21 +293,24 @@ path. NB: Gitea must be running for this command to succeed. ### migrate + Migrates the database. This command can be used to run other commands before starting the server for the first time. This command is idempotent. ### convert + Converts an existing MySQL database from utf8 to utf8mb4. ### doctor + Diagnose the problems of current gitea instance according the given configuration. Currently there are a check list below: - Check if OpenSSH authorized_keys file id correct -When your gitea instance support OpenSSH, your gitea instance binary path will be written to `authorized_keys` -when there is any public key added or changed on your gitea instance. -Sometimes if you moved or renamed your gitea binary when upgrade and you haven't run `Update the '.ssh/authorized_keys' file with Gitea SSH keys. (Not needed for the built-in SSH server.)` on your Admin Panel. Then all pull/push via SSH will not be work. -This check will help you to check if it works well. + When your gitea instance support OpenSSH, your gitea instance binary path will be written to `authorized_keys` + when there is any public key added or changed on your gitea instance. + Sometimes if you moved or renamed your gitea binary when upgrade and you haven't run `Update the '.ssh/authorized_keys' file with Gitea SSH keys. (Not needed for the built-in SSH server.)` on your Admin Panel. Then all pull/push via SSH will not be work. + This check will help you to check if it works well. For contributors, if you want to add more checks, you can wrie ad new function like `func(ctx *cli.Context) ([]string, error)` and append it to `doctor.go`. @@ -369,24 +362,24 @@ It is highly recommended to back-up your database before running these commands. Manage running server operations: - Commands: - - `shutdown`: Gracefully shutdown the running process - - `restart`: Gracefully restart the running process - (not implemented for windows servers) - - `flush-queues`: Flush queues in the running process + - `shutdown`: Gracefully shutdown the running process + - `restart`: Gracefully restart the running process - (not implemented for windows servers) + - `flush-queues`: Flush queues in the running process - Options: - `--timeout value`: Timeout for the flushing process (default: 1m0s) - `--non-blocking`: Set to true to not wait for flush to complete before returning - - `logging`: Adjust logging commands + - `logging`: Adjust logging commands - Commands: - - `pause`: Pause logging + - `pause`: Pause logging - Notes: - The logging level will be raised to INFO temporarily if it is below this level. - Gitea will buffer logs up to a certain point and will drop them after that point. - - `resume`: Resume logging + - `resume`: Resume logging - `release-and-reopen`: Cause Gitea to release and re-open files and connections used for logging (Equivalent to sending SIGUSR1 to Gitea.) - `remove name`: Remove the named logger - Options: - `--group group`, `-g group`: Set the group to remove the sublogger from. (defaults to `default`) - - `add`: Add a logger + - `add`: Add a logger - Commands: - `console`: Add a console logger - Options: @@ -402,7 +395,7 @@ Manage running server operations: - `file`: Add a file logger - Options: - `--group value`, `-g value`: Group to add logger to - will default to "default" - - `--name value`, `-n value`: Name of the new logger - will default to mode + - `--name value`, `-n value`: Name of the new logger - will default to mode - `--level value`, `-l value`: Logging level for the new logger - `--stacktrace-level value`, `-L value`: Stacktrace logging level - `--flags value`, `-F value`: Flags for the logger @@ -419,7 +412,7 @@ Manage running server operations: - `conn`: Add a network connection logger - Options: - `--group value`, `-g value`: Group to add logger to - will default to "default" - - `--name value`, `-n value`: Name of the new logger - will default to mode + - `--name value`, `-n value`: Name of the new logger - will default to mode - `--level value`, `-l value`: Logging level for the new logger - `--stacktrace-level value`, `-L value`: Stacktrace logging level - `--flags value`, `-F value`: Flags for the logger diff --git a/docs/content/doc/usage/email-setup.en-us.md b/docs/content/doc/usage/email-setup.en-us.md index 9cb3a9e78..54ccfbf82 100644 --- a/docs/content/doc/usage/email-setup.en-us.md +++ b/docs/content/doc/usage/email-setup.en-us.md @@ -3,7 +3,7 @@ date: "2019-10-15T10:10:00+05:00" title: "Usage: Email setup" slug: "email-setup" weight: 12 -toc: true +toc: false draft: false menu: sidebar: @@ -15,11 +15,17 @@ menu: # Email setup +**Table of Contents** + +{{< toc >}} + To use Gitea's built-in Email support, update the `app.ini` config file [mailer] section: ## Sendmail version + Use the operating system’s sendmail command instead of SMTP. This is common on Linux servers. Note: For use in the official Gitea Docker image, please configure with the SMTP version. + ```ini [mailer] ENABLED = true @@ -29,6 +35,7 @@ SENDMAIL_PATH = /usr/sbin/sendmail ``` ## SMTP version + ```ini [mailer] ENABLED = true diff --git a/docs/content/doc/usage/fail2ban-setup.en-us.md b/docs/content/doc/usage/fail2ban-setup.en-us.md index 42b61416b..5c5bdb9a2 100644 --- a/docs/content/doc/usage/fail2ban-setup.en-us.md +++ b/docs/content/doc/usage/fail2ban-setup.en-us.md @@ -3,7 +3,7 @@ date: "2018-05-11T11:00:00+02:00" title: "Usage: Setup fail2ban" slug: "fail2ban-setup" weight: 16 -toc: true +toc: false draft: false menu: sidebar: diff --git a/docs/content/doc/usage/git-lfs-support.md b/docs/content/doc/usage/git-lfs-support.md index 7027ebf16..66e521761 100644 --- a/docs/content/doc/usage/git-lfs-support.md +++ b/docs/content/doc/usage/git-lfs-support.md @@ -3,7 +3,7 @@ date: "2019-10-06T08:00:00+05:00" title: "Usage: Git LFS setup" slug: "git-lfs-setup" weight: 12 -toc: true +toc: false draft: false menu: sidebar: diff --git a/docs/content/doc/usage/https-support.md b/docs/content/doc/usage/https-support.md index dfafa21c5..ebbfc165f 100644 --- a/docs/content/doc/usage/https-support.md +++ b/docs/content/doc/usage/https-support.md @@ -3,7 +3,7 @@ date: "2018-06-02T11:00:00+02:00" title: "Usage: HTTPS setup" slug: "https-setup" weight: 12 -toc: true +toc: false draft: false menu: sidebar: @@ -15,6 +15,10 @@ menu: # HTTPS setup to encrypt connections to Gitea +**Table of Contents** + +{{< toc >}} + ## Using the built-in server Before you enable HTTPS, make sure that you have valid SSL/TLS certificates. @@ -32,6 +36,7 @@ HTTP_PORT = 3000 CERT_FILE = cert.pem KEY_FILE = key.pem ``` + Note that if your certificate is signed by a third party certificate authority (i.e. not self-signed), then cert.pem should contain the certificate chain. The server certificate must be the first entry in cert.pem, followed by the intermediaries in order (if any). The root certificate does not have to be included because the connecting client must already have it in order to estalbish the trust relationship. To learn more about the config values, please checkout the [Config Cheat Sheet](../config-cheat-sheet#server). @@ -66,14 +71,14 @@ LETSENCRYPT_EMAIL=email@example.com To learn more about the config values, please checkout the [Config Cheat Sheet](../config-cheat-sheet#server). -## Using reverse proxy +## Using a reverse proxy Setup up your reverse proxy as shown in the [reverse proxy guide](../reverse-proxies). After that, enable HTTPS by following one of these guides: -* [nginx](https://nginx.org/en/docs/http/configuring_https_servers.html) -* [apache2/httpd](https://httpd.apache.org/docs/2.4/ssl/ssl_howto.html) -* [caddy](https://caddyserver.com/docs/tls) +- [nginx](https://nginx.org/en/docs/http/configuring_https_servers.html) +- [apache2/httpd](https://httpd.apache.org/docs/2.4/ssl/ssl_howto.html) +- [caddy](https://caddyserver.com/docs/tls) Note: Enabling HTTPS only at the proxy level is referred as [TLS Termination Proxy](https://en.wikipedia.org/wiki/TLS_termination_proxy). The proxy server accepts incoming TLS connections, decrypts the contents, and passes the now unencrypted contents to Gitea. This is normally fine as long as both the proxy and Gitea instances are either on the same machine, or on different machines within private network (with the proxy is exposed to outside network). If your Gitea instance is separated from your proxy over a public network, or if you want full end-to-end encryption, you can also [enable HTTPS support directly in Gitea using built-in server](#using-the-built-in-server) and forward the connections over HTTPS instead. diff --git a/docs/content/doc/usage/issue-pull-request-templates.en-us.md b/docs/content/doc/usage/issue-pull-request-templates.en-us.md index 0bc8f0eb7..44291635c 100644 --- a/docs/content/doc/usage/issue-pull-request-templates.en-us.md +++ b/docs/content/doc/usage/issue-pull-request-templates.en-us.md @@ -3,7 +3,7 @@ date: "2018-05-10T16:00:00+02:00" title: "Usage: Issue and Pull Request templates" slug: "issue-pull-request-templates" weight: 15 -toc: true +toc: false draft: false menu: sidebar: @@ -15,6 +15,10 @@ menu: # Issue and Pull Request Templates +**Table of Contents** + +{{< toc >}} + Some projects have a standard list of questions that users need to answer when creating an issue or pull request. Gitea supports adding templates to the main branch of the repository so that they can autopopulate the form when users are @@ -23,53 +27,55 @@ of getting some clarifying details. Possible file names for issue templates: -* ISSUE_TEMPLATE.md -* issue_template.md -* .gitea/ISSUE_TEMPLATE.md -* .gitea/issue_template.md -* .github/ISSUE_TEMPLATE.md -* .github/issue_template.md - +- `ISSUE_TEMPLATE.md` +- `issue_template.md` +- `.gitea/ISSUE_TEMPLATE.md` +- `.gitea/issue_template.md` +- `.github/ISSUE_TEMPLATE.md` +- `.github/issue_template.md` Possible file names for PR templates: -* PULL_REQUEST_TEMPLATE.md -* pull_request_template.md -* .gitea/PULL_REQUEST_TEMPLATE.md -* .gitea/pull_request_template.md -* .github/PULL_REQUEST_TEMPLATE.md -* .github/pull_request_template.md - +- `PULL_REQUEST_TEMPLATE.md` +- `pull_request_template.md` +- `.gitea/PULL_REQUEST_TEMPLATE.md` +- `.gitea/pull_request_template.md` +- `.github/PULL_REQUEST_TEMPLATE.md` +- `.github/pull_request_template.md` Additionally, the New Issue page URL can be suffixed with `?title=Issue+Title&body=Issue+Text` and the form will be populated with those strings. Those strings will be used instead of the template if there is one. -# Issue Template Directory +## Issue Template Directory Alternatively, users can create multiple issue templates inside a special directory and allow users to choose one that more specifically addresses their problem. Possible directory names for issue templates: -* ISSUE_TEMPLATE -* issue_template -* .gitea/ISSUE_TEMPLATE -* .gitea/issue_template -* .github/ISSUE_TEMPLATE -* .github/issue_template -* .gitlab/ISSUE_TEMPLATE -* .gitlab/issue_template +- `ISSUE_TEMPLATE` +- `issue_template` +- `.gitea/ISSUE_TEMPLATE` +- `.gitea/issue_template` +- `.github/ISSUE_TEMPLATE` +- `.github/issue_template` +- `.gitlab/ISSUE_TEMPLATE` +- `.gitlab/issue_template` Inside the directory can be multiple issue templates with the form -```markdown ------ +```md +--- + name: "Template Name" about: "This template is for testing!" title: "[TEST] " labels: - - bug - - "help needed" ------ + +- bug +- "help needed" + +--- + This is the template! ``` diff --git a/docs/content/doc/usage/issue-pull-request-templates.zh-cn.md b/docs/content/doc/usage/issue-pull-request-templates.zh-cn.md index ad02b351d..1d2539b7b 100644 --- a/docs/content/doc/usage/issue-pull-request-templates.zh-cn.md +++ b/docs/content/doc/usage/issue-pull-request-templates.zh-cn.md @@ -3,7 +3,7 @@ date: "2018-05-10T16:00:00+02:00" title: "使用：Issue 和 Pull Request 模板" slug: "issue-pull-request-templates" weight: 15 -toc: true +toc: false draft: false menu: sidebar: diff --git a/docs/content/doc/usage/linked-references.en-us.md b/docs/content/doc/usage/linked-references.en-us.md index 963d54fad..bb40acdcd 100644 --- a/docs/content/doc/usage/linked-references.en-us.md +++ b/docs/content/doc/usage/linked-references.en-us.md @@ -3,7 +3,7 @@ date: "2019-11-21T17:00:00-03:00" title: "Usage: Automatically Linked References" slug: "automatically-linked-references" weight: 15 -toc: true +toc: false draft: false menu: sidebar: @@ -15,6 +15,10 @@ menu: # Automatically Linked References in Issues, Pull Requests and Commit Messages +**Table of Contents** + +{{< toc >}} + When an issue, pull request or comment is posted, the text description is parsed in search for references. These references will be shown as links in the Issue View and, in some cases, produce certain _actions_. @@ -27,8 +31,6 @@ for them to be recognized. For example, they should not be included inside code text. They should also be reasonably cleared from their surrounding text (for example, using spaces). -{{< toc >}} - ## User, Team and Organization Mentions When a text in the form `@username` is found and `username` matches the name @@ -108,10 +110,10 @@ is merged. For an actionable reference to be accepted, _at least one_ of the following conditions must be met: -* The commenter has permissions to close or reopen the issue at the moment -of creating the reference. -* The reference is inside a commit message. -* The reference is posted as part of the pull request description. +- The commenter has permissions to close or reopen the issue at the moment + of creating the reference. +- The reference is inside a commit message. +- The reference is posted as part of the pull request description. In the last case, the issue will be closed or reopened only if the merger of the pull request has permissions to do so. @@ -121,8 +123,8 @@ and only issues can be closed or reopened this way. The default _keywords_ are: -* **Closing**: close, closes, closed, fix, fixes, fixed, resolve, resolves, resolved -* **Reopening**: reopen, reopens, reopened +- **Closing**: close, closes, closed, fix, fixes, fixed, resolve, resolves, resolved +- **Reopening**: reopen, reopens, reopened ## Time tracking in Pull Requests and Commit Messages @@ -135,11 +137,11 @@ multiple fixed issues and spent time for each of them. Supported time units (``): -* `m` - minutes -* `h` - hours -* `d` - days (equals to 8 hours) -* `w` - weeks (equals to 5 days) -* `mo` - months (equals to 4 weeks) +- `m` - minutes +- `h` - hours +- `d` - days (equals to 8 hours) +- `w` - weeks (equals to 5 days) +- `mo` - months (equals to 4 weeks) Numbers to specify time (``) can be also decimal numbers, ex. `@1.5h` would result in one and half hours. Multiple time units can be combined, ex. `@1h10m` would @@ -172,26 +174,26 @@ This table illustrates the different kinds of cross-reference for issues and pul In the examples, `User1/Repo1` refers to the repository where the reference is used, while `UserZ/RepoZ` indicates a different repository. -| Reference in User1/Repo1 | Repo1 issues are external | RepoZ issues are external | Should render | -|---------------------------|:-------------------------:|:-------------------------:|----------------------------------| -| `#1234` | no | N/A | A link to issue/pull 1234 in `User1/Repo1` | -| `!1234` | no | N/A | A link to issue/pull 1234 in `User1/Repo1` | -| `#1234` | yes | N/A | A link to _external issue_ 1234 for `User1/Repo1` | -| `!1234` | yes | N/A | A link to _PR_ 1234 for `User1/Repo1` | -| `User1/Repo1#1234` | no | N/A | A link to issue/pull 1234 in `User1/Repo1` | -| `User1/Repo1!1234` | no | N/A | A link to issue/pull 1234 in `User1/Repo1` | -| `User1/Repo1#1234` | yes | N/A | A link to _external issue_ 1234 for `User1/Repo1` | -| `User1/Repo1!1234` | yes | N/A | A link to _PR_ 1234 for `User1/Repo1` | -| `UserZ/RepoZ#1234` | N/A | no | A link to issue/pull 1234 in `UserZ/RepoZ` | -| `UserZ/RepoZ!1234` | N/A | no | A link to issue/pull 1234 in `UserZ/RepoZ` | -| `UserZ/RepoZ#1234` | N/A | yes | A link to _external issue_ 1234 for `UserZ/RepoZ` | -| `UserZ/RepoZ!1234` | N/A | yes | A link to _PR_ 1234 for `UserZ/RepoZ` | -| **Alphanumeric issue IDs:** | - | - | - | -| `AAA-1234` | yes | N/A | A link to _external issue_ `AAA-1234` for `User1/Repo1` | -| `!1234` | yes | N/A | A link to _PR_ 1234 for `User1/Repo1` | -| `User1/Repo1!1234` | yes | N/A | A link to _PR_ 1234 for `User1/Repo1` | -| _Not supported_ | N/A | yes | A link to _external issue_ `AAA-1234` for `UserZ/RepoZ` | -| `UserZ/RepoZ!1234` | N/A | yes | A link to _PR_ 1234 in `UserZ/RepoZ` | +| Reference in User1/Repo1 | Repo1 issues are external | RepoZ issues are external | Should render | +| --------------------------- | :-----------------------: | :-----------------------: | ------------------------------------------------------- | +| `#1234` | no | N/A | A link to issue/pull 1234 in `User1/Repo1` | +| `!1234` | no | N/A | A link to issue/pull 1234 in `User1/Repo1` | +| `#1234` | yes | N/A | A link to _external issue_ 1234 for `User1/Repo1` | +| `!1234` | yes | N/A | A link to _PR_ 1234 for `User1/Repo1` | +| `User1/Repo1#1234` | no | N/A | A link to issue/pull 1234 in `User1/Repo1` | +| `User1/Repo1!1234` | no | N/A | A link to issue/pull 1234 in `User1/Repo1` | +| `User1/Repo1#1234` | yes | N/A | A link to _external issue_ 1234 for `User1/Repo1` | +| `User1/Repo1!1234` | yes | N/A | A link to _PR_ 1234 for `User1/Repo1` | +| `UserZ/RepoZ#1234` | N/A | no | A link to issue/pull 1234 in `UserZ/RepoZ` | +| `UserZ/RepoZ!1234` | N/A | no | A link to issue/pull 1234 in `UserZ/RepoZ` | +| `UserZ/RepoZ#1234` | N/A | yes | A link to _external issue_ 1234 for `UserZ/RepoZ` | +| `UserZ/RepoZ!1234` | N/A | yes | A link to _PR_ 1234 for `UserZ/RepoZ` | +| **Alphanumeric issue IDs:** | - | - | - | +| `AAA-1234` | yes | N/A | A link to _external issue_ `AAA-1234` for `User1/Repo1` | +| `!1234` | yes | N/A | A link to _PR_ 1234 for `User1/Repo1` | +| `User1/Repo1!1234` | yes | N/A | A link to _PR_ 1234 for `User1/Repo1` | +| _Not supported_ | N/A | yes | A link to _external issue_ `AAA-1234` for `UserZ/RepoZ` | +| `UserZ/RepoZ!1234` | N/A | yes | A link to _PR_ 1234 in `UserZ/RepoZ` | _The last section is for repositories with external issue trackers that use alphanumeric format._ diff --git a/docs/content/doc/usage/pull-request.en-us.md b/docs/content/doc/usage/pull-request.en-us.md index 39cff7f65..33743f8ea 100644 --- a/docs/content/doc/usage/pull-request.en-us.md +++ b/docs/content/doc/usage/pull-request.en-us.md @@ -3,7 +3,7 @@ date: "2018-06-01T19:00:00+02:00" title: "Usage: Pull Request" slug: "pull-request" weight: 13 -toc: true +toc: false draft: false menu: sidebar: @@ -19,7 +19,7 @@ menu: Marking a pull request as being a work in progress will prevent that pull request from being accidentally merged. To mark a pull request as being a work in progress, you must prefix its title by `WIP:` or `[WIP]` (case insensitive). Those values are configurable in your `app.ini` file : -``` +```ini [repository.pull-request] WORK_IN_PROGRESS_PREFIXES=WIP:,[WIP] ``` diff --git a/docs/content/doc/usage/pull-request.zh-cn.md b/docs/content/doc/usage/pull-request.zh-cn.md index c1bddef1b..04125672d 100644 --- a/docs/content/doc/usage/pull-request.zh-cn.md +++ b/docs/content/doc/usage/pull-request.zh-cn.md @@ -3,7 +3,7 @@ date: "2018-06-01T19:00:00+02:00" title: "使用：Pull Request" slug: "pull-request" weight: 13 -toc: true +toc: false draft: false menu: sidebar: diff --git a/docs/content/doc/usage/push-options.en-us.md b/docs/content/doc/usage/push-options.en-us.md index 439d13b42..6539c9d7c 100644 --- a/docs/content/doc/usage/push-options.en-us.md +++ b/docs/content/doc/usage/push-options.en-us.md @@ -3,7 +3,7 @@ date: "2020-07-06T16:00:00+02:00" title: "Usage: Push Options" slug: "push-options" weight: 15 -toc: true +toc: false draft: false menu: sidebar: diff --git a/docs/content/doc/usage/reverse-proxies.en-us.md b/docs/content/doc/usage/reverse-proxies.en-us.md index 89f7ff5c4..714e912d8 100644 --- a/docs/content/doc/usage/reverse-proxies.en-us.md +++ b/docs/content/doc/usage/reverse-proxies.en-us.md @@ -3,7 +3,7 @@ date: "2018-05-22T11:00:00+00:00" title: "Usage: Reverse Proxies" slug: "reverse-proxies" weight: 17 -toc: true +toc: false draft: false menu: sidebar: @@ -15,12 +15,15 @@ menu: # Reverse Proxies +**Table of Contents** + {{< toc >}} -## Nginx +## Nginx + If you want Nginx to serve your Gitea instance, add the following `server` section to the `http` section of `nginx.conf`: -``` +```apacheconf server { listen 80; server_name git.example.com; @@ -35,7 +38,7 @@ server { In case you already have a site, and you want Gitea to share the domain name, you can setup Nginx to serve Gitea under a sub-path by adding the following `server` section inside the `http` section of `nginx.conf`: -``` +```apacheconf server { listen 80; server_name git.example.com; @@ -48,7 +51,8 @@ server { Then set `[server] ROOT_URL = http://git.example.com/git/` in your configuration. -## Nginx and serve static resources directly +## Nginx and serve static resources directly + We can tune the performance in splitting requests into categories static and dynamic. CSS files, JavaScript files, images and web fonts are static content. @@ -56,20 +60,20 @@ The front page, a repository view or issue list is dynamic content. Nginx can serve static resources directly and proxy only the dynamic requests to gitea. Nginx is optimized for serving static content, while the proxying of large responses might be the opposite of that - (see https://serverfault.com/q/587386). +(see https://serverfault.com/q/587386). Download a snapshot of the Gitea source repository to `/path/to/gitea/`. After this, run `make frontend` in the repository directory to generate the static resources. We are only interested in the `public/` directory for this task, so you can delete the rest. (You will need to have [Node with npm](https://nodejs.org/en/download/) and `make` installed to generate the static resources) Depending on the scale of your user base, you might want to split the traffic to two distinct servers, - or use a cdn for the static files. +or use a cdn for the static files. ### Single node and single domain Set `[server] STATIC_URL_PREFIX = /_/static` in your configuration. -``` +```apacheconf server { listen 80; server_name git.example.com; @@ -88,7 +92,7 @@ server { Set `[server] STATIC_URL_PREFIX = http://cdn.example.com/gitea` in your configuration. -``` +```apacheconf # application server running gitea server { listen 80; @@ -100,7 +104,7 @@ server { } ``` -``` +```apacheconf # static content delivery server server { listen 80; @@ -120,7 +124,7 @@ server { If you want Apache HTTPD to serve your Gitea instance, you can add the following to your Apache HTTPD configuration (usually located at `/etc/apache2/httpd.conf` in Ubuntu): -``` +```apacheconf ... ProxyPreserveHost On @@ -139,7 +143,7 @@ If you wish to use Let's Encrypt with webroot validation, add the line `ProxyPas In case you already have a site, and you want Gitea to share the domain name, you can setup Apache HTTPD to serve Gitea under a sub-path by adding the following to you Apache HTTPD configuration (usually located at `/etc/apache2/httpd.conf` in Ubuntu): -``` +```apacheconf ... @@ -161,7 +165,7 @@ Note: The following Apache HTTPD mods must be enabled: `proxy`, `proxy_http` If you want Caddy to serve your Gitea instance, you can add the following server block to your Caddyfile: -``` +```apacheconf git.example.com { reverse_proxy localhost:3000 } @@ -169,7 +173,7 @@ git.example.com { If you still use Caddy v1, use: -``` +```apacheconf git.example.com { proxy / localhost:3000 } @@ -179,7 +183,7 @@ git.example.com { In case you already have a site, and you want Gitea to share the domain name, you can setup Caddy to serve Gitea under a sub-path by adding the following to your server block in your Caddyfile: -``` +```apacheconf git.example.com { route /git/* { uri strip_prefix /git @@ -190,7 +194,7 @@ git.example.com { Or, for Caddy v1: -``` +```apacheconf git.example.com { proxy /git/ localhost:3000 } @@ -204,14 +208,15 @@ If you wish to run Gitea with IIS. You will need to setup IIS with URL Rewrite a 1. Setup an empty website in IIS, named let's say, `Gitea Proxy`. 2. Follow the first two steps in [Microsoft's Technical Community Guide to Setup IIS with URL Rewrite](https://techcommunity.microsoft.com/t5/iis-support-blog/setup-iis-with-url-rewrite-as-a-reverse-proxy-for-real-world/ba-p/846222#M343). That is: - - Install Application Request Routing (ARR for short) either by using the Microsoft Web Platform Installer 5.1 (WebPI) or downloading the extension from [IIS.net]( https://www.iis.net/downloads/microsoft/application-request-routing) - - Once the module is installed in IIS, you will see a new Icon in the IIS Administration Console called URL Rewrite. - - Open the IIS Manager Console and click on the `Gitea Proxy` Website from the tree view on the left. Select and double click the URL Rewrite Icon from the middle pane to load the URL Rewrite interface. - - Choose the `Add Rule` action from the right pane of the management console and select the `Reverse Proxy Rule` from the `Inbound and Outbound Rules` category. - - In the Inbound Rules section, set the server name to be the host that Gitea is running on with its port. e.g. if you are running Gitea on the localhost with port 3000, the following should work: `127.0.0.1:3000` - - Enable SSL Offloading - - In the Outbound Rules, ensure `Rewrite the domain names of the links in HTTP response` is set and set the `From:` field as above and the `To:` to your external hostname, say: `git.example.com` - - Now edit the `web.config` for your website to match the following: (changing `127.0.0.1:3000` and `git.example.com` as appropriate) + +- Install Application Request Routing (ARR for short) either by using the Microsoft Web Platform Installer 5.1 (WebPI) or downloading the extension from [IIS.net](https://www.iis.net/downloads/microsoft/application-request-routing) +- Once the module is installed in IIS, you will see a new Icon in the IIS Administration Console called URL Rewrite. +- Open the IIS Manager Console and click on the `Gitea Proxy` Website from the tree view on the left. Select and double click the URL Rewrite Icon from the middle pane to load the URL Rewrite interface. +- Choose the `Add Rule` action from the right pane of the management console and select the `Reverse Proxy Rule` from the `Inbound and Outbound Rules` category. +- In the Inbound Rules section, set the server name to be the host that Gitea is running on with its port. e.g. if you are running Gitea on the localhost with port 3000, the following should work: `127.0.0.1:3000` +- Enable SSL Offloading +- In the Outbound Rules, ensure `Rewrite the domain names of the links in HTTP response` is set and set the `From:` field as above and the `To:` to your external hostname, say: `git.example.com` +- Now edit the `web.config` for your website to match the following: (changing `127.0.0.1:3000` and `git.example.com` as appropriate) ```xml diff --git a/docs/content/doc/usage/reverse-proxies.zh-cn.md b/docs/content/doc/usage/reverse-proxies.zh-cn.md index f52adccbb..b2425f8d5 100644 --- a/docs/content/doc/usage/reverse-proxies.zh-cn.md +++ b/docs/content/doc/usage/reverse-proxies.zh-cn.md @@ -3,7 +3,7 @@ date: "2018-05-22T11:00:00+00:00" title: "使用：反向代理" slug: "reverse-proxies" weight: 17 -toc: true +toc: false draft: false menu: sidebar: diff --git a/docs/content/doc/usage/template-repositories.md b/docs/content/doc/usage/template-repositories.md index 6bd5ae7bc..24fdf28ee 100644 --- a/docs/content/doc/usage/template-repositories.md +++ b/docs/content/doc/usage/template-repositories.md @@ -3,7 +3,7 @@ date: "2019-11-28:00:00+02:00" title: "Template Repositories" slug: "template-repositories" weight: 14 -toc: true +toc: false draft: false menu: sidebar: @@ -13,13 +13,20 @@ menu: identifier: "template-repositories" --- -## Template Repositories +# Template Repositories + +**Table of Contents** + +{{< toc >}} + Gitea `1.11.0` and above includes template repositories, and one feature implemented with them is auto-expansion of specific variables within your template files. To tell Gitea which files to expand, you must include a `template` file inside the `.gitea` directory of the template repository. Gitea uses [gobwas/glob](https://github.com/gobwas/glob) for its glob syntax. It closely resembles a traditional `.gitignore`, however there may be slight differences. -### Example `.gitea/template` file +## Example `.gitea/template` file + All paths are relative to the base of the repository + ```gitignore # All .go files, anywhere in the repository **.go @@ -33,14 +40,16 @@ a/b/c/d.json # Batch files in both upper or lower case can be matched **.[bB][aA][tT] ``` + **NOTE:** The `template` file will be removed from the `.gitea` directory when a repository is generated from the template. -### Variable Expansion +## Variable Expansion + In any file matched by the above globs, certain variables will be expanded. All variables must be of the form `$VAR` or `${VAR}`. To escape an expansion, use a double `$$`, such as `$$VAR` or `$${VAR}` | Variable | Expands To | Transformable | -|----------------------|-----------------------------------------------------|---------------| +| -------------------- | --------------------------------------------------- | ------------- | | REPO_NAME | The name of the generated repository | ✓ | | TEMPLATE_NAME | The name of the template repository | ✓ | | REPO_DESCRIPTION | The description of the generated repository | ✘ | @@ -54,18 +63,19 @@ All variables must be of the form `$VAR` or `${VAR}`. To escape an expansion, us | REPO_SSH_URL | The SSH clone link for the generated repository | ✘ | | TEMPLATE_SSH_URL | The SSH clone link for the template repository | ✘ | -### Transformers :robot: +## Transformers :robot: + Gitea `1.12.0` adds a few transformers to some of the applicable variables above. For example, to get `REPO_NAME` in `PASCAL`-case, your template would use `${REPO_NAME_PASCAL}` Feeding `go-sdk` to the available transformers yields... -| Transformer | Effect | -|-------------|------------| -| SNAKE | go_sdk | -| KEBAB | go-sdk | -| CAMEL | goSdk | -| PASCAL | GoSdk | -| LOWER | go-sdk | -| UPPER | GO-SDK | -| TITLE | Go-Sdk | +| Transformer | Effect | +| ----------- | ------ | +| SNAKE | go_sdk | +| KEBAB | go-sdk | +| CAMEL | goSdk | +| PASCAL | GoSdk | +| LOWER | go-sdk | +| UPPER | GO-SDK | +| TITLE | Go-Sdk | diff --git a/docs/content/page/index.en-us.md b/docs/content/page/index.en-us.md index 32ce9c123..1002c9551 100644 --- a/docs/content/page/index.en-us.md +++ b/docs/content/page/index.en-us.md @@ -4,7 +4,7 @@ title: "Documentation" slug: "documentation" url: "/en-us/" weight: 10 -toc: true +toc: false draft: false --- diff --git a/docs/content/page/index.fr-fr.md b/docs/content/page/index.fr-fr.md index 9b9743c10..c6761edc4 100755 --- a/docs/content/page/index.fr-fr.md +++ b/docs/content/page/index.fr-fr.md @@ -4,7 +4,7 @@ title: "Documentation" slug: "documentation" url: "/fr-fr/" weight: 10 -toc: true +toc: false draft: false --- diff --git a/docs/content/page/index.zh-cn.md b/docs/content/page/index.zh-cn.md index cf137a1fc..5ffc4b2b0 100644 --- a/docs/content/page/index.zh-cn.md +++ b/docs/content/page/index.zh-cn.md @@ -4,7 +4,7 @@ title: "文档" slug: "documentation" url: "/zh-cn/" weight: 10 -toc: true +toc: false draft: false --- diff --git a/docs/content/page/index.zh-tw.md b/docs/content/page/index.zh-tw.md index 5ea9b6796..1392c2a9c 100644 --- a/docs/content/page/index.zh-tw.md +++ b/docs/content/page/index.zh-tw.md @@ -4,7 +4,7 @@ title: "文件" slug: "documentation" url: "/zh-tw/" weight: 10 -toc: true +toc: false draft: false ---