or compare with a previous PR adding a new API endpoint e.g. [PR #5483](https://github.com/go-gitea/gitea/pull/5843/files#diff-2e0a7b644cf31e1c8ef7d76b444fe3aaR20)
or compare with a previous PR adding a new API endpoint, e.g. [PR #5483](https://github.com/go-gitea/gitea/pull/5843/files#diff-2e0a7b644cf31e1c8ef7d76b444fe3aaR20)
You should be careful not to break the API for downstream users which depend
You should be careful not to break the API for downstream users which depend
on a stable API. In general this means additions are acceptable, but deletions
on a stable API. In general, this means additions are acceptable, but deletions
or fundamental changes of API will be rejected.
or fundamental changes to the API will be rejected.
Once you have created or changed an API endpoint, please regenerate the Swagger
Once you have created or changed an API endpoint, please regenerate the Swagger
documentation using:
documentation using:
@ -208,7 +208,7 @@ found in `docs/content/doc/advanced/config-cheat-sheet.en-us.md`
### Changing the logo
### Changing the logo
When changing the Gitea logo svg. You will need to run and commit the results
When changing the Gitea logo SVG, you will need to run and commit the results
of:
of:
```bash
```bash
@ -220,7 +220,7 @@ This will create the necessary Gitea favicon and others.
### Database Migrations
### Database Migrations
If you make breaking changes to any of the database persisted structs in the
If you make breaking changes to any of the database persisted structs in the
`models/` directory you will need to make a new migration. These can be found
`models/` directory, you will need to make a new migration. These can be found
in `models/migrations/`. You can ensure that your migrations work for the main
in `models/migrations/`. You can ensure that your migrations work for the main
database types using:
database types using:
@ -236,23 +236,23 @@ There are two types of test run by Gitea: Unit tests and Integration Tests.
TAGS="bindata sqlite sqlite_unlock_notify" make test # Runs the unit tests
TAGS="bindata sqlite sqlite_unlock_notify" make test # Runs the unit tests
```
```
Unit tests will not and cannot completely test Gitea alone. Therefore we
Unit tests will not and cannot completely test Gitea alone. Therefore, we
have written integration tests, however, these are database dependent.
have written integration tests; however, these are database dependent.
```bash
```bash
TAGS="bindata sqlite sqlite_unlock_notify" make generate build test-sqlite
TAGS="bindata sqlite sqlite_unlock_notify" make generate build test-sqlite
```
```
Will run the integration tests in an sqlite environment. Other database tests
will run the integration tests in an sqlite environment. Other database tests
are available however may need adjustment for local environment.
are available but may need adjustment to the local environment.
- Example for Microsoft Active Directory (AD): `(&(objectCategory=Person)(memberOf=CN=user-group,OU=example,DC=example,DC=org)(sAMAccountName=%s)(!(UserAccountControl:1.2.840.113556.1.4.803:=2)))`
- Example for Microsoft Active Directory (AD): `(&(objectCategory=Person)(memberOf=CN=user-group,OU=example,DC=example,DC=org)(sAMAccountName=%s)(!(UserAccountControl:1.2.840.113556.1.4.803:=2)))`
- To substitute more than once `%[1]s` should be used instead, e.g. when
- To substitute more than once,`%[1]s` should be used instead, e.g. when
matching supplied login name against multiple attributes such as user
matching supplied login name against multiple attributes such as user
To help decide if Gitea is suited for your needs here is how it compares to other Git self hosted options.
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 can be outdated. If you find anything that needs to be updated in table below please report [issue on Github](https://github.com/go-gitea/gitea/issues).
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).
Check that you have proper access to the repository
Check that you have proper access to the repository
error: failed to push some refs to '<GIT_REPO_URL>'
error: failed to push some refs to '<GIT_REPO_URL>'
```
```
Have you checked the value of `LFS_HTTP_AUTH_EXPIRY` in your `app.ini` file? By default your LFS token will expire after 20 minutes. If you have a slow connection or a large file (or both) it may not finish uploading within the time limit.
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`.
You may want to set this value to `60m` or `120m`.
Gitea signs all binaries with a [GPG key](https://pgp.mit.edu/pks/lookup?op=vindex&fingerprint=on&search=0x2D9AE806EC1592E2) to prevent against unwanted modification of binaries. To validate the binary download the signature file which ends in `.asc` for the binary you downloaded and use the gpg command line tool.
Gitea signs all binaries with a [GPG key](https://pgp.mit.edu/pks/lookup?op=vindex&fingerprint=on&search=0x2D9AE806EC1592E2) to prevent against unwanted modification of binaries. To validate the binary, download the signature file which ends in `.asc` for the binary you downloaded and use the gpg command line tool.
@ -49,12 +49,12 @@ Of note, configuring `GITEA_WORK_DIR` will tell Gitea where to base its working
### Prepare environment
### Prepare environment
Check that git is installed on the server, if it is not install it first.
Check that Git is installed on the server. If it is not, install it first.
```sh
```sh
git --version
git --version
```
```
Create user to run gitea (ex. `git`)
Create user to run Gitea (ex. `git`)
```sh
```sh
adduser \
adduser \
--system \
--system \
@ -77,7 +77,7 @@ chown root:git /etc/gitea
chmod 770 /etc/gitea
chmod 770 /etc/gitea
```
```
**NOTE:** `/etc/gitea` is temporary set with write rights for user `git` so that Web installer could write configuration file. After installation is done it is recommended to set rights to read-only using:
**NOTE:** `/etc/gitea` is temporary set with write rights for user `git` so that Web installer could write configuration file. After installation is done, it is recommended to set rights to read-only using:
```
```
chmod 750 /etc/gitea
chmod 750 /etc/gitea
chmod 644 /etc/gitea/app.ini
chmod 644 /etc/gitea/app.ini
@ -90,7 +90,7 @@ chmod 644 /etc/gitea/app.ini
export GITEA_WORK_DIR=/var/lib/gitea/
export GITEA_WORK_DIR=/var/lib/gitea/
```
```
### Copy gitea binary to global location
### Copy Gitea binary to global location
```
```
cp gitea /usr/local/bin/gitea
cp gitea /usr/local/bin/gitea
@ -112,7 +112,7 @@ GITEA_WORK_DIR=/var/lib/gitea/ /usr/local/bin/gitea web -c /etc/gitea/app.ini
## Updating to a new version
## Updating to a new version
You can update to a new version of gitea by stopping gitea, replacing the binary at `/usr/local/bin/gitea` and restarting the instance.
You can update to a new version of Gitea by stopping Gitea, replacing the binary at `/usr/local/bin/gitea` and restarting the instance.
The binary file name should not be changed during the update to avoid problems
The binary file name should not be changed during the update to avoid problems
in existing repositories.
in existing repositories.
@ -122,7 +122,7 @@ If you have carried out the installation steps as described above, the binary sh
have the generic name `gitea`. Do not change this, i.e. to include the version number.
have the generic name `gitea`. Do not change this, i.e. to include the version number.
See below for troubleshooting instructions to repair broken repositories after
See below for troubleshooting instructions to repair broken repositories after
an update of your gitea version.
an update of your Gitea version.
## Troubleshooting
## Troubleshooting
@ -135,16 +135,16 @@ SQLite support in the binaries provided by dl.gitea.io. In this situation, it is
possible to [install from source]({{< relref "from-source.en-us.md" >}}) without sqlite
possible to [install from source]({{< relref "from-source.en-us.md" >}}) without sqlite
support.
support.
### Running gitea on another port
### Running Gitea on another port
For errors like `702 runWeb()] [E] Failed to start server: listen tcp 0.0.0.0:3000:
For errors like `702 runWeb()] [E] Failed to start server: listen tcp 0.0.0.0:3000:
bind: address already in use` gitea needs to be started on another free port. This
bind: address already in use` Gitea needs to be started on another free port. This
is possible using `./gitea web -p $PORT`. It's possible another instance of gitea
is possible using `./gitea web -p $PORT`. It's possible another instance of Gitea
is already running.
is already running.
### Git error after updating to a new version of gitea
### Git error after updating to a new version of Gitea
If the binary file name has been changed during the update to a new version of gitea,
If the binary file name has been changed during the update to a new version of Gitea,
git hooks in existing repositories will not work any more. In that case, a git
git hooks in existing repositories will not work any more. In that case, a git
error will be displayed when pushing to the repository.
error will be displayed when pushing to the repository.
@ -152,7 +152,7 @@ error will be displayed when pushing to the repository.
remote: ./hooks/pre-receive.d/gitea: line 2: [...]: No such file or directory
remote: ./hooks/pre-receive.d/gitea: line 2: [...]: No such file or directory
```
```
The `[...]` part of the error message will contain the path to your previous gitea
The `[...]` part of the error message will contain the path to your previous Gitea
binary.
binary.
To solve this, go to the admin options and run the task `Resynchronize pre-receive,
To solve this, go to the admin options and run the task `Resynchronize pre-receive,
@ -160,6 +160,6 @@ update and post-receive hooks of all repositories` to update all hooks to contai
the new binary path. Please note that this overwrite all git hooks including ones
the new binary path. Please note that this overwrite all git hooks including ones
with customizations made.
with customizations made.
If you aren't using the built-in to Gitea ssh server you will also need to re-write
If you aren't using the built-in to Gitea SSH server you will also need to re-write
the authorized key file by running the `Update the '.ssh/authorized_keys' file with
the authorized key file by running the `Update the '.ssh/authorized_keys' file with
@ -20,13 +20,13 @@ possible to always use the latest stable tag or to use another service that hand
Docker images.
Docker images.
This reference setup guides users through the setup based on `docker-compose`, but the installation
This reference setup guides users through the setup based on `docker-compose`, but the installation
of `docker-compose` is out of scope of this documentation. To install `docker-compose` itself follow
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/).
the official [install instructions](https://docs.docker.com/compose/install/).
## Basics
## Basics
The most simple setup just creates a volume and a network and starts the `gitea/gitea:latest`
The most simple setup just creates a volume and a network and starts the `gitea/gitea:latest`
image as a service. Since there is no database available one can be initialized using SQLite3.
image as a service. Since there is no database available, one can be initialized using SQLite3.
Create a directory like `gitea` and paste the following content into a file named `docker-compose.yml`.
Create a directory like `gitea` and paste the following content into a file named `docker-compose.yml`.
Note that the volume should be owned by the user/group with the UID/GID specified in the config file.
Note that the volume should be owned by the user/group with the UID/GID specified in the config file.
If you don't give the volume correct permissions, the container may not start.
If you don't give the volume correct permissions, the container may not start.
@ -187,7 +187,7 @@ services:
To use named volumes instead of host volumes, define and use the named volume
To use named volumes instead of host volumes, define and use the named volume
within the `docker-compose.yml` configuration. This change will automatically
within the `docker-compose.yml` configuration. This change will automatically
create the required volume. You don't need to worry about permissions with
create the required volume. You don't need to worry about permissions with
named volumes, Docker will deal with that automatically.
named volumes; Docker will deal with that automatically.
```diff
```diff
version: "2"
version: "2"
@ -230,10 +230,10 @@ Notice: if using a non-3000 port on http, change app.ini to match
## Install
## Install
After starting the Docker setup via `docker-compose` Gitea should be available using a
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
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
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.
documented above, please note that `db` must be used as the database hostname.
## Environments variables
## Environments variables
@ -252,7 +252,7 @@ You can configure some of Gitea's settings via environment variables:
* `DB_HOST`: **localhost:3306**: Database host address and port.
* `DB_HOST`: **localhost:3306**: Database host address and port.
* `DB_NAME`: **gitea**: Database name.
* `DB_NAME`: **gitea**: Database name.
* `DB_USER`: **root**: Database username.
* `DB_USER`: **root**: Database username.
* `DB_PASSWD`: **"<empty>"**: Database user password. Use \`your password\` for quoting if you use special characters in the password.
* `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.
* `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`.
* `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.
* `DISABLE_REGISTRATION`: **false**: Disable registration, after which only admin can create accounts for users.
@ -263,8 +263,8 @@ You can configure some of Gitea's settings via environment variables:
# Customization
# Customization
Customization files described [here](https://docs.gitea.io/en-us/customizing-gitea/) should
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
be placed in `/data/gitea` directory. If using host volumes, it's quite easy to access these
files; for named volumes this is done through another container or by direct access at
files; for named volumes, this is done through another container or by direct access at
`/var/lib/docker/volumes/gitea_gitea/_data`. The configuration file will be saved at
`/var/lib/docker/volumes/gitea_gitea/_data`. The configuration file will be saved at
`/data/gitea/conf/app.ini` after the installation.
`/data/gitea/conf/app.ini` after the installation.
@ -285,7 +285,7 @@ docker-compose up -d
Since SSH is running inside the container, you'll have to pass SSH from the host to the
Since SSH is running inside the container, you'll have to pass SSH from the host to the
container if you wish to use SSH support. If you wish to do this without running the container
container if you wish to use SSH support. If you wish to do this without running the container
SSH on a non-standard port (or move your host port to a non-standard port) you can forward
SSH on a non-standard port (or move your host port to a non-standard port), you can forward
SSH connections destined for the container with a little extra setup.
SSH connections destined for the container with a little extra setup.
This guide assumes that you have created a user on the host called `git` which shares the same
This guide assumes that you have created a user on the host called `git` which shares the same
Before you enable HTTPS make sure that you have valid SSL/TLS certificates.
Before you enable HTTPS, make sure that you have valid SSL/TLS certificates.
You could use self-generated certificates for evaluation and testing. Please run `gitea cert --host [HOST]` to generate a self signed certificate.
You could use self-generated certificates for evaluation and testing. Please run `gitea cert --host [HOST]` to generate a self signed certificate.
To use Gitea's built-in HTTPS support you must change your `app.ini` file:
To use Gitea's built-in HTTPS support, you must change your `app.ini` file:
```ini
```ini
[server]
[server]
@ -33,7 +33,7 @@ KEY_FILE = key.pem
To learn more about the config values, please checkout the [Config Cheat Sheet](../config-cheat-sheet#server).
To learn more about the config values, please checkout the [Config Cheat Sheet](../config-cheat-sheet#server).
### Setting-up HTTP redirection
### Settingup HTTP redirection
The Gitea server is only able to listen to one port; to redirect HTTP requests to the HTTPS port, you will need to enable the HTTP redirection service:
The Gitea server is only able to listen to one port; to redirect HTTP requests to the HTTPS port, you will need to enable the HTTP redirection service:
@ -48,9 +48,9 @@ If you are using Docker, make sure that this port is configured in your `docker-
## Using Let's Encrypt
## Using Let's Encrypt
[Let's Encrypt](https://letsencrypt.org/) is a Certificate Authority that allows you to automatically request and renew SSL/TLS certificates. In addition to starting Gitea on your configured port, to request HTTPS certificates Gitea will also need to listed on port 80, and will set up an autoredirect to HTTPS for you. Let's Encrypt will need to be able to access Gitea via the Internet to verify your ownership of the domain.
[Let's Encrypt](https://letsencrypt.org/) is a Certificate Authority that allows you to automatically request and renew SSL/TLS certificates. In addition to starting Gitea on your configured port, to request HTTPS certificates, Gitea will also need to listed on port 80, and will set up an autoredirect to HTTPS for you. Let's Encrypt will need to be able to access Gitea via the Internet to verify your ownership of the domain.
By using Lets Encrypt **you must consent** to their [terms of service](https://letsencrypt.org/documents/LE-SA-v1.2-November-15-2017.pdf)
By using Let's Encrypt **you must consent** to their [terms of service](https://letsencrypt.org/documents/LE-SA-v1.2-November-15-2017.pdf).
```ini
```ini
[server]
[server]
@ -66,7 +66,7 @@ To learn more about the config values, please checkout the [Config Cheat Sheet](
## Using reverse proxy
## Using reverse proxy
Setup up your reverse proxy like shown in the [reverse proxy guide](../reverse-proxies).
Setup up your reverse proxy as shown in the [reverse proxy guide](../reverse-proxies).
After that, enable HTTPS by following one of these guides:
After that, enable HTTPS by following one of these guides:
@ -74,5 +74,5 @@ After that, enable HTTPS by following one of these guides:
Note: Your connection between your reverse proxy and gitea might be unencrypted. To encrypt it too follow the [built-in server guide](#using-built-in-server) and change
Note: Your connection between your reverse proxy and Gitea might be unencrypted. To encrypt it too, follow the [built-in server guide](#using-built-in-server) and change
If you want Nginx to serve your Gitea instance you can the following `server` section inside the `http` section of `nginx.conf`:
If you want Nginx to serve your Gitea instance, you can the following `server` section inside the `http` section of `nginx.conf`:
```
```
server {
server {
@ -27,7 +27,7 @@ server {
}
}
```
```
## Using Nginx with a Sub-path as a reverse proxy
## Using Nginx with a sub-path as a reverse proxy
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`:
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`:
@ -46,7 +46,7 @@ Then set `[server] ROOT_URL = http://git.example.com/git/` in your configuration
## Using Apache HTTPD as a reverse proxy
## Using Apache HTTPD as a reverse proxy
If you want Apache HTTPD to serve your Gitea instance you can add the following to you Apache HTTPD configuration (usually located at `/etc/apache2/httpd.conf` in Ubuntu):
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):
```
```
<VirtualHost*:80>
<VirtualHost*:80>
@ -60,7 +60,7 @@ If you want Apache HTTPD to serve your Gitea instance you can add the following
Note: The following Apache HTTPD mods must be enabled: `proxy`, `proxy_http`
Note: The following Apache HTTPD mods must be enabled: `proxy`, `proxy_http`
## Using Apache HTTPD with a Sub-path as a reverse proxy
## Using Apache HTTPD with a sub-path as a reverse proxy
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):
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):
@ -83,7 +83,7 @@ Note: The following Apache HTTPD mods must be enabled: `proxy`, `proxy_http`
## Using Caddy as a reverse proxy
## Using Caddy as a reverse proxy
If you want Caddy to serve your Gitea instance you can add the following server block to your Caddyfile:
If you want Caddy to serve your Gitea instance, you can add the following server block to your Caddyfile:
```
```
git.example.com {
git.example.com {
@ -91,9 +91,9 @@ git.example.com {
}
}
```
```
## Using Caddy with a Sub-path as a reverse proxy
## Using Caddy with a sub-path as a reverse proxy
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 you server block in your Caddyfile:
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:
Aidan Fitzgerald
6 years ago
committed by
techknowlogick