From 32f57a30b76958a7d751215bd7f26034ac7559d3 Mon Sep 17 00:00:00 2001 From: jolheiser Date: Fri, 5 Apr 2019 11:25:23 -0500 Subject: [PATCH 01/14] Initial draft Signed-off-by: jolheiser --- docs/content/doc/help/faq.en-us.md | 207 ++++++++++++++++++ .../content/doc/help/troubleshooting.en-us.md | 96 -------- 2 files changed, 207 insertions(+), 96 deletions(-) create mode 100644 docs/content/doc/help/faq.en-us.md delete mode 100644 docs/content/doc/help/troubleshooting.en-us.md diff --git a/docs/content/doc/help/faq.en-us.md b/docs/content/doc/help/faq.en-us.md new file mode 100644 index 0000000000000..1a5ee6731150f --- /dev/null +++ b/docs/content/doc/help/faq.en-us.md @@ -0,0 +1,207 @@ +--- +date: "2016-11-08T16:00:00+02:00" +title: "FAQ" +slug: "faq" +weight: 5 +toc: true +draft: false +menu: + sidebar: + parent: "help" + name: "FAQ" + weight: 5 + identifier: "faq" +--- + +# Frequently Asked Questions + +This page contains some common questions and answers. +Also see [Support Options]({{< relref "doc/help/seek-help.en-us.md" >}}) + +* [How to migrate from Gogs/GitHub/etc. to Gitea](#how-to-migrate-from-gogs-github-etc-to-gitea) +* [Where does Gitea store "x" file](#where-does-gitea-store-x-file) +* [Not seeing a clone URL or the clone URL being incorrect](#not-seeing-a-clone-url-or-the-clone-url-being-incorrect) +* [Custom Templates not loading or working incorrectly](#custom-templates-not-loading-or-working-incorrectly) +* [Active user vs login prohibited user](#active-user-vs-login-prohibited-user) +* [Setting up logging](#setting-up-logging) +* [Adjusting your server for public/private use](#adjusting-your-server-for-public-private-use) + * [Preventing spammers](#preventing-spammers) + * [Only allow/block certain email domains](#only-allow-block-certain-email-domains) + * [Issue only users](#issue-only-users) +* [Adding custom themes](#how-to-add-use-custom-themes) +* [SSHD vs built-in SSH](#sshd-vs-built-in-ssh) +* [Gitea is running slow](#why-is-gitea-running-slow) +* [Translation is incorrect/how to add more translations](#translation-is-incorrect-how-to-add-more-translations) +* [SSH Issues](#ssh-issues) +* [Missing releases after migration repository with tags](#missing-releases-after-migrating-repository-with-tags) +* [LFS Issues](#lfs-issues) + + +## 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) + +To migrate from GitHub to Gitea, you can use Gitea's [Migrator tool](https://gitea.com/gitea/migrator) + +To migrate from Gitlab to Gitea, you can use this non-affiliated tool: +https://github.com/loganinak/MigrateGitlabToGogs + +## Where does Gitea store "x" 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` +* 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" >}}) +2. Make sure you have correctly set `ROOT_URL` in the `server` section of your `app.ini` + +## 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. +To find the correct path, follow these steps: + +1. Check if the environment variable is set: +``` +echo $GITEA_CUSTOM +``` + +2. If not, the default can be [found 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" >}}) + +## Adjusting your server for public/private use + +### Preventing 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/advanced/api-usage.en-us.md" >}}), or Gitea's Admin UI + +[API Example](https://try.gitea.io/api/swagger) + +### Only allow/block certain email domains +If using OpenID, you can configure `WHITELISTED_URIS` or `BLACKLISTED_URIS` 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. + +## 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) + +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. + +## Why is Gitea 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` + +## Translation is incorrect/how to add more translations +Our translations are currently crowd-sourced on our [Crowding 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. + +## SSH issues + +For issues reaching repositories over `ssh` while the Gitea web front-end, but +`https` based git repository access works fine, consider looking into the following. + +``` +Permission denied (publickey). +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 + git user (before the `@`) is spelled correctly. + * Ensure public and private ssh keys are correct on client machine. + * Try to connect using ssh (ssh git@myremote.example) to ensure a connection + can be made. +* 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. + +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 +repository. + +``` +fatal: Could not read from remote repository. + +Please make sure you have the correct access rights +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 + correct configuration file. + +## Missing releases after migrating repository with tags + +To migrate an repository *with* all tags, you need to do two things: + +* Push tags to the repository: +``` + git push --tags + ``` + + * (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 +Check that you have proper access to the repository +error: failed to push some refs to '' +``` +Have you checked 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`. diff --git a/docs/content/doc/help/troubleshooting.en-us.md b/docs/content/doc/help/troubleshooting.en-us.md deleted file mode 100644 index 664a51731eec6..0000000000000 --- a/docs/content/doc/help/troubleshooting.en-us.md +++ /dev/null @@ -1,96 +0,0 @@ ---- -date: "2016-11-08T16:00:00+02:00" -title: "Troubleshooting" -slug: "troubleshooting" -weight: 10 -toc: true -draft: false -menu: - sidebar: - parent: "help" - name: "Troubleshooting" - weight: 20 - identifier: "troubleshooting" ---- - -# Troubleshooting - -This page contains some common seen issues and their solutions. - -## SSH issues - -For issues reaching repositories over `ssh` while the Gitea web front-end, but -`https` based git repository access works fine, consider looking into the following. - -``` -Permission denied (publickey). -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 - git user (before the `@`) is spelled correctly. - * Ensure public and private ssh keys are correct on client machine. - * Try to connect using ssh (ssh git@myremote.example) to ensure a connection - can be made. -* 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. - -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 -repository. - -``` -fatal: Could not read from remote repository. - -Please make sure you have the correct access rights -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 - correct configuration file. - -## Missing releases after migrating repository with tags - -To migrate an repository *with* all tags, you need to do two things: - -* Push tags to the repository: -``` - git push --tags - ``` - - * (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 -Check that you have proper access to the repository -error: failed to push some refs to '' -``` -Have you checked 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`. - From d44a5f888c21c17e82d38999f742f1860b970c26 Mon Sep 17 00:00:00 2001 From: jolheiser Date: Fri, 5 Apr 2019 11:31:53 -0500 Subject: [PATCH 02/14] Update date (not that it's shown...) Signed-off-by: jolheiser --- docs/content/doc/help/faq.en-us.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/content/doc/help/faq.en-us.md b/docs/content/doc/help/faq.en-us.md index 1a5ee6731150f..4bece0b7cb932 100644 --- a/docs/content/doc/help/faq.en-us.md +++ b/docs/content/doc/help/faq.en-us.md @@ -1,5 +1,5 @@ --- -date: "2016-11-08T16:00:00+02:00" +date: "2019-04-05T16:00:00+02:00" title: "FAQ" slug: "faq" weight: 5 From 1a7c68a7df07bce65592a271ea2a3d582db73cba Mon Sep 17 00:00:00 2001 From: jolheiser Date: Fri, 5 Apr 2019 11:43:57 -0500 Subject: [PATCH 03/14] Add fail2ban Signed-off-by: jolheiser --- docs/content/doc/help/faq.en-us.md | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/docs/content/doc/help/faq.en-us.md b/docs/content/doc/help/faq.en-us.md index 4bece0b7cb932..75639cb84f5f4 100644 --- a/docs/content/doc/help/faq.en-us.md +++ b/docs/content/doc/help/faq.en-us.md @@ -28,6 +28,7 @@ Also see [Support Options]({{< relref "doc/help/seek-help.en-us.md" >}}) * [Preventing spammers](#preventing-spammers) * [Only allow/block certain email domains](#only-allow-block-certain-email-domains) * [Issue only users](#issue-only-users) + * [Enable Fail2ban](#enable-fail2ban) * [Adding custom themes](#how-to-add-use-custom-themes) * [SSHD vs built-in SSH](#sshd-vs-built-in-ssh) * [Gitea is running slow](#why-is-gitea-running-slow) @@ -108,6 +109,10 @@ If using OpenID, you can configure `WHITELISTED_URIS` or `BLACKLISTED_URIS` in y ### Issue only users The current way to achieve this is to create/modify a user with a max repo creation limit of 0. +### Enable Fail2ban + +Use [Fail2Ban]({{ relref "doc/usage/fail2ban-setup.md" >}}) to monitor and stop automated login attempts and 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) From b3b9ad230f0adf46e74c2208772759ce442ea23f Mon Sep 17 00:00:00 2001 From: jolheiser Date: Fri, 5 Apr 2019 12:08:41 -0500 Subject: [PATCH 04/14] Added @mrsdizzie suggestions Added note to support page reminding users to have information available for troubleshooting Signed-off-by: jolheiser --- docs/content/doc/help/faq.en-us.md | 17 ++++++++++------- docs/content/doc/help/seek-help.en-us.md | 7 +++++++ 2 files changed, 17 insertions(+), 7 deletions(-) diff --git a/docs/content/doc/help/faq.en-us.md b/docs/content/doc/help/faq.en-us.md index 75639cb84f5f4..fc317ff9058ee 100644 --- a/docs/content/doc/help/faq.en-us.md +++ b/docs/content/doc/help/faq.en-us.md @@ -72,16 +72,19 @@ 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" >}}) 2. Make sure you have correctly set `ROOT_URL` in the `server` section of your `app.ini` +If certain clone options aren't showing up (HTTP/S or SSH), the following options can be checked in your `app.ini` + +`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 + + ## 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. -To find the correct path, follow these steps: - -1. Check if the environment variable is set: -``` -echo $GITEA_CUSTOM -``` -2. If not, the default can be [found above](#where-does-gitea-store-x-file) +1. To find the correct path, look for Custom File Root Path in Site Administration -> Configuration + * If that doesn't exist, you can try `echo $GITEA_CUSTOM` +2. If you are still unable to find a path, the default can be [calculated above](#where-does-gitea-store-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 diff --git a/docs/content/doc/help/seek-help.en-us.md b/docs/content/doc/help/seek-help.en-us.md index 36406b091f5eb..e9de812eac037 100644 --- a/docs/content/doc/help/seek-help.en-us.md +++ b/docs/content/doc/help/seek-help.en-us.md @@ -18,6 +18,13 @@ menu: - [Discord](https://discord.gg/NsatcWJ) - [Discourse Forum](https://discourse.gitea.io/) +**NOTE:** When asking for support, it may be a good idea to have the following available so that the person helping has all the info they need: + +1. Your `app.ini` (with any sensitive data scrubbed as necessary) +2. The `gitea.log` (and any other appropriate log files for the situation) + * e.g. If the error is related to the database, the `xorm.log` might be helpful +3. Any error messages you are seeing + ## Bugs If you found a bug, please create an [issue on GitHub](https://github.com/go-gitea/gitea/issues). From 45be7ba37e6e7ff04e195bbf326262f65e17218c Mon Sep 17 00:00:00 2001 From: jolheiser Date: Fri, 5 Apr 2019 12:11:38 -0500 Subject: [PATCH 05/14] Clarify CustomPath Signed-off-by: jolheiser --- docs/content/doc/help/faq.en-us.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/docs/content/doc/help/faq.en-us.md b/docs/content/doc/help/faq.en-us.md index fc317ff9058ee..8cb50e9977afe 100644 --- a/docs/content/doc/help/faq.en-us.md +++ b/docs/content/doc/help/faq.en-us.md @@ -81,8 +81,9 @@ If certain clone options aren't showing up (HTTP/S or SSH), the following option ## 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 the correct path, look for Custom File Root Path in Site Administration -> Configuration +1. To find `CustomPath`, look for Custom File Root Path in Site Administration -> Configuration * If that doesn't exist, you can try `echo $GITEA_CUSTOM` 2. If you are still unable to find a path, the default can be [calculated above](#where-does-gitea-store-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. From 6836797a26e9726860bd44b1e582b125fe4865aa Mon Sep 17 00:00:00 2001 From: jolheiser Date: Fri, 5 Apr 2019 12:24:29 -0500 Subject: [PATCH 06/14] Add reminder to try replicating problem on try.gitea.io Signed-off-by: jolheiser --- docs/content/doc/help/seek-help.en-us.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/docs/content/doc/help/seek-help.en-us.md b/docs/content/doc/help/seek-help.en-us.md index e9de812eac037..6940d7f12c826 100644 --- a/docs/content/doc/help/seek-help.en-us.md +++ b/docs/content/doc/help/seek-help.en-us.md @@ -24,6 +24,8 @@ menu: 2. The `gitea.log` (and any other appropriate log files for the situation) * e.g. If the error is related to the database, the `xorm.log` might be helpful 3. Any error messages you are seeing +4. When possible, try to replicate the issue on [try.gitea.io](https://try.gitea.io) and include steps so that others can reproduce the issue. + * This will greatly improve the chance that the root of the issue can be quickly discovered and resolved. ## Bugs From a9ee549091339ada6e4ec67faab25dfb50b488d8 Mon Sep 17 00:00:00 2001 From: jolheiser Date: Mon, 8 Apr 2019 09:31:24 -0500 Subject: [PATCH 07/14] Add more paths Reminder to make sure Gitea can write to needed directories Add swagger Signed-off-by: jolheiser --- docs/content/doc/help/faq.en-us.md | 25 +++++++++++++++++++++++-- 1 file changed, 23 insertions(+), 2 deletions(-) diff --git a/docs/content/doc/help/faq.en-us.md b/docs/content/doc/help/faq.en-us.md index 8cb50e9977afe..41b3af0897c9e 100644 --- a/docs/content/doc/help/faq.en-us.md +++ b/docs/content/doc/help/faq.en-us.md @@ -24,6 +24,7 @@ Also see [Support Options]({{< relref "doc/help/seek-help.en-us.md" >}}) * [Custom Templates not loading or working incorrectly](#custom-templates-not-loading-or-working-incorrectly) * [Active user vs login prohibited user](#active-user-vs-login-prohibited-user) * [Setting up logging](#setting-up-logging) +* [What is Swagger?](#what-is-swagger) * [Adjusting your server for public/private use](#adjusting-your-server-for-public-private-use) * [Preventing spammers](#preventing-spammers) * [Only allow/block certain email domains](#only-allow-block-certain-email-domains) @@ -32,6 +33,7 @@ Also see [Support Options]({{< relref "doc/help/seek-help.en-us.md" >}}) * [Adding custom themes](#how-to-add-use-custom-themes) * [SSHD vs built-in SSH](#sshd-vs-built-in-ssh) * [Gitea is running slow](#why-is-gitea-running-slow) +* [Can't create repositories/files](#cant-create-repositories-files) * [Translation is incorrect/how to add more translations](#translation-is-incorrect-how-to-add-more-translations) * [SSH Issues](#ssh-issues) * [Missing releases after migration repository with tags](#missing-releases-after-migrating-repository-with-tags) @@ -59,6 +61,12 @@ https://github.com/loganinak/MigrateGitlabToGogs * 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` @@ -95,6 +103,13 @@ A "login prohibited" user is a user that is not allowed to log in to Gitea anymo ## Setting up logging * [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/advanced/api-usage.en-us.md" >}}) + +[Swagger Example](https://try.gitea.io/api/swagger) + ## Adjusting your server for public/private use ### Preventing spammers @@ -104,8 +119,6 @@ There are multiple things you can combine to prevent spammers. 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/advanced/api-usage.en-us.md" >}}), or Gitea's Admin UI -[API Example](https://try.gitea.io/api/swagger) - ### Only allow/block certain email domains If using OpenID, you can configure `WHITELISTED_URIS` or `BLACKLISTED_URIS` in your `app.ini` **NOTE:** whitelisted takes precedence, so if it is non-blank then blacklisted is ignored @@ -134,6 +147,14 @@ 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) + +**Note for Arch users:** At the time of writing this, there is an issue with the Arch package's systemd file including this line: +`ReadWritePaths=/etc/gitea/app.ini` +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 [Crowding 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. From 50fa54b54a4cb4021193efdb97929e42dbd97369 Mon Sep 17 00:00:00 2001 From: jolheiser Date: Mon, 8 Apr 2019 09:34:49 -0500 Subject: [PATCH 08/14] Change to vanity URL Signed-off-by: jolheiser --- docs/content/doc/help/seek-help.en-us.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/content/doc/help/seek-help.en-us.md b/docs/content/doc/help/seek-help.en-us.md index 6940d7f12c826..e9d0211029ea5 100644 --- a/docs/content/doc/help/seek-help.en-us.md +++ b/docs/content/doc/help/seek-help.en-us.md @@ -15,7 +15,7 @@ menu: # Support Options -- [Discord](https://discord.gg/NsatcWJ) +- [Discord](https://discord.gg/Gitea) - [Discourse Forum](https://discourse.gitea.io/) **NOTE:** When asking for support, it may be a good idea to have the following available so that the person helping has all the info they need: From b0087502f0275c18b062fb8445a0ffdd964f60d1 Mon Sep 17 00:00:00 2001 From: jolheiser Date: Wed, 10 Apr 2019 08:36:31 -0500 Subject: [PATCH 09/14] Crowding -> Crowdin Signed-off-by: jolheiser --- docs/content/doc/help/faq.en-us.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/content/doc/help/faq.en-us.md b/docs/content/doc/help/faq.en-us.md index 41b3af0897c9e..4384402cd567c 100644 --- a/docs/content/doc/help/faq.en-us.md +++ b/docs/content/doc/help/faq.en-us.md @@ -156,7 +156,7 @@ 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 [Crowding project](https://crowdin.com/project/gitea) +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. ## SSH issues From 7c9ebf215082a7249be99aa0d6c40cd531a18041 Mon Sep 17 00:00:00 2001 From: jolheiser Date: Wed, 10 Apr 2019 08:49:39 -0500 Subject: [PATCH 10/14] Change questions to statements in a few places Signed-off-by: jolheiser --- docs/content/doc/help/faq.en-us.md | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/docs/content/doc/help/faq.en-us.md b/docs/content/doc/help/faq.en-us.md index 4384402cd567c..15138a6520d03 100644 --- a/docs/content/doc/help/faq.en-us.md +++ b/docs/content/doc/help/faq.en-us.md @@ -32,7 +32,7 @@ Also see [Support Options]({{< relref "doc/help/seek-help.en-us.md" >}}) * [Enable Fail2ban](#enable-fail2ban) * [Adding custom themes](#how-to-add-use-custom-themes) * [SSHD vs built-in SSH](#sshd-vs-built-in-ssh) -* [Gitea is running slow](#why-is-gitea-running-slow) +* [Gitea is running slow](#gitea-is-running-slow) * [Can't create repositories/files](#cant-create-repositories-files) * [Translation is incorrect/how to add more translations](#translation-is-incorrect-how-to-add-more-translations) * [SSH Issues](#ssh-issues) @@ -142,7 +142,7 @@ Allow users to use it by adding `arc-blue` to the list of `THEMES` in your `app. 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. -## Why is Gitea running slow? +## 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` @@ -232,6 +232,7 @@ batch response: Authentication required: Authorization error: /in Check that you have proper access to the repository error: failed to push some refs to '' ``` -Have you checked 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. +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`. From d16ae3c4053cdb7d718e5c55955593d34d28f5ba Mon Sep 17 00:00:00 2001 From: jolheiser Date: Fri, 12 Apr 2019 09:19:28 -0500 Subject: [PATCH 11/14] Add SSH successful error message Signed-off-by: jolheiser --- docs/content/doc/help/faq.en-us.md | 20 ++++++++++++++------ 1 file changed, 14 insertions(+), 6 deletions(-) diff --git a/docs/content/doc/help/faq.en-us.md b/docs/content/doc/help/faq.en-us.md index 15138a6520d03..049172721cae5 100644 --- a/docs/content/doc/help/faq.en-us.md +++ b/docs/content/doc/help/faq.en-us.md @@ -36,6 +36,7 @@ Also see [Support Options]({{< relref "doc/help/seek-help.en-us.md" >}}) * [Can't create repositories/files](#cant-create-repositories-files) * [Translation is incorrect/how to add more translations](#translation-is-incorrect-how-to-add-more-translations) * [SSH Issues](#ssh-issues) + * [SSH Common Errors](#ssh-common-errors) * [Missing releases after migration repository with tags](#missing-releases-after-migrating-repository-with-tags) * [LFS Issues](#lfs-issues) @@ -128,7 +129,7 @@ The current way to achieve this is to create/modify a user with a max repo creat ### Enable Fail2ban -Use [Fail2Ban]({{ relref "doc/usage/fail2ban-setup.md" >}}) to monitor and stop automated login attempts and other malicious behavior based on log patterns +Use [Fail2Ban]({{ relref "doc/usage/fail2ban-setup.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) @@ -161,8 +162,17 @@ Whether you want to change a translation or add a new one, it will need to be th ## SSH issues -For issues reaching repositories over `ssh` while the Gitea web front-end, but -`https` based git repository access works fine, consider looking into the following. +If you cannot reach repositories over `ssh`, but `https` based git repository access works fine, consider looking into the following. + +First, make sure you can access Gitea via SSH. +`ssh -i ~/.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. +``` + +### SSH Common Errors ``` Permission denied (publickey). @@ -177,12 +187,10 @@ following things: * 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. - * Try to connect using ssh (ssh git@myremote.example) to ensure a connection - can be made. * 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`. + * 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. From 8dd6f59342b4cae0ce2c2216eac46fc47afb9256 Mon Sep 17 00:00:00 2001 From: jolheiser Date: Fri, 12 Apr 2019 09:23:39 -0500 Subject: [PATCH 12/14] Remove redundant message Signed-off-by: jolheiser --- docs/content/doc/help/faq.en-us.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/content/doc/help/faq.en-us.md b/docs/content/doc/help/faq.en-us.md index 049172721cae5..2360343550961 100644 --- a/docs/content/doc/help/faq.en-us.md +++ b/docs/content/doc/help/faq.en-us.md @@ -162,7 +162,7 @@ Whether you want to change a translation or add a new one, it will need to be th ## SSH issues -If you cannot reach repositories over `ssh`, but `https` based git repository access works fine, consider looking into the following. +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 -i ~/.ssh/ git@myremote.example` From a399e247625fbff95637a97a67412e37089a8dec Mon Sep 17 00:00:00 2001 From: jolheiser Date: Fri, 12 Apr 2019 10:11:04 -0500 Subject: [PATCH 13/14] Add hooks section Signed-off-by: jolheiser --- docs/content/doc/help/faq.en-us.md | 11 ++++++++++- 1 file changed, 10 insertions(+), 1 deletion(-) diff --git a/docs/content/doc/help/faq.en-us.md b/docs/content/doc/help/faq.en-us.md index 2360343550961..d610c8593decd 100644 --- a/docs/content/doc/help/faq.en-us.md +++ b/docs/content/doc/help/faq.en-us.md @@ -35,6 +35,7 @@ Also see [Support Options]({{< relref "doc/help/seek-help.en-us.md" >}}) * [Gitea is running slow](#gitea-is-running-slow) * [Can't create repositories/files](#cant-create-repositories-files) * [Translation is incorrect/how to add more translations](#translation-is-incorrect-how-to-add-more-translations) +* [Hooks aren't running](#hooks-aren-t-running) * [SSH Issues](#ssh-issues) * [SSH Common Errors](#ssh-common-errors) * [Missing releases after migration repository with tags](#missing-releases-after-migrating-repository-with-tags) @@ -160,18 +161,26 @@ Which makes all other paths non-writeable to Gitea. 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. -## SSH issues +## 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. + +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 -i ~/.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. ``` +If you do not get the above message, it means your SSH key is **not** being managed by Gitea. This means hooks won't run, among other potential problems. + ### SSH Common Errors ``` From b4d9519b8250c061443a92fef74cc9bd86960d22 Mon Sep 17 00:00:00 2001 From: jolheiser Date: Fri, 12 Apr 2019 10:40:40 -0500 Subject: [PATCH 14/14] Generify SSH example Clarify "good" error message Signed-off-by: jolheiser --- docs/content/doc/help/faq.en-us.md | 7 +++++-- 1 file changed, 5 insertions(+), 2 deletions(-) diff --git a/docs/content/doc/help/faq.en-us.md b/docs/content/doc/help/faq.en-us.md index d610c8593decd..c82583f360886 100644 --- a/docs/content/doc/help/faq.en-us.md +++ b/docs/content/doc/help/faq.en-us.md @@ -171,7 +171,7 @@ You can also try logging into the administration panel and running the `Resynchr 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 -i ~/.ssh/ git@myremote.example` +`ssh git@myremote.example` If the connection is successful, you should receive an error message like the following: ``` @@ -179,7 +179,10 @@ Hi there, You've successfully authenticated, but Gitea does not provide shell ac If this is unexpected, please log in with password and setup Gitea under another user. ``` -If you do not get the above message, it means your SSH key is **not** being managed by Gitea. This means hooks won't run, among other potential problems. +If you do not get the above message but still connect, it means your SSH key is **not** being managed by Gitea. This means hooks won't run, among other potential problems. + +If you cannot connect at all, your SSH key may not be configured correctly locally. +This is specific to SSH and not Gitea, so will not be covered here. ### SSH Common Errors