diff --git a/docs/content/doc/advanced/cmd-embedded.en-us.md b/docs/content/doc/advanced/cmd-embedded.en-us.md index 3bd80d13483c4..5408d5786ed6c 100644 --- a/docs/content/doc/advanced/cmd-embedded.en-us.md +++ b/docs/content/doc/advanced/cmd-embedded.en-us.md @@ -26,8 +26,6 @@ inside the `custom` directory (see [Customizing Gitea]({{< relref "doc/advanced/ To obtain a copy of the embedded resources ready for editing, the `embedded` command from the CLI can be used from the OS shell interface. -**NOTE:** The embedded data extraction tool is included in Gitea versions 1.12 and above. - ## Listing resources To list resources embedded in Gitea's executable, use the following syntax: diff --git a/docs/content/doc/advanced/config-cheat-sheet.en-us.md b/docs/content/doc/advanced/config-cheat-sheet.en-us.md index 741c5f292cdf8..9de41cc3879be 100644 --- a/docs/content/doc/advanced/config-cheat-sheet.en-us.md +++ b/docs/content/doc/advanced/config-cheat-sheet.en-us.md @@ -289,8 +289,8 @@ The following configuration set `Content-Type: application/vnd.android.package-a - `OFFLINE_MODE`: **false**: Disables use of CDN for static files and Gravatar for profile pictures. - `DISABLE_ROUTER_LOG`: **false**: Mute printing of the router log. -- `CERT_FILE`: **https/cert.pem**: Cert file path used for HTTPS. When chaining, the server certificate must come first, then intermediate CA certificates (if any). From 1.11 paths are relative to `CUSTOM_PATH`. -- `KEY_FILE`: **https/key.pem**: Key file path used for HTTPS. From 1.11 paths are relative to `CUSTOM_PATH`. +- `CERT_FILE`: **https/cert.pem**: Cert file path used for HTTPS. When chaining, the server certificate must come first, then intermediate CA certificates (if any). +- `KEY_FILE`: **https/key.pem**: Key file path used for HTTPS. - `STATIC_ROOT_PATH`: **./**: Upper level of template and static files path. - `APP_DATA_PATH`: **data** (**/data/gitea** on docker): Default path for application data. - `STATIC_CACHE_TIME`: **6h**: Web browser cache time for static resources on `custom/`, `public/` and all uploaded avatars. Note that this cache is disabled when `RUN_MODE` is "dev". @@ -444,7 +444,7 @@ relation to port exhaustion. ## OpenID (`openid`) - `ENABLE_OPENID_SIGNIN`: **false**: Allow authentication in via OpenID. -- `ENABLE_OPENID_SIGNUP`: **! DISABLE\_REGISTRATION**: Allow registering via OpenID. +- `ENABLE_OPENID_SIGNUP`: **! DISABLE\_REGISTRATION && ENABLE\_OPENID\_SIGNIN**: Allow registering via OpenID. - `WHITELISTED_URIS`: **\**: If non-empty, list of POSIX regex patterns matching OpenID URI's to permit. - `BLACKLISTED_URIS`: **\**: If non-empty, list of POSIX regex patterns matching diff --git a/docs/content/doc/advanced/customizing-gitea.en-us.md b/docs/content/doc/advanced/customizing-gitea.en-us.md index cbb749412f039..92f5470a702e5 100644 --- a/docs/content/doc/advanced/customizing-gitea.en-us.md +++ b/docs/content/doc/advanced/customizing-gitea.en-us.md @@ -198,7 +198,7 @@ You can display STL file directly in Gitea by adding: 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 `$GITEA_CUSTOM/public/` folder. +You also need to download the content of the library [Madeleine.js](https://github.com/beige90/Madeleine.js) and place it under `$GITEA_CUSTOM/public/` folder. You should end-up with a folder structucture similar to: @@ -321,8 +321,20 @@ A full list of supported emoji's is at [emoji list](https://gitea.com/gitea/gite ## Customizing the look of Gitea -As of version 1.6.0 Gitea has built-in themes. The two built-in themes are, the default theme `gitea`, and a dark theme `arc-green`. To change the look of your Gitea install change the value of `DEFAULT_THEME` in the [ui](https://docs.gitea.io/en-us/config-cheat-sheet/#ui-ui) section of `app.ini` to another one of the available options. -As of version 1.8.0 Gitea also has per-user themes. The list of themes a user can choose from can be configured with the `THEMES` value in the [ui](https://docs.gitea.io/en-us/config-cheat-sheet/#ui-ui) section of `app.ini` (defaults to `gitea` and `arc-green`, light and dark respectively) +Gitea has two built-in themes, `gitea` (light) and `arc-green` (dark). +More themes are available, see [awesome-gitea](https://gitea.com/gitea/awesome-gitea#user-content-themes). + +- To change the default theme, change the value of `DEFAULT_THEME` in the [ui]({{< relref "doc/advanced/config-cheat-sheet.en-us.md" >}}#ui-ui) section of `app.ini` to one of the available options. + +- To make a theme selectable by users in their profile settings, add its name to the list of `THEMES` in your `app.ini`. + +- To add a custom 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`](https://gitea.artixlinux.org/artix/gitea-dark-blue). + Download the `.css` file and name it `theme-arc-blue.css`, and add it to your custom folder in `$GITEA_CUSTOM/public/css/`. + + Adapt your `app.ini` to make it the default theme or be user-selectable, as described above. ## Customizing fonts diff --git a/docs/content/doc/advanced/logging-documentation.en-us.md b/docs/content/doc/advanced/logging-documentation.en-us.md index 478b6418c6cbf..d941e5d691d01 100644 --- a/docs/content/doc/advanced/logging-documentation.en-us.md +++ b/docs/content/doc/advanced/logging-documentation.en-us.md @@ -15,8 +15,6 @@ menu: # Logging Configuration -The logging framework has been revamped in Gitea 1.9.0. - **Table of Contents** {{< toc >}} @@ -94,7 +92,7 @@ log using the value: `ROUTER = ,` ### The "Access" logger -The Access logger is a new logger for version 1.9. It provides a NCSA +The Access logger provides a NCSA Common Log compliant log format. It's highly configurable but caution should be taken when changing its template. The main benefit of this logger is that Gitea can now log accesses in a standard log format so diff --git a/docs/content/doc/developers/migrations.en-us.md b/docs/content/doc/developers/migrations.en-us.md index e432ea3b3ff0e..4eba60e463864 100644 --- a/docs/content/doc/developers/migrations.en-us.md +++ b/docs/content/doc/developers/migrations.en-us.md @@ -15,10 +15,10 @@ menu: # Migration Features -Complete migrations were introduced in Gitea 1.9.0. It defines two interfaces to support migrating +Currently, migrations from GitHub, Gitlab, Gogs, and other Gitea instances are implemented. +Gitea's migration feature defines two interfaces to support migrating repository data from other git host platforms to Gitea or, in the future, migrating Gitea data to other -git host platforms. -Currently, migrations from Github, Gitlab, and other Gitea instances are implemented. +git host platforms. First of all, Gitea defines some standard objects in packages [modules/migrations/base](https://github.com/go-gitea/gitea/tree/main/modules/migrations/base). They are `Repository`, `Milestone`, `Release`, `ReleaseAsset`, `Label`, `Issue`, `Comment`, `PullRequest`, `Reaction`, `Review`, `ReviewComment`. diff --git a/docs/content/doc/developers/oauth2-provider.md b/docs/content/doc/developers/oauth2-provider.md index efe78eed97659..7ed01bd3510f1 100644 --- a/docs/content/doc/developers/oauth2-provider.md +++ b/docs/content/doc/developers/oauth2-provider.md @@ -19,7 +19,7 @@ menu: {{< 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. +Gitea supports acting as an OAuth2 provider to allow third party applications to access its resources with the user's consent. ## Endpoints diff --git a/docs/content/doc/developers/integrations.en-us.md b/docs/content/doc/features/integrations.en-us.md similarity index 96% rename from docs/content/doc/developers/integrations.en-us.md rename to docs/content/doc/features/integrations.en-us.md index 8a111a3a8dc68..8d160abf55536 100644 --- a/docs/content/doc/developers/integrations.en-us.md +++ b/docs/content/doc/features/integrations.en-us.md @@ -7,7 +7,7 @@ toc: false draft: false menu: sidebar: - parent: "developers" + parent: "features" name: "Integrations" weight: 65 identifier: "integrations" diff --git a/docs/content/doc/developers/integrations.zh-tw.md b/docs/content/doc/features/integrations.zh-tw.md similarity index 96% rename from docs/content/doc/developers/integrations.zh-tw.md rename to docs/content/doc/features/integrations.zh-tw.md index 6991ec4ae8860..ced088b8eb063 100644 --- a/docs/content/doc/developers/integrations.zh-tw.md +++ b/docs/content/doc/features/integrations.zh-tw.md @@ -7,7 +7,7 @@ toc: false draft: false menu: sidebar: - parent: "developers" + parent: "features" name: "整合" weight: 65 identifier: "integrations" diff --git a/docs/content/doc/help/faq.en-us.md b/docs/content/doc/help/faq.en-us.md index 953aa9f0120de..5841f7d73a6df 100644 --- a/docs/content/doc/help/faq.en-us.md +++ b/docs/content/doc/help/faq.en-us.md @@ -22,33 +22,9 @@ For more help resources, check all [Support Options]({{< relref "doc/help/seek-h {{< toc >}} -## Difference between 1.x and 1.x.x downloads +## Configuration -Version 1.7.x will be used for this example. -**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. - -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) - -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. -[Example (requires login)](https://try.gitea.io/repo/migrate) - -To migrate from Gitlab to Gitea, you can use this non-affiliated tool: -https://github.com/loganinak/MigrateGitlabToGogs - -## Where does Gitea store what file +### Where does Gitea store what file - WorkPath - Environment variable `GITEA_WORK_DIR` @@ -72,132 +48,119 @@ https://github.com/loganinak/MigrateGitlabToGogs - `PATH` in `database` section of `app.ini` - Else `%(AppDataPath)/gitea.db` -## Not seeing a clone URL or the clone URL being incorrect +### SSHD vs built-in SSH -There are a few places that could make this show incorrectly. +`sshd` is the SSH server on most Unix systems. +It is by Gitea by default, by placing users' SSH keys in `/.ssh/authorized_keys` with a special `command=` option. +This setup only works well, when Gitea runs as a distinct user (i.e. `git`) so that the `authorized_keys` file can be exclusively managed by Gitea. -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 +Gitea also provides its own SSH server, for usage when SSHD is not available. -## File upload fails with: 413 Request Entity Too Large +### Adjusting your server for public/private use -This error occurs when the reverse proxy limits the file upload size. +#### Preventing spammers -See the [reverse proxy guide]({{< relref "doc/usage/reverse-proxies.en-us.md" >}}) for a solution with nginx. +There are multiple things you can combine to prevent spammers. -## Custom Templates not loading or working incorrectly +1. By whitelisting or blocklisting certain email domains +2. By only whitelisting certain domains with OpenID (see below) +3. Setting `ENABLE_CAPTCHA` to `true` in your `app.ini` and properly configuring `RECAPTCHA_SECRET` and `RECAPTCHA_SITEKEY` +4. 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 -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` +#### Only allow/block certain email domains -1. To find `CustomPath`, look for Custom File Root Path in Site Administration -> Configuration +You can configure `EMAIL_DOMAIN_WHITELIST` or `EMAIL_DOMAIN_BLOCKLIST` in your app.ini under `[service]` -- If that doesn't exist, you can try `echo $GITEA_CUSTOM` +#### Only allow/block certain OpenID providers -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. +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 -## Active user vs login prohibited user +#### Issue only users -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 +The current way to achieve this is to create/modify a user with a max repo creation limit of 0. +For organization repos, teams can be set up to only access the issue tracker. -## Setting up logging +#### Enable Fail2ban -- [Official Docs]({{< relref "doc/advanced/logging-documentation.en-us.md" >}}) +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 -## What is Swagger? +### How to add/use custom themes -[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" >}}) +See [here]({{< relref "doc/advanced/customizing-gitea.en-us.md" >}}#customizing-the-look-of-gitea). -[Swagger Example](https://try.gitea.io/api/swagger) +### How can I enable password reset -## Adjusting your server for public/private use +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. -### Preventing spammers +--- -There are multiple things you can combine to prevent spammers. +## Troubleshooting -1. By whitelisting or blocklisting certain email domains -2. By only whitelisting certain domains with OpenID (see below) -3. Setting `ENABLE_CAPTCHA` to `true` in your `app.ini` and properly configuring `RECAPTCHA_SECRET` and `RECAPTCHA_SITEKEY` -4. 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 +### How do I get debug logs? -### Only allow/block certain email domains +For setting up debug logging for bug reports, see [here]({{< relref "doc/advanced/logging-documentation.en-us.md" >}}#debugging-problems). -You can configure `EMAIL_DOMAIN_WHITELIST` or `EMAIL_DOMAIN_BLOCKLIST` in your app.ini under `[service]` +### Repo displayed as empty or pushed commits don't show up in the UI -### Only allow/block certain OpenID providers +Essentially this problem boils down to git hooks not running. +That could be due to: -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 +- You're pushing not through Gitea's SSH; see [SSH issues](#ssh-issues). +- The hooks not having the right path for gitea (ie. after moving installations. To fix this, click `Resynchronize pre-receive, update and post-receive hooks of all repositories` in the Gitea admin dashboard. +- The hooks aren't executable because they're on a `noexec` partition, or due to another security feature of the way Gitea is run. -### Issue only users +### Custom Templates not loading or working incorrectly -The current way to achieve this is to create/modify a user with a max repo creation limit of 0. +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` -### Restricted users +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-what-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. -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.\_\_ +### Not seeing a clone URL or the clone URL being incorrect -Example use case: A company runs a Gitea instance that requires login. Most repos are public (accessible/browsable by all co-workers). +There are a few places that could make this show incorrectly. -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. +1. If using a reverse proxy, make sure you have followed the correct instructions 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` -### Enable Fail2ban +If certain clone options aren't showing up (HTTP/S or SSH), the following options can be checked in your `app.ini` -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 +`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 -## How to add/use custom themes +### File upload fails with: 413 Request Entity Too Large -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) +This error occurs when the reverse proxy limits the file upload size. -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` +See the [reverse proxy guide]({{< relref "doc/usage/reverse-proxies.en-us.md" >}}) for a solution with nginx. -## SSHD vs built-in SSH +### Why Are Emoji Broken On MySQL -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. +Unfortunately MySQL's `utf8` charset does not completely allow all possible UTF-8 characters, in particular Emoji. +They created a new charset and collation called `utf8mb4` that allows for emoji to be stored but tables which use +the `utf8` charset, and connections which use the `utf8` charset will not use this. -## Gitea is running slow +Please run `gitea convert`, or run `ALTER DATABASE database_name CHARACTER SET utf8mb4 COLLATE utf8mb4_general_ci;` +for the database_name and run `ALTER TABLE table_name CONVERT TO CHARACTER SET utf8mb4 COLLATE utf8mb4_general_ci;` +for each table in the database. -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` +You will also need to change the app.ini database charset to `CHARSET=utf8mb4`. -## Can't create repositories/files +### 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) +See [AppDataPath and RepoRootPath](#where-does-gitea-store-what-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 +### SSH issues If you cannot reach repositories over `ssh`, but `https` works fine, consider looking into the following. @@ -212,11 +175,12 @@ If this is unexpected, please log in with password and setup Gitea under another ``` 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. +You can try to run `Update the '.ssh/authorized_keys' file with Gitea SSH keys.` in the admin dashboard. 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 +#### SSH Common Errors ``` Permission denied (publickey). @@ -261,23 +225,8 @@ In this case, look into the following settings: - 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 +### LFS Issues For issues concerning LFS data upload @@ -292,15 +241,72 @@ By default, your LFS token will expire after 20 minutes. If you have a slow conn You may want to set this value to `60m` or `120m`. -## How can I create users before starting Gitea +If git reports the following when pushing, you likely didn't push through Gitea, see [SSH issues](#ssh-issues). +``` +error: exit status 127, message: bash: git-lfs-authenticate: command not found (try: 5/6) +``` -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. +### Gitea is running slow -## How can I enable password reset +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` -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. +### Issues after updating + +Please always check the release notes / [changelog](https://github.com/go-gitea/gitea/blob/main/CHANGELOG.md) for breaking changes; we regularly have breaking changes on minor releases! + +#### Upgrade errors with MySQL + +- If you are receiving errors on upgrade of Gitea using MySQL that read: + + > `ORM engine initialization failed: migrate: do migrate: Error: 1118: Row size too large...` + + Please run `gitea convert` or run `ALTER TABLE table_name ROW_FORMAT=dynamic;` for each table in the database. + + The underlying problem is that the space allocated for indices by the default row format + is too small. Gitea requires that the `ROWFORMAT` for its tables is `DYNAMIC`. + +- If you are receiving an error line containing `Error 1071: Specified key was too long; max key length is 1000 bytes...` + then you are attempting to run Gitea on tables which use the ISAM engine. While this may have worked by chance in previous versions of Gitea, it has never been officially supported and + you must use InnoDB. You should run `ALTER TABLE table_name ENGINE=InnoDB;` for each table in the database. + If you are using MySQL 5, another possible fix is + ```mysql + SET GLOBAL innodb_file_format=Barracuda; + SET GLOBAL innodb_file_per_table=1; + SET GLOBAL innodb_large_prefix=1; + ``` + +--- + +## Usage + +### How to migrate from Gogs/GitHub/etc. to Gitea + +To migrate repositories including issues, pulls, releases etc, Gitea has built in support for various git forges (GitHub, Gitlab, Gitea, Gogs). +[Example (requires login)](https://try.gitea.io/repo/migrate) + +To migrate an entire Gogs installation 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) + +### User flags: active, prohibited, restricted + +- An "active" has activated their account via email. + +- A "login prohibited" user is a user that is not allowed to log in to Gitea anymore. + +- 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. -## How can a user's password be changed + Example use case: A company runs a Gitea instance that requires login. Most repos are public (accessible/browsable 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. + +### 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 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. @@ -311,45 +317,59 @@ There is no setting for password resets. It is enabled when a [mail service]({{< - 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" >}}). -## 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. +### Missing releases after migrating repository with tags -## Upgrade errors with MySQL - -If you are receiving errors on upgrade of Gitea using MySQL that read: +To migrate an repository _with_ all tags, you need to do two things: -> `ORM engine initialization failed: migrate: do migrate: Error: 1118: Row size too large...` +- Push tags to the repository: -Please run `gitea convert` or run `ALTER TABLE table_name ROW_FORMAT=dynamic;` for each table in the database. +``` + git push --tags +``` -The underlying problem is that the space allocated for indices by the default row format -is too small. Gitea requires that the `ROWFORMAT` for its tables is `DYNAMIC`. +- (Re-)sync tags of all repositories within Gitea: -If you are receiving an error line containing `Error 1071: Specified key was too long; max key length is 1000 bytes...` -then you are attempting to run Gitea on tables which use the ISAM engine. While this may have worked by chance in previous versions of Gitea, it has never been officially supported and -you must use InnoDB. You should run `ALTER TABLE table_name ENGINE=InnoDB;` for each table in the database. -If you are using MySQL 5, another possible fix is -```mysql -SET GLOBAL innodb_file_format=Barracuda; -SET GLOBAL innodb_file_per_table=1; -SET GLOBAL innodb_large_prefix=1; +``` +gitea admin repo-sync-releases ``` -## Why Are Emoji Broken On MySQL +### Why are Emoji displaying only as placeholders or in monochrome -Unfortunately MySQL's `utf8` charset does not completely allow all possible UTF-8 characters, in particular Emoji. -They created a new charset and collation called `utf8mb4` that allows for emoji to be stored but tables which use -the `utf8` charset, and connections which use the `utf8` charset will not use this. +Gitea requires the system or browser to have one of the supported Emoji fonts installed, which are Apple Color Emoji, Segoe UI Emoji, Segoe UI Symbol, Noto Color Emoji and Twemoji Mozilla. Generally, the operating system should already provide one of these fonts, but especially on Linux, it may be necessary to install them manually. -Please run `gitea convert`, or run `ALTER DATABASE database_name CHARACTER SET utf8mb4 COLLATE utf8mb4_general_ci;` -for the database_name and run `ALTER TABLE table_name CONVERT TO CHARACTER SET utf8mb4 COLLATE utf8mb4_general_ci;` -for each table in the database. +--- -You will also need to change the app.ini database charset to `CHARSET=utf8mb4`. +## Misc -## Why are Emoji displaying only as placeholders or in monochrome +### To which Gitea version is this documentation referring? -Gitea requires the system or browser to have one of the supported Emoji fonts installed, which are Apple Color Emoji, Segoe UI Emoji, Segoe UI Symbol, Noto Color Emoji and Twemoji Mozilla. Generally, the operating system should already provide one of these fonts, but especially on Linux, it may be necessary to install them manually. +Currently, this documentation is always referring to the latest development on the `main` branch. +We're looking provide separate documentation per release, see [this issue](https://github.com/go-gitea/gitea/issues/15279) if you want to help with that. + +### Is there end-user documentation available? + +Currently not, but Codeberg provides some helpful docs [here](https://docs.codeberg.org/). + +### 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! + +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. + +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. + +### Translation is incorrect/how to add more translations + +See [here]({{< relref "doc/translation/localization.en-us.md" >}}) on how to add or change translations. + +### What is Swagger? + +[Swagger](https://swagger.io/) (or OpenAPI) is a standard Gitea uses for its API documentation. +This UI is available at `/api/swagger` ([example](https://try.gitea.io/api/swagger)), +but it can be disabled by configuration]({{< relref "doc/advanced/config-cheat-sheet.en-us.md" >}}#api-api). +For more information on the API, refer to Gitea's [API docs]({{< relref "doc/developers/api-usage.en-us.md" >}}) diff --git a/docs/content/doc/help/seek-help.en-us.md b/docs/content/doc/help/seek-help.en-us.md index 1c01f94ae86be..518efe7bcfc6d 100644 --- a/docs/content/doc/help/seek-help.en-us.md +++ b/docs/content/doc/help/seek-help.en-us.md @@ -18,18 +18,20 @@ menu: - [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: +**NOTE:** When asking for support, please always provide the following data, so that the person helping has all the info they need. This increases your chances of getting help significantly. -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 +1. The `gitea.log` (and any other appropriate log files for the situation) + * Learn [here]({{< relref "doc/advanced/logging-documentation.en-us.md" >}}#debugging-problems) how to enable debug logging to get the most useful logs. + * e.g. If the error is related to the database, the `xorm.log` might be helpful. +2. Your `app.ini` (with any sensitive data scrubbed as necessary) 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. + * 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). +Please search for existing issues first! ## Chinese Support diff --git a/docs/content/doc/installation/on-cloud-provider.md b/docs/content/doc/installation/on-cloud-provider.md index c61c042af2424..0aaf328e4f007 100644 --- a/docs/content/doc/installation/on-cloud-provider.md +++ b/docs/content/doc/installation/on-cloud-provider.md @@ -39,6 +39,6 @@ To deploy it have a look at https://www.vultr.com/marketplace/apps/gitea. ## DigitalOcean -[DigitalOcean](https://www.digitalocean.com) has gitea as droplet in his marketplace. +[DigitalOcean](https://www.digitalocean.com) has preconfigured Gitea as droplet in their marketplace. Just create a new [Gitea Droplet](https://marketplace.digitalocean.com/apps/gitea). diff --git a/docs/content/doc/features/localization.en-us.md b/docs/content/doc/translation/localization.en-us.md similarity index 70% rename from docs/content/doc/features/localization.en-us.md rename to docs/content/doc/translation/localization.en-us.md index a5b7a52f89891..a3c2bf20a9128 100644 --- a/docs/content/doc/features/localization.en-us.md +++ b/docs/content/doc/translation/localization.en-us.md @@ -7,7 +7,7 @@ toc: false draft: false menu: sidebar: - parent: "features" + parent: "translation" name: "Localization" weight: 20 identifier: "localization" @@ -21,6 +21,12 @@ For changes to an **English** translation, a pull request can be made that chang the [english locale](https://github.com/go-gitea/gitea/blob/master/options/locale/locale_en-US.ini). For changes to a **non-English** translation, refer to the Crowdin project above. +Please don't submit non-English translation updates via GitHub pull requests, as they will be overwritten with the translations in Crowdin. + +## Adding a new translation + +If you want to add an entirely new translation, please [contact us]({{< relref "doc/help/seek-help" >}}) so we can set that up in Crowdin. +Please understand that we only add new translations, if there is a volunteer for maintaining this translation with future changes. ## Supported Languages diff --git a/docs/content/doc/features/localization.zh-cn.md b/docs/content/doc/translation/localization.zh-cn.md similarity index 89% rename from docs/content/doc/features/localization.zh-cn.md rename to docs/content/doc/translation/localization.zh-cn.md index 6a6f637326652..56ca40ce11c42 100644 --- a/docs/content/doc/features/localization.zh-cn.md +++ b/docs/content/doc/translation/localization.zh-cn.md @@ -7,7 +7,7 @@ toc: false draft: false menu: sidebar: - parent: "features" + parent: "translation" name: "本地化" weight: 20 identifier: "localization" diff --git a/docs/content/doc/features/localization.zh-tw.md b/docs/content/doc/translation/localization.zh-tw.md similarity index 97% rename from docs/content/doc/features/localization.zh-tw.md rename to docs/content/doc/translation/localization.zh-tw.md index e1000636069ab..9af571f97667a 100644 --- a/docs/content/doc/features/localization.zh-tw.md +++ b/docs/content/doc/translation/localization.zh-tw.md @@ -7,7 +7,7 @@ toc: false draft: false menu: sidebar: - parent: "features" + parent: "translation" name: "在地化" weight: 20 identifier: "localization" diff --git a/docs/content/doc/usage/command-line.en-us.md b/docs/content/doc/usage/command-line.en-us.md index 0bc8d70fdb53a..5bb7b3056b368 100644 --- a/docs/content/doc/usage/command-line.en-us.md +++ b/docs/content/doc/usage/command-line.en-us.md @@ -77,10 +77,17 @@ Admin operations: - One of `--id`, `--username` or `--email` is required. If more than one is provided then all have to match. - 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` + - `create`: + - Options: + - `--username value`: Username. Required. + - `--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. diff --git a/docs/content/doc/usage/reverse-proxies.en-us.md b/docs/content/doc/usage/reverse-proxies.en-us.md index 5f1e6685ecfb1..cee22f23ccdbd 100644 --- a/docs/content/doc/usage/reverse-proxies.en-us.md +++ b/docs/content/doc/usage/reverse-proxies.en-us.md @@ -46,6 +46,9 @@ server { location /git/ { # Note: Trailing slash proxy_pass http://localhost:3000/; # Note: Trailing slash } + location = /git { + return 308 /git/ + } } ``` diff --git a/docs/content/doc/usage/template-repositories.md b/docs/content/doc/usage/template-repositories.md index 24fdf28ee091f..8609256d25d9e 100644 --- a/docs/content/doc/usage/template-repositories.md +++ b/docs/content/doc/usage/template-repositories.md @@ -19,7 +19,7 @@ menu: {{< 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. +Gitea has template repositories, with support for 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. diff --git a/docs/content/page/index.en-us.md b/docs/content/page/index.en-us.md index a5204e17dff78..38430912d9a08 100644 --- a/docs/content/page/index.en-us.md +++ b/docs/content/page/index.en-us.md @@ -288,3 +288,4 @@ Windows, on architectures like amd64, i386, ARM, PowerPC, and others. ## Software and Service Support - [Drone](https://github.com/drone/drone) (CI) +- more integrations are listed at [awesome-gitea](https://gitea.com/gitea/awesome-gitea)