FAQ (#6524)

3 files changed, 268 insertions, 97 deletions

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 0000000000..c82583f360
--- /dev/null
+++ b/docs/content/doc/help/faq.en-us.md
@@ -0,0 +1,258 @@
+---
+date: "2019-04-05T16: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)
+* [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)
+  * [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](#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)
+* [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`
+* 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" >}})
+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.  
+The correct path for the template(s) will be relative to the `CustomPath`
+
+1. To find `CustomPath`, look for Custom File Root Path in Site Administration -> Configuration 
+  * If that doesn't exist, you can try `echo $GITEA_CUSTOM`
+2. If you are still unable to find a path, the default can be [calculated above](#where-does-gitea-store-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" >}})
+
+## 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
+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  
+
+### 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.
+
+### Enable Fail2ban
+
+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)  
+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)
+
+**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 [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.  
+  
+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`  
+
+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 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
+
+```
+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.
+* 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: <GITEA_LFS_URL>/info/lfs/objects/batch                                                                                                              
+Check that you have proper access to the repository
+error: failed to push some refs to '<GIT_REPO_URL>'
+```
+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`.
diff --git a/docs/content/doc/help/seek-help.en-us.md b/docs/content/doc/help/seek-help.en-us.md
index 36406b091f..e9d0211029 100644
--- a/docs/content/doc/help/seek-help.en-us.md
+++ b/docs/content/doc/help/seek-help.en-us.md
@@ -15,9 +15,18 @@ 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:
+
+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
+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
 
 If you found a bug, please create an [issue on GitHub](https://github.com/go-gitea/gitea/issues).
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 664a51731e..0000000000
--- 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: <GITEA_LFS_URL>/info/lfs/objects/batch                                                                                                              
-Check that you have proper access to the repository
-error: failed to push some refs to '<GIT_REPO_URL>'
-```
-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`.
-