You also need to download the content of the library [Madeleine.js](https://jinjunho.github.io/Madeleine.js/) and place it under `custom/public/` folder.
You should end-up with a folder structucture similar to:
```
custom/templates
-- custom
@ -289,10 +301,12 @@ currently there are `{Name}` (name of repository), `{Description}`, `{CloneURL.S
### Reactions
To change reaction emoji's you can set allowed reactions at app.ini
This supports rendering of whole files. If you want to render code blocks in markdown you would need to do something with javascript. See some examples on the [Customizing Gitea](../customizing-gitea) page.
@ -29,7 +33,7 @@ This supports rendering of whole files. If you want to render code blocks in mar
In order to get file rendering through external binaries, their associated packages must be installed.
If you're using a Docker image, your `Dockerfile` should contain something along this lines:
```
```docker
FROM gitea/gitea:{{<version>}}
[...]
@ -49,7 +53,7 @@ RUN pip3 install jupyter docutils
add one `[markup.XXXXX]` section per external renderer on your custom `app.ini`:
| `.FallbackSubject` | string | Always | A default subject line. See Below. |
| `.Subject` | string | Only in body | The _subject_, once resolved. |
| `.Body` | string | Always | The message of the issue, pull request or comment, parsed from Markdown into HTML and sanitized. Do not confuse with the _mail body_. |
| `.Link` | string | Always | The address of the originating issue, pull request or comment. |
| `.Issue` | models.Issue | Always | The issue (or pull request) originating the notification. To get data specific to a pull request (e.g. `HasMerged`), `.Issue.PullRequest` can be used, but care should be taken as this field will be `nil` if the issue is *not* a pull request. |
| `.Issue` | models.Issue | Always | The issue (or pull request) originating the notification. To get data specific to a pull request (e.g. `HasMerged`), `.Issue.PullRequest` can be used, but care should be taken as this field will be `nil` if the issue is _not_ a pull request. |
| `.Comment` | models.Comment | If applicable | If the notification is from a comment added to an issue or pull request, this will contain the information about the comment. |
| `.IsPull` | bool | Always | `true` if the mail notification is associated with a pull request (i.e. `.Issue.PullRequest` is not `nil`). |
| `.Repo` | string | Always | Name of the repository, including owner name (e.g. `mike/stuff`) |
@ -115,19 +117,19 @@ Please refer to the linked documentation for details about its syntax.
The _subject_ is built using the following steps:
* A template is selected according to the type of notification and to what templates are present.
* The template is parsed and resolved (e.g. `{{.Issue.Index}}` is converted to the number of the issue
- A template is selected according to the type of notification and to what templates are present.
- The template is parsed and resolved (e.g. `{{.Issue.Index}}` is converted to the number of the issue
or pull request).
* All space-like characters (e.g. `TAB`, `LF`, etc.) are converted to normal spaces.
* All leading, trailing and redundant spaces are removed.
* The string is truncated to its first 256 runes (characters).
- All space-like characters (e.g. `TAB`, `LF`, etc.) are converted to normal spaces.
- All leading, trailing and redundant spaces are removed.
- The string is truncated to its first 256 runes (characters).
If the end result is an empty string, **or** no subject template was available (i.e. the selected template
did not include a subject part), Gitea's **internal default** will be used.
The internal default (fallback) subject is the equivalent of:
As of v1.8.0 of Gitea, if using basic authentication with the API and your user has two factor authentication enabled, you'll need to send an additional header that contains the one time password (6 digit rotating token). An example of the header is `X-Gitea-OTP: 123456` where `123456` is where you'd place the code from your authenticator. Here is how the request would look like in curl:
```
```sh
$ curl -H "X-Gitea-OTP: 123456" --request GET --url https://yourusername:yourpassword@gitea.your.host/api/v1/users/yourusername/tokens
```
@ -104,5 +105,5 @@ The API allows admin users to sudo API requests as another user. Simply add eith
@ -127,9 +129,9 @@ See `make help` for all available `make` targets. Also see [`.drone.yml`](https:
To run and continously rebuild when source files change:
````bash
```bash
make watch
````
```
On macOS, watching all backend source files may hit the default open files limit which can be increased via `ulimit -n 12288` for the current shell or in your shell startup file for all future shells.
Gitea supports acting as an OAuth2 provider to allow third party applications to access its resources with the user's consent. This feature is available since release 1.8.0.
**Table of Contents**
## Endpoints
{{<toc>}}
Gitea supports acting as an OAuth2 provider to allow third party applications to access its resources with the user's consent. This feature is available since release 1.8.0.
At the moment Gitea only supports the [**Authorization Code Grant**](https://tools.ietf.org/html/rfc6749#section-1.3.1) standard with additional support of the [Proof Key for Code Exchange (PKCE)](https://tools.ietf.org/html/rfc7636) extension.
To use the Authorization Code Grant as a third party application it is required to register a new application via the "Settings" (`/user/settings/applications`) section of the settings.
## Scopes
@ -44,49 +44,49 @@ Currently Gitea does not support scopes (see [#4300](https://github.com/go-gitea
1. Redirect to user to the authorization endpoint in order to get his/her consent for accessing the resources:
The `CLIENT_ID` can be obtained by registering an application in the settings. The `STATE` is a random string that will be send back to your application after the user authorizes. The `state` parameter is optional but should be used to prevent CSRF attacks.
The `CLIENT_ID` can be obtained by registering an application in the settings. The `STATE` is a random string that will be send back to your application after the user authorizes. The `state` parameter is optional but should be used to prevent CSRF attacks.
The user will now be asked to authorize your application. If they authorize it, the user will be redirected to the `REDIRECT_URL`, for example:
The user will now be asked to authorize your application. If they authorize it, the user will be redirected to the `REDIRECT_URL`, for example:
2. Using the provided `code` from the redirect, you can request a new application and refresh token. The access token endpoints accepts POST requests with `application/json` and `application/x-www-form-urlencoded` body, for example:
```curl
POST https://[YOUR-GITEA-URL]/login/oauth/access_token
```
```curl
POST https://[YOUR-GITEA-URL]/login/oauth/access_token
The `CLIENT_SECRET` is the unique secret code generated for this application. Please note that the secret will only be visible after you created/registered the application with Gitea and cannot be recovered. If you lose the secret you must regenerate the secret via the application's settings.
The `REDIRECT_URI` in the `access_token` request must match the `REDIRECT_URI` in the `authorize` request.
The `CLIENT_SECRET` is the unique secret code generated for this application. Please note that the secret will only be visible after you created/registered the application with Gitea and cannot be recovered. If you lose the secret you must regenerate the secret via the application's settings.
The `REDIRECT_URI` in the `access_token` request must match the `REDIRECT_URI` in the `authorize` request.
3. Use the `access_token` to make [API requests](https://docs.gitea.io/en-us/api-usage#oauth2) to access the user's resources.
@ -197,18 +227,22 @@ configure this, set the fields below:
userPassword: secure password
passwordExpirationTime: 20380119031407Z
nsIdleTimeout: 0
```
```
- Import the LDIF (change localhost to an IPA server if needed). A prompt for
Directory Manager password will be presented:
```
```sh
ldapmodify -h localhost -p 389 -x -D \
"cn=Directory Manager" -W -f gitea.ldif
```
- Add an IPA group for gitea\_users :
```
```
- Add an IPA group for gitea_users :
```sh
ipa group-add --desc="Gitea Users" gitea_users
```
```
- Note: For errors about IPA credentials, run `kinit admin` and provide the
domain admin account password.
@ -224,13 +258,15 @@ Before activating SSPI single sign-on authentication (SSO) you have to prepare y
- Create a separate user account in active directory, under which the `gitea.exe` process will be running (eg. `user` under domain `domain.local`):
- Create a service principal name for the host where `gitea.exe` is running with class `HTTP`:
- Start `Command Prompt` or `PowerShell` as a priviledged domain user (eg. Domain Administrator)
- Run the command below, replacing `host.domain.local` with the fully qualified domain name (FQDN) of the server where the web application will be running, and `domain\user` with the name of the account created in the previous step:
```
```sh
setspn -A HTTP/host.domain.local domain\user
```
- Sign in (*sign out if you were already signed in*) with the user created
- Sign in (_sign out if you were already signed in_) with the user created
- Make sure that `ROOT_URL` in the `[server]` section of `custom/conf/app.ini` is the fully qualified domain name of the server where the web application will be running - the same you used when creating the service principal name (eg. `host.domain.local`)
title: "Gitea compared to other Git hosting options"
slug: "comparison"
weight: 5
toc: true
toc: false
draft: false
menu:
sidebar:
@ -15,23 +15,27 @@ menu:
# Gitea compared to other Git hosting options
**Table of Contents**
{{<toc>}}
To help decide if Gitea is suited for your needs, here is how it compares to other Git self hosted options.
Be warned that we don't regularly check for feature changes in other products, so this list may be outdated. If you find anything that needs to be updated in the table below, please report it in an [issue on GitHub](https://github.com/go-gitea/gitea/issues).
_Symbols used in table:_
* _✓ - supported_
- _✓ - supported_
* _⁄ - supported with limited functionality_
- _⁄ - supported with limited functionality_
* _✘ - unsupported_
- _✘ - unsupported_
#### General Features
## General Features
| Feature | Gitea | Gogs | GitHub EE | GitLab CE | GitLab EE | BitBucket | RhodeCode CE |
## 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" >}})
@ -79,24 +85,29 @@ If certain clone options aren't showing up (HTTP/S or SSH), the following option
`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`
- 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
[Swagger](https://swagger.io/) is what Gitea uses for its API.
All Gitea instances have the built-in API, though it can be disabled by setting `ENABLE_SWAGGER` to `false` in the `api` section of your `app.ini`
For more information, refer to Gitea's [API docs]({{< relref "doc/developers/api-usage.en-us.md" >}})
@ -106,6 +117,7 @@ For more information, refer to Gitea's [API docs]({{< relref "doc/developers/api
## Adjusting your server for public/private use
### Preventing spammers
There are multiple things you can combine to prevent spammers.
1. By only whitelisting certain domains with OpenID (see below)
@ -113,28 +125,32 @@ There are multiple things you can combine to prevent spammers.
3. Settings `DISABLE_REGISTRATION` to `true` and creating new users via the [CLI]({{< relref "doc/usage/command-line.en-us.md" >}}), [API]({{< relref "doc/developers/api-usage.en-us.md" >}}), or Gitea's Admin UI
### Only allow certain email domains
You can configure `EMAIL_DOMAIN_WHITELIST` in your app.ini under `[service]`
### Only allow/block certain OpenID providers
You can configure `WHITELISTED_URIS` or `BLACKLISTED_URIS` under `[openid]` in your `app.ini`
**NOTE:** whitelisted takes precedence, so if it is non-blank then blacklisted is ignored
### Issue only users
The current way to achieve this is to create/modify a user with a max repo creation limit of 0.
### Restricted users
Restricted users are limited to a subset of the content based on their organization/team memberships and collaborations, ignoring the public flag on organizations/repos etc.__
Restricted users are limited to a subset of the content based on their organization/team memberships and collaborations, ignoring the public flag on organizations/repos etc.\_\_
Example use case: A company runs a Gitea instance that requires login. Most repos are public (accessible/browseable by all co-workers).
At some point, a customer or third party needs access to a specific repo and only that repo. Making such a customer account restricted and granting any needed access using team membership(s) and/or collaboration(s) is a simple way to achieve that without the need to make everything private.
### Enable Fail2ban
Use [Fail2Ban]({{< relref "doc/usage/fail2ban-setup.en-us.md" >}}) to monitor and stop automated login attempts or other malicious behavior based on log patterns
## How to add/use custom themes
Gitea supports two official themes right now, `gitea` and `arc-green` (`light` and `dark` respectively)
To add your own theme, currently the only way is to provide a complete theme (not just color overrides)
@ -143,15 +159,18 @@ Name the `.css` file `theme-arc-blue.css` and add it to your custom folder in `c
Allow users to use it by adding `arc-blue` to the list of `THEMES` in your `app.ini`
## SSHD vs built-in SSH
SSHD is the built-in SSH server on most Unix systems.
Gitea also provides its own SSH server, for usage when SSHD is not available.
## Gitea is running slow
The most common culprit for this is loading federated avatars.
This can be turned off by setting `ENABLE_FEDERATED_AVATAR` to `false` in your `app.ini`
Another option that may need to be changed is setting `DISABLE_GRAVATAR` to `true` in your `app.ini`
## Can't create repositories/files
Make sure that Gitea has sufficient permissions to write to its home directory and data directory.
See [AppDataPath and RepoRootPath](#where-does-gitea-store-x-file)
@ -160,22 +179,26 @@ See [AppDataPath and RepoRootPath](#where-does-gitea-store-x-file)
Which makes all other paths non-writeable to Gitea.
## Translation is incorrect/how to add more translations
Our translations are currently crowd-sourced on our [Crowdin project](https://crowdin.com/project/gitea)
Whether you want to change a translation or add a new one, it will need to be there as all translations are overwritten in our CI via the Crowdin integration.
## Hooks aren't running
If Gitea is not running hooks, a common cause is incorrect setup of SSH keys.
See [SSH Issues](#ssh-issues) for more information.
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.
@ -196,20 +219,20 @@ fatal: Could not read from remote repository.
This error signifies that the server rejected a log in attempt, check the
following things:
* On the client:
* Ensure the public and private ssh keys are added to the correct Gitea user.
* Make sure there are no issues in the remote url. In particular, ensure the name of the
- On the client:
- Ensure the public and private ssh keys are added to the correct Gitea user.
- Make sure there are no issues in the remote url. In particular, ensure the name of the
git user (before the `@`) is spelled correctly.
* Ensure public and private ssh keys are correct on client machine.
* On the server:
* Make sure the repository exists and is correctly named.
* Check the permissions of the `.ssh` directory in the system user's home directory.
* Verify that the correct public keys are added to `.ssh/authorized_keys`.
- Ensure public and private ssh keys are correct on client machine.
- On the server:
- Make sure the repository exists and is correctly named.
- Check the permissions of the `.ssh` directory in the system user's home directory.
- Verify that the correct public keys are added to `.ssh/authorized_keys`.
Try to run `Rewrite '.ssh/authorized_keys' file (for Gitea SSH keys)` on the
Gitea admin panel.
* Read Gitea logs.
* Read /var/log/auth (or similar).
* Check permissions of repositories.
- Read Gitea logs.
- Read /var/log/auth (or similar).
- Check permissions of repositories.
The following is an example of a missing public SSH key where authentication
succeeded, but some other setting is preventing SSH from reaching the correct
@ -224,26 +247,28 @@ and the repository exists.
In this case, look into the following settings:
* On the server:
* Make sure that the `git` system user has a usable shell set
* Verify this with `getent passwd git | cut -d: -f7`
*`usermod` or `chsh` can be used to modify this.
* Ensure that the `gitea serv` command in `.ssh/authorized_keys` uses the
- On the server:
- Make sure that the `git` system user has a usable shell set
- Verify this with `getent passwd git | cut -d: -f7`
-`usermod` or `chsh` can be used to modify this.
- Ensure that the `gitea serv` command in `.ssh/authorized_keys` uses the
correct configuration file.
## Missing releases after migrating repository with tags
To migrate an repository *with* all tags, you need to do two things:
To migrate an repository _with_ all tags, you need to do two things:
- Push tags to the repository:
* Push tags to the repository:
```
git push --tags
```
```
* (Re-)sync tags of all repositories within Gitea:
```
gitea admin repo-sync-releases
```
- (Re-)sync tags of all repositories within Gitea:
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`.
## How can I create users before starting Gitea
Gitea provides a sub-command `gitea migrate` to initialize the database, after which you can use the [admin CLI commands]({{< relref "doc/usage/command-line.en-us.md#admin" >}}) to add users like normal.
## How can I enable password reset
There is no setting for password resets. It is enabled when a [mail service]({{< relref "doc/usage/email-setup.en-us.md" >}}) is configured, and disabled otherwise.
## How can a user's password be changed
- As an **admin**, you can change any user's password (and optionally force them to change it on next login)...
- By navigating to your `Site Administration -> User Accounts` page and editing a user.
- By using the [admin CLI commands]({{< relref "doc/usage/command-line.en-us.md#admin" >}}).
@ -276,6 +305,7 @@ There is no setting for password resets. It is enabled when a [mail service]({{<
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.
@ -21,6 +21,8 @@ Database instance can be on same machine as Gitea (local database setup), or on
Note: All steps below requires that the database engine of your choice is installed on your system. For remote database setup, install the server part on database instance and client part on your Gitea server. In addition, make sure you use same engine version for both server and client for some engine features to work. For security reason, protect `root` (MySQL) or `postgres` (PostgreSQL) database superuser with secure password. The steps assumes that you run Linux for both database and Gitea servers.
**Table of Contents**
{{<toc>}}
## MySQL
@ -30,6 +32,7 @@ Note: All steps below requires that the database engine of your choice is instal
```ini
bind-address = 203.0.113.3
```
2. On database instance, login to database console as root:
```
@ -58,7 +61,7 @@ Note: All steps below requires that the database engine of your choice is instal
Replace username and password above as appropriate.
4. Create database with UTF-8 charset and collation. Make sure to use `utf8mb4` charset instead of `utf8` as the former supports all Unicode characters (including emojis) beyond *Basic Multilingual Plane*. Also, collation chosen depending on your expected content. When in doubt, use either `unicode_ci` or `general_ci`.
4. Create database with UTF-8 charset and collation. Make sure to use `utf8mb4` charset instead of `utf8` as the former supports all Unicode characters (including emojis) beyond _Basic Multilingual Plane_. Also, collation chosen depending on your expected content. When in doubt, use either `unicode_ci` or `general_ci`.
```sql
CREATE DATABASE giteadb CHARACTER SET 'utf8mb4' COLLATE 'utf8mb4_unicode_ci';
@ -249,14 +252,12 @@ The PostgreSQL driver used by Gitea supports two-way TLS. In two-way TLS, both d
You should be prompted to enter password for the database user, and then be connected to the database.
### MySQL
While the MySQL driver used by Gitea also supports two-way TLS, Gitea currently supports only one-way TLS. See issue #10828 for details.
In one-way TLS, the database client verifies the certificate sent from server during the connection handshake, and the server assumes that the connected client is legitimate, since client certificate verification doesn't take place.
1. On the database instance, place the following credentials:
@ -23,6 +23,8 @@ This reference setup guides users through the setup based on `docker-compose`, b
of `docker-compose` is out of scope of this documentation. To install `docker-compose` itself, follow
the official [install instructions](https://docs.docker.com/compose/install/).
**Table of Contents**
{{<toc>}}
## Basics
@ -61,7 +63,7 @@ services:
- "222:22"
```
## Custom port
## Ports
To bind the integrated openSSH daemon and the webserver on a different port, adjust
the port section. It's common to just change the host port and keep the ports within
@ -95,7 +97,9 @@ services:
+ - "2221:22"
```
## MySQL database
## Databases
### MySQL database
To start Gitea in combination with a MySQL database, apply these changes to the
`docker-compose.yml` file created above.
@ -146,7 +150,7 @@ services:
+ - ./mysql:/var/lib/mysql
```
## PostgreSQL database
### PostgreSQL database
To start Gitea in combination with a PostgreSQL database, apply these changes to
the `docker-compose.yml` file created above.
@ -233,7 +237,7 @@ services:
MySQL or PostgreSQL containers will need to be created separately.
## Start
## Startup
To start this setup based on `docker-compose`, execute `docker-compose up -d`,
to launch Gitea in the background. Using `docker-compose ps` will show if Gitea
@ -245,42 +249,42 @@ and kill the containers. The volumes will still exist.
Notice: if using a non-3000 port on http, change app.ini to match
`LOCAL_ROOT_URL = http://localhost:3000/`.
## Install
## Installation
After starting the Docker setup via `docker-compose`, Gitea should be available using a
favorite browser to finalize the installation. Visit http://server-ip:3000 and follow the
installation wizard. If the database was started with the `docker-compose` setup as
documented above, please note that `db` must be used as the database hostname.
## Environments variables
## Environment variables
You can configure some of Gitea's settings via environment variables:
(Default values are provided in **bold**)
*`APP_NAME`: **"Gitea: Git with a cup of tea"**: Application name, used in the page title.
*`RUN_MODE`: **prod**: Application run mode, affects performance and debugging. Either "dev", "prod" or "test".
*`DOMAIN`: **localhost**: Domain name of this server, used for the displayed http clone URL in Gitea's UI.
*`SSH_DOMAIN`: **localhost**: Domain name of this server, used for the displayed ssh clone URL in Gitea's UI. If the install page is enabled, SSH Domain Server takes DOMAIN value in the form (which overwrite this setting on save).
*`SSH_PORT`: **22**: SSH port displayed in clone URL.
*`SSH_LISTEN_PORT`: **%(SSH\_PORT)s**: Port for the built-in SSH server.
*`DISABLE_SSH`: **false**: Disable SSH feature when it's not available. If you want to disable SSH feature, you should set SSH port to `0` when installing Gitea.
*`HTTP_PORT`: **3000**: HTTP listen port.
*`ROOT_URL`: **""**: Overwrite the automatically generated public URL. This is useful if the internal and the external URL don't match (e.g. in Docker).
*`DB_TYPE`: **sqlite3**: The database type in use \[mysql, postgres, mssql, sqlite3\].
*`DB_HOST`: **localhost:3306**: Database host address and port.
*`DB_NAME`: **gitea**: Database name.
*`DB_USER`: **root**: Database username.
*`DB_PASSWD`: **"\<empty>"**: Database user password. Use \`your password\` for quoting if you use special characters in the password.
*`INSTALL_LOCK`: **false**: Disallow access to the install page.
*`SECRET_KEY`: **""**: Global secret key. This should be changed. If this has a value and `INSTALL_LOCK` is empty, `INSTALL_LOCK` will automatically set to `true`.
*`DISABLE_REGISTRATION`: **false**: Disable registration, after which only admin can create accounts for users.
*`REQUIRE_SIGNIN_VIEW`: **false**: Enable this to force users to log in to view any page.
*`USER_UID`: **1000**: The UID (Unix user ID) of the user that runs Gitea within the container. Match this to the UID of the owner of the `/data` volume if using host volumes (this is not necessary with named volumes).
*`USER_GID`: **1000**: The GID (Unix group ID) of the user that runs Gitea within the container. Match this to the GID of the owner of the `/data` volume if using host volumes (this is not necessary with named volumes).
# Customization
-`APP_NAME`: **"Gitea: Git with a cup of tea"**: Application name, used in the page title.
-`RUN_MODE`: **prod**: Application run mode, affects performance and debugging. Either "dev", "prod" or "test".
-`DOMAIN`: **localhost**: Domain name of this server, used for the displayed http clone URL in Gitea's UI.
-`SSH_DOMAIN`: **localhost**: Domain name of this server, used for the displayed ssh clone URL in Gitea's UI. If the install page is enabled, SSH Domain Server takes DOMAIN value in the form (which overwrite this setting on save).
-`SSH_PORT`: **22**: SSH port displayed in clone URL.
-`SSH_LISTEN_PORT`: **%(SSH_PORT)s**: Port for the built-in SSH server.
-`DISABLE_SSH`: **false**: Disable SSH feature when it's not available. If you want to disable SSH feature, you should set SSH port to `0` when installing Gitea.
-`HTTP_PORT`: **3000**: HTTP listen port.
-`ROOT_URL`: **""**: Overwrite the automatically generated public URL. This is useful if the internal and the external URL don't match (e.g. in Docker).
-`DB_TYPE`: **sqlite3**: The database type in use \[mysql, postgres, mssql, sqlite3\].
-`DB_HOST`: **localhost:3306**: Database host address and port.
-`DB_NAME`: **gitea**: Database name.
-`DB_USER`: **root**: Database username.
-`DB_PASSWD`: **"\<empty>"**: Database user password. Use \`your password\` for quoting if you use special characters in the password.
-`INSTALL_LOCK`: **false**: Disallow access to the install page.
-`SECRET_KEY`: **""**: Global secret key. This should be changed. If this has a value and `INSTALL_LOCK` is empty, `INSTALL_LOCK` will automatically set to `true`.
-`DISABLE_REGISTRATION`: **false**: Disable registration, after which only admin can create accounts for users.
-`REQUIRE_SIGNIN_VIEW`: **false**: Enable this to force users to log in to view any page.
-`USER_UID`: **1000**: The UID (Unix user ID) of the user that runs Gitea within the container. Match this to the UID of the owner of the `/data` volume if using host volumes (this is not necessary with named volumes).
-`USER_GID`: **1000**: The GID (Unix group ID) of the user that runs Gitea within the container. Match this to the GID of the owner of the `/data` volume if using host volumes (this is not necessary with named volumes).
## Customization
Customization files described [here](https://docs.gitea.io/en-us/customizing-gitea/) should
be placed in `/data/gitea` directory. If using host volumes, it's quite easy to access these
@ -288,7 +292,7 @@ files; for named volumes, this is done through another container or by direct ac
`/var/lib/docker/volumes/gitea_gitea/_data`. The configuration file will be saved at
`/data/gitea/conf/app.ini` after the installation.
# Upgrading
## Upgrading
:exclamation::exclamation: **Make sure you have volumed data to somewhere outside Docker container** :exclamation::exclamation:
@ -302,7 +306,7 @@ docker-compose pull
docker-compose up -d
```
# SSH Container Passthrough
## SSH Container Passthrough
Since SSH is running inside the container, SSH needs to be passed through from the host to the container if SSH support is desired. One option would be to run the container SSH on a non-standard port (or moving the host port to a non-standard port). Another option which might be more straightforward is to forward SSH connections from the host to the container. This setup is explained in the following.
Gitea currently has a `dump` command that will save the installation to a zip file. This
file can be unpacked and used to restore an instance.
**Table of Contents**
{{<toc>}}
## Backup Command (`dump`)
Switch to the user running Gitea: `su git`. Run `./gitea dump -c /path/to/app.ini` in the Gitea installation
@ -34,12 +38,12 @@ directory. There should be some output similar to the following:
Inside the `gitea-dump-1482906742.zip` file, will be the following:
*`app.ini` - Optional copy of configuration file if originally stored outside of the default `custom/` directory
*`custom` - All config or customization files in `custom/`.
*`data` - Data directory in <GITEA_WORK_DIR>, except sessions if you are using file session. This directory includes `attachments`, `avatars`, `lfs`, `indexers`, sqlite file if you are using sqlite.
*`gitea-db.sql` - SQL dump of database
*`gitea-repo.zip` - Complete copy of the repository directory.
*`log/` - Various logs. They are not needed for a recovery or migration.
-`app.ini` - Optional copy of configuration file if originally stored outside of the default `custom/` directory
-`custom` - All config or customization files in `custom/`.
-`data` - Data directory in <GITEA_WORK_DIR>, except sessions if you are using file session. This directory includes `attachments`, `avatars`, `lfs`, `indexers`, sqlite file if you are using sqlite.
-`gitea-db.sql` - SQL dump of database
-`gitea-repo.zip` - Complete copy of the repository directory.
-`log/` - Various logs. They are not needed for a recovery or migration.
Intermediate backup files are created in a temporary directory specified either with the
`--tempdir` command-line parameter or the `TMPDIR` environment variable.
*Note: `--tempdir` refers to the temporary directory of the docker environment used by Gitea; if you have not specified a custom `--tempdir`, then Gitea uses `/tmp` or the `TMPDIR` environment variable of the docker container. For `--tempdir` adjust your `docker exec` command options accordingly.
\*Note: `--tempdir` refers to the temporary directory of the docker environment used by Gitea; if you have not specified a custom `--tempdir`, then Gitea uses `/tmp` or the `TMPDIR` environment variable of the docker container. For `--tempdir` adjust your `docker exec` command options accordingly.
The result should be a file, stored in the `--tempdir` specified, along the lines of: `gitea-dump-1482906742.zip`
@ -67,7 +71,7 @@ involves moving files to their correct locations and restoring a database dump.
- `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
NB: Gitea must be running for this command to succeed.
### migrate
Migrates the database. This command can be used to run other commands before starting the server for the first time.
This command is idempotent.
### convert
Converts an existing MySQL database from utf8 to utf8mb4.
### doctor
Diagnose the problems of current gitea instance according the given configuration.
Currently there are a check list below:
- Check if OpenSSH authorized_keys file id correct
When your gitea instance support OpenSSH, your gitea instance binary path will be written to `authorized_keys`
when there is any public key added or changed on your gitea instance.
Sometimes if you moved or renamed your gitea binary when upgrade and you haven't run `Update the '.ssh/authorized_keys' file with Gitea SSH keys. (Not needed for the built-in SSH server.)` on your Admin Panel. Then all pull/push via SSH will not be work.
This check will help you to check if it works well.
When your gitea instance support OpenSSH, your gitea instance binary path will be written to `authorized_keys`
when there is any public key added or changed on your gitea instance.
Sometimes if you moved or renamed your gitea binary when upgrade and you haven't run `Update the '.ssh/authorized_keys' file with Gitea SSH keys. (Not needed for the built-in SSH server.)` on your Admin Panel. Then all pull/push via SSH will not be work.
This check will help you to check if it works well.
For contributors, if you want to add more checks, you can wrie ad new function like `func(ctx *cli.Context) ([]string, error)` and
Before you enable HTTPS, make sure that you have valid SSL/TLS certificates.
@ -32,6 +36,7 @@ HTTP_PORT = 3000
CERT_FILE = cert.pem
KEY_FILE = key.pem
```
Note that if your certificate is signed by a third party certificate authority (i.e. not self-signed), then cert.pem should contain the certificate chain. The server certificate must be the first entry in cert.pem, followed by the intermediaries in order (if any). The root certificate does not have to be included because the connecting client must already have it in order to estalbish the trust relationship.
To learn more about the config values, please checkout the [Config Cheat Sheet](../config-cheat-sheet#server).
Note: Enabling HTTPS only at the proxy level is referred as [TLS Termination Proxy](https://en.wikipedia.org/wiki/TLS_termination_proxy). The proxy server accepts incoming TLS connections, decrypts the contents, and passes the now unencrypted contents to Gitea. This is normally fine as long as both the proxy and Gitea instances are either on the same machine, or on different machines within private network (with the proxy is exposed to outside network). If your Gitea instance is separated from your proxy over a public network, or if you want full end-to-end encryption, you can also [enable HTTPS support directly in Gitea using built-in server](#using-the-built-in-server) and forward the connections over HTTPS instead.
Some projects have a standard list of questions that users need to answer
when creating an issue or pull request. Gitea supports adding templates to the
main branch of the repository so that they can autopopulate the form when users are
@ -23,53 +27,55 @@ of getting some clarifying details.
Possible file names for issue templates:
* ISSUE_TEMPLATE.md
* issue_template.md
* .gitea/ISSUE_TEMPLATE.md
* .gitea/issue_template.md
* .github/ISSUE_TEMPLATE.md
* .github/issue_template.md
- `ISSUE_TEMPLATE.md`
- `issue_template.md`
- `.gitea/ISSUE_TEMPLATE.md`
- `.gitea/issue_template.md`
- `.github/ISSUE_TEMPLATE.md`
- `.github/issue_template.md`
Possible file names for PR templates:
* PULL_REQUEST_TEMPLATE.md
* pull_request_template.md
* .gitea/PULL_REQUEST_TEMPLATE.md
* .gitea/pull_request_template.md
* .github/PULL_REQUEST_TEMPLATE.md
* .github/pull_request_template.md
- `PULL_REQUEST_TEMPLATE.md`
- `pull_request_template.md`
- `.gitea/PULL_REQUEST_TEMPLATE.md`
- `.gitea/pull_request_template.md`
- `.github/PULL_REQUEST_TEMPLATE.md`
- `.github/pull_request_template.md`
Additionally, the New Issue page URL can be suffixed with `?title=Issue+Title&body=Issue+Text` and the form will be populated with those strings. Those strings will be used instead of the template if there is one.
# Issue Template Directory
## Issue Template Directory
Alternatively, users can create multiple issue templates inside a special directory and allow users to choose one that more specifically
addresses their problem.
Possible directory names for issue templates:
* ISSUE_TEMPLATE
* issue_template
* .gitea/ISSUE_TEMPLATE
* .gitea/issue_template
* .github/ISSUE_TEMPLATE
* .github/issue_template
* .gitlab/ISSUE_TEMPLATE
* .gitlab/issue_template
- `ISSUE_TEMPLATE`
- `issue_template`
- `.gitea/ISSUE_TEMPLATE`
- `.gitea/issue_template`
- `.github/ISSUE_TEMPLATE`
- `.github/issue_template`
- `.gitlab/ISSUE_TEMPLATE`
- `.gitlab/issue_template`
Inside the directory can be multiple issue templates with the form
Marking a pull request as being a work in progress will prevent that pull request from being accidentally merged. To mark a pull request as being a work in progress, you must prefix its title by `WIP:` or `[WIP]` (case insensitive). Those values are configurable in your `app.ini` file :
If you want Nginx to serve your Gitea instance, add the following `server` section to the `http` section of `nginx.conf`:
```
```apacheconf
server {
listen 80;
server_name git.example.com;
@ -35,7 +38,7 @@ server {
In case you already have a site, and you want Gitea to share the domain name, you can setup Nginx to serve Gitea under a sub-path by adding the following `server` section inside the `http` section of `nginx.conf`:
```
```apacheconf
server {
listen 80;
server_name git.example.com;
@ -49,6 +52,7 @@ server {
Then set `[server] ROOT_URL = http://git.example.com/git/` in your configuration.
## Nginx and serve static resources directly
We can tune the performance in splitting requests into categories static and dynamic.
CSS files, JavaScript files, images and web fonts are static content.
@ -56,20 +60,20 @@ The front page, a repository view or issue list is dynamic content.
Nginx can serve static resources directly and proxy only the dynamic requests to gitea.
Nginx is optimized for serving static content, while the proxying of large responses might be the opposite of that
(see https://serverfault.com/q/587386).
(see https://serverfault.com/q/587386).
Download a snapshot of the Gitea source repository to `/path/to/gitea/`.
After this, run `make frontend` in the repository directory to generate the static resources. We are only interested in the `public/` directory for this task, so you can delete the rest.
(You will need to have [Node with npm](https://nodejs.org/en/download/) and `make` installed to generate the static resources)
Depending on the scale of your user base, you might want to split the traffic to two distinct servers,
or use a cdn for the static files.
or use a cdn for the static files.
### Single node and single domain
Set `[server] STATIC_URL_PREFIX = /_/static` in your configuration.
```
```apacheconf
server {
listen 80;
server_name git.example.com;
@ -88,7 +92,7 @@ server {
Set `[server] STATIC_URL_PREFIX = http://cdn.example.com/gitea` in your configuration.
```
```apacheconf
# application server running gitea
server {
listen 80;
@ -100,7 +104,7 @@ server {
}
```
```
```apacheconf
# static content delivery server
server {
listen 80;
@ -120,7 +124,7 @@ server {
If you want Apache HTTPD to serve your Gitea instance, you can add the following to your Apache HTTPD configuration (usually located at `/etc/apache2/httpd.conf` in Ubuntu):
```
```apacheconf
<VirtualHost*:80>
...
ProxyPreserveHost On
@ -139,7 +143,7 @@ If you wish to use Let's Encrypt with webroot validation, add the line `ProxyPas
In case you already have a site, and you want Gitea to share the domain name, you can setup Apache HTTPD to serve Gitea under a sub-path by adding the following to you Apache HTTPD configuration (usually located at `/etc/apache2/httpd.conf` in Ubuntu):
```
```apacheconf
<VirtualHost*:80>
...
<Proxy*>
@ -161,7 +165,7 @@ Note: The following Apache HTTPD mods must be enabled: `proxy`, `proxy_http`
If you want Caddy to serve your Gitea instance, you can add the following server block to your Caddyfile:
```
```apacheconf
git.example.com {
reverse_proxy localhost:3000
}
@ -169,7 +173,7 @@ git.example.com {
If you still use Caddy v1, use:
```
```apacheconf
git.example.com {
proxy / localhost:3000
}
@ -179,7 +183,7 @@ git.example.com {
In case you already have a site, and you want Gitea to share the domain name, you can setup Caddy to serve Gitea under a sub-path by adding the following to your server block in your Caddyfile:
```
```apacheconf
git.example.com {
route /git/* {
uri strip_prefix /git
@ -190,7 +194,7 @@ git.example.com {
Or, for Caddy v1:
```
```apacheconf
git.example.com {
proxy /git/ localhost:3000
}
@ -204,14 +208,15 @@ If you wish to run Gitea with IIS. You will need to setup IIS with URL Rewrite a
1. Setup an empty website in IIS, named let's say, `Gitea Proxy`.
2. Follow the first two steps in [Microsoft's Technical Community Guide to Setup IIS with URL Rewrite](https://techcommunity.microsoft.com/t5/iis-support-blog/setup-iis-with-url-rewrite-as-a-reverse-proxy-for-real-world/ba-p/846222#M343). That is:
- Install Application Request Routing (ARR for short) either by using the Microsoft Web Platform Installer 5.1 (WebPI) or downloading the extension from [IIS.net]( https://www.iis.net/downloads/microsoft/application-request-routing)
- Once the module is installed in IIS, you will see a new Icon in the IIS Administration Console called URL Rewrite.
- Open the IIS Manager Console and click on the `Gitea Proxy` Website from the tree view on the left. Select and double click the URL Rewrite Icon from the middle pane to load the URL Rewrite interface.
- Choose the `Add Rule` action from the right pane of the management console and select the `Reverse Proxy Rule` from the `Inbound and Outbound Rules` category.
- In the Inbound Rules section, set the server name to be the host that Gitea is running on with its port. e.g. if you are running Gitea on the localhost with port 3000, the following should work: `127.0.0.1:3000`
- Enable SSL Offloading
- In the Outbound Rules, ensure `Rewrite the domain names of the links in HTTP response` is set and set the `From:` field as above and the `To:` to your external hostname, say: `git.example.com`
- Now edit the `web.config` for your website to match the following: (changing `127.0.0.1:3000` and `git.example.com` as appropriate)
- Install Application Request Routing (ARR for short) either by using the Microsoft Web Platform Installer 5.1 (WebPI) or downloading the extension from [IIS.net](https://www.iis.net/downloads/microsoft/application-request-routing)
- Once the module is installed in IIS, you will see a new Icon in the IIS Administration Console called URL Rewrite.
- Open the IIS Manager Console and click on the `Gitea Proxy` Website from the tree view on the left. Select and double click the URL Rewrite Icon from the middle pane to load the URL Rewrite interface.
- Choose the `Add Rule` action from the right pane of the management console and select the `Reverse Proxy Rule` from the `Inbound and Outbound Rules` category.
- In the Inbound Rules section, set the server name to be the host that Gitea is running on with its port. e.g. if you are running Gitea on the localhost with port 3000, the following should work: `127.0.0.1:3000`
- Enable SSL Offloading
- In the Outbound Rules, ensure `Rewrite the domain names of the links in HTTP response` is set and set the `From:` field as above and the `To:` to your external hostname, say: `git.example.com`
- Now edit the `web.config` for your website to match the following: (changing `127.0.0.1:3000` and `git.example.com` as appropriate)
Gitea `1.11.0` and above includes template repositories, and one feature implemented with them is auto-expansion of specific variables within your template files.
To tell Gitea which files to expand, you must include a `template` file inside the `.gitea` directory of the template repository.
Gitea uses [gobwas/glob](https://github.com/gobwas/glob) for its glob syntax. It closely resembles a traditional `.gitignore`, however there may be slight differences.
### Example `.gitea/template` file
## Example `.gitea/template` file
All paths are relative to the base of the repository
```gitignore
# All .go files, anywhere in the repository
**.go
@ -33,14 +40,16 @@ a/b/c/d.json
# Batch files in both upper or lower case can be matched
**.[bB][aA][tT]
```
**NOTE:** The `template` file will be removed from the `.gitea` directory when a repository is generated from the template.
### Variable Expansion
## Variable Expansion
In any file matched by the above globs, certain variables will be expanded.
All variables must be of the form `$VAR` or `${VAR}`. To escape an expansion, use a double `$$`, such as `$$VAR` or `$${VAR}`
Patrick Schratz
4 years ago
committed by
GitHub