From 16fe297a74fca9d7e73d28a86b1596522bb5ea47 Mon Sep 17 00:00:00 2001 From: John Olheiser <42128690+jolheiser@users.noreply.github.com> Date: Fri, 12 Apr 2019 21:46:52 -0500 Subject: [PATCH] FAQ (#6524) --- docs/content/doc/help/faq.en-us.md | 258 ++++++++++++++++++ docs/content/doc/help/seek-help.en-us.md | 11 +- .../content/doc/help/troubleshooting.en-us.md | 96 ------- 3 files changed, 268 insertions(+), 97 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 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: /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`. 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: /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`. -