gitea/gitea-docs
1
0
Fork 0
mirror of https://gitea.com/gitea/docs.git synced 2026-07-08 14:35:23 +00:00
Code Issues Packages Projects Releases Wiki Activity

Add 1.25.0 documentation (#289)

Browse Source 
Reviewed-on: https://gitea.com/gitea/docs/pulls/289
This commit is contained in:
Lunny Xiao
2025-11-01 06:48:53 +00:00
parent d5eac4f23d
commit 7d50e32ba8
112 changed files with 49039 additions and 219 deletions
Download Patch File Download Diff File Expand all files Collapse all files

145
versioned_docs/version-1.25/installation/comparison.md Normal file
View File

@@ -0,0 +1,145 @@
---
date: "2018-05-07T13:00:00+02:00"
slug: "comparison"
sidebar_position: 5
aliases:
- /en-us/comparison
---
# Compared to other Git hosting
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 [open an issue](https://github.com/go-gitea/gitea/issues/new/choose).
_Symbols used in table:_
- _✓ - supported_
- _⁄ - supported with limited functionality_
- _✘ - unsupported_
- _⚙️ - supported through third-party software_
## General Features
| Feature | Gitea | GitHub EE | GitLab CE | GitLab EE | BitBucket | RhodeCode CE | RhodeCode EE |
| ------------------------------------------------ | --------------------------------------------------- | --------- | --------- | --------- | --------- | ------------ | ------------ |
| Open source and free | ✓ | ✘ | ✓ | ✘ | ✘ | ✓ | ✓ |
| Low RAM/ CPU usage | ✓ | ✘ | ✘ | ✘ | ✘ | ✘ | ✘ |
| Multiple database support | ✓ | ✘ | ⁄ | ⁄ | ✓ | ✓ | ✓ |
| Multiple OS support | ✓ | ✘ | ✘ | ✘ | ✘ | ✓ | ✓ |
| Easy upgrades | ✓ | ✘ | ✓ | ✓ | ✘ | ✓ | ✓ |
| Telemetry | **✘** | ✓ | ✓ | ✓ | ✓ | ✘ | ✘ |
| Third-party render tool support | ✓ | ✘ | ✘ | ✘ | ✓ | ✘ | ✘ |
| WebAuthn (2FA) | ✓ | ✓ | ✓ | ✓ | ✓ | ✘ | ✓ |
| Extensive API | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ |
| Built-in Package/Container Registry | ✓ | ✓ | ✓ | ✓ | ✘ | ✘ | ✘ |
| Sync commits to an external repo (push mirror) | ✓ | ✘ | ✓ | ✓ | ✘ | ✓ | ✓ |
| Sync commits from an external repo (pull mirror) | ✓ | ✘ | ✓ | ✓ | ✘ | ✓ | ✓ |
| Light and Dark Theme | ✓ | ✓ | ✓ | ✓ | ✘ | ✘ | ✘ |
| Custom Theme Support | ✓ | ✘ | ✘ | ✘ | ✓ | ✓ | ✓ |
| Markdown support | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ |
| CSV support | ✓ | ✓ | ✘ | ✘ | ✓ | ✘ | ✘ |
| 'GitHub / GitLab pages' | [⚙️][gitea-pages-server], [⚙️][gitea-caddy-plugin] | ✓ | ✓ | ✓ | ✘ | ✘ | ✘ |
| Gists / Snippets | [⚙️][opengist] | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ |
| Repo-specific wiki (as a repo itself) | ✓ | ✓ | ✓ | ✓ | / | ✘ | ✘ |
| Deploy Tokens | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ |
| Repository Tokens with write rights | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ |
| RSS Feeds | ✓ | ✓ | ✘ | ✘ | ✘ | ✓ | ✓ |
| Built-in CI/CD | ✓ | ✓ | ✓ | ✓ | ✘ | ✘ | ✘ |
| Subgroups: groups within groups | [✘](https://github.com/go-gitea/gitea/issues/1872) | ✘ | ✓ | ✓ | ✘ | ✓ | ✓ |
| Interaction with other instances | [/](https://github.com/go-gitea/gitea/issues/18240) | ✘ | ✘ | ✘ | ✘ | ✘ | ✘ |
| Mermaid diagrams in Markdown | ✓ | ✓ | ✓ | ✓ | ✘ | ✘ | ✘ |
| Math syntax in Markdown | ✓ | ✓ | ✓ | ✓ | ✘ | ✓ | ✓ |
## Code management
| Feature | Gitea | GitHub EE | GitLab CE | GitLab EE | BitBucket | RhodeCode CE | RhodeCode EE |
| ------------------------------------------- | --------------------------------------------------- | --------- | --------- | --------- | --------- | ------------ | ------------ |
| Repository topics | ✓ | ✓ | ✓ | ✓ | ✘ | ✘ | ✘ |
| Repository code search | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ |
| Global code search | ✓ | ✓ | ✘ | ✓ | ✓ | ✓ | ✓ |
| Git LFS 2.0 | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ |
| Group Milestones | [✘](https://github.com/go-gitea/gitea/issues/14622) | ✘ | ✓ | ✓ | ✘ | ✘ | ✘ |
| Granular user roles (Code, Issues, Wiki, …) | ✓ | ✘ | ✓ | ✓ | ✘ | ✘ | ✘ |
| Verified Committer | ⁄ | ? | ✓ | ✓ | ✓ | ✘ | ✘ |
| GPG Signed Commits | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ |
| SSH Signed Commits | ✓ | ✓ | ✓ | ✓ | ? | ✘ | ✘ |
| Reject unsigned commits | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ |
| Migrating repos from other services | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ |
| Repository Activity page | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ |
| Branch manager | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ |
| Create new branches | ✓ | ✓ | ✓ | ✓ | ✘ | ✘ | ✘ |
| Web code editor | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ |
| Commit graph | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ |
| Template Repositories | ✓ | ✓ | ✘ | ✓ | ✓ | ✘ | ✘ |
| Git Blame | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ |
| Visual comparison of image changes | ✓ | ✓ | ? | ? | ? | ✘ | ✘ |
- Gitea has builtin repository-level code search
- Better code search support could be achieved by [using a repository indexer](../administration/repo-indexer.md)
## Issue Tracker
| Feature | Gitea | GitHub EE | GitLab CE | GitLab EE | BitBucket | RhodeCode CE | RhodeCode EE |
| ----------------------------- | --------------------------------------------------- | --------- | --------- | --------- | --------- | ------------ | ------------ |
| Issue tracker | ✓ | ✓ | ✓ | ✓ | / | ✘ | ✘ |
| Issue templates | ✓ | ✓ | ✓ | ✓ | ✘ | ✘ | ✘ |
| Labels | ✓ | ✓ | ✓ | ✓ | ✘ | ✘ | ✘ |
| Time tracking | ✓ | ✓ | ✓ | ✓ | ✘ | ✘ | ✘ |
| Multiple assignees for issues | ✓ | ✓ | ✘ | ✓ | ✘ | ✘ | ✘ |
| Related issues | ✘ | ⁄ | ✓ | ✓ | ✘ | ✘ | ✘ |
| Confidential issues | [✘](https://github.com/go-gitea/gitea/issues/3217) | ✘ | ✓ | ✓ | ✘ | ✘ | ✘ |
| Comment reactions | ✓ | ✓ | ✓ | ✓ | ✘ | ✘ | ✘ |
| Lock Discussion | ✓ | ✓ | ✓ | ✓ | ✘ | ✘ | ✘ |
| Batch issue handling | ✓ | ✓ | ✓ | ✓ | ✘ | ✘ | ✘ |
| Projects | [/](https://github.com/go-gitea/gitea/issues/14710) | ✘ | ✓ | ✓ | ✘ | ✘ | ✘ |
| Create branch from issue | [✘](https://github.com/go-gitea/gitea/issues/20226) | ✘ | ✓ | ✓ | ✘ | ✘ | ✘ |
| Convert comment to new issue | ✓ | ✓ | ✓ | ✓ | ✘ | ✘ | ✘ |
| Issue search | ✓ | ✓ | ✓ | ✓ | ✓ | ✘ | ✘ |
| Global issue search | [/](https://github.com/go-gitea/gitea/issues/2434) | ✓ | ✓ | ✓ | ✓ | ✘ | ✘ |
| Issue dependency | ✓ | ✘ | ✘ | ✘ | ✘ | ✘ | ✘ |
| Create issue via email | [✘](https://github.com/go-gitea/gitea/issues/6226) | ✘ | ✓ | ✓ | ✓ | ✘ | ✘ |
| Service Desk | [✘](https://github.com/go-gitea/gitea/issues/6219) | ✘ | ✓ | ✓ | ✘ | ✘ | ✘ |
## Pull/Merge requests
| Feature | Gitea | GitHub EE | GitLab CE | GitLab EE | BitBucket | RhodeCode CE | RhodeCode EE |
| ----------------------------------------------- | -------------------------------------------------- | --------- | --------- | --------- | --------- | ------------ | ------------ |
| Pull/Merge requests | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ |
| Squash merging | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ |
| Rebase merging | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ |
| Pull/Merge request inline comments | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ |
| Pull/Merge request approval | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ |
| Pull/Merge require approval | ✓ | ✓ | ✘ | ✓ | ✓ | ✓ | ✓ |
| Pull/Merge multiple reviewers | ✓ | ✓ | ✘ | ✓ | ✓ | ✓ | ✓ |
| Merge conflict resolution | [✘](https://github.com/go-gitea/gitea/issues/9014) | ✓ | ✓ | ✓ | ✓ | ✘ | ✘ |
| Restrict push and merge access to certain users | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ |
| Revert specific commits | ✓ | ✓ | ✓ | ✓ | ✓ | ✘ | ✘ |
| Pull/Merge requests templates | ✓ | ✓ | ✓ | ✓ | ✘ | ✘ | ✘ |
| Cherry-picking changes | ✓ | ✘ | ✓ | ✓ | ✘ | ✘ | ✓ |
| Download Patch | ✓ | ✓ | ✓ | ✓ | / | ✓ | ✓ |
| Merge queues | ✓ | ✓ | ✘ | ✓ | ✘ | ✘ | ✘ |
## 3rd-party integrations
| Feature | Gitea | GitHub EE | GitLab CE | GitLab EE | BitBucket | RhodeCode CE | RhodeCode EE |
| ---------------------------------------------- | -------------------------------------------------- | --------- | --------- | --------- | --------- | ------------ | ------------ |
| Webhooks | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ |
| Git Hooks | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ |
| AD / LDAP integration | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ |
| Multiple LDAP / AD server support | ✓ | ✘ | ✘ | ✓ | ✓ | ✓ | ✓ |
| LDAP user synchronization | ✓ | ✓ | ✓ | ✓ | ✓ | ✘ | ✓ |
| SAML 2.0 service provider | [✘](https://github.com/go-gitea/gitea/issues/5512) | ✓ | ✓ | ✓ | ✓ | ✘ | ✓ |
| OpenID Connect support | ✓ | ✓ | ✓ | ✓ | ? | ✘ | ✓ |
| OAuth 2.0 integration (external authorization) | ✓ | ⁄ | ✓ | ✓ | ? | ✘ | ✓ |
| Act as OAuth 2.0 provider | ✓ | ✓ | ✓ | ✓ | ✓ | ✘ | ✘ |
| Two factor authentication (2FA) | ✓ | ✓ | ✓ | ✓ | ✓ | ✘ | ✓ |
| Integration with the most common services | ✓ | ⁄ | ✓ | ✓ | ⁄ | ✓ | ✓ |
| Incorporate external CI/CD | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ |
[gitea-caddy-plugin]: https://github.com/42wim/caddy-gitea
[gitea-pages-server]: https://codeberg.org/Codeberg/pages-server
[opengist]: https://github.com/thomiceli/opengist

311
versioned_docs/version-1.25/installation/database-preparation.md Normal file
View File

@@ -0,0 +1,311 @@
---
date: "2020-01-16"
slug: "database-prep"
sidebar_position: 10
aliases:
- /en-us/database-prep
---
# Database Preparation
You need a database to use Gitea. Gitea supports PostgreSQL (>= 12), MySQL (>= 8.0), MariaDB (>= 10.4), SQLite (builtin), and MSSQL (>= 2012 SP4). This page will guide into preparing database. Only PostgreSQL and MySQL will be covered here since those database engines are widely-used in production. If you plan to use SQLite, you can ignore this chapter.
:::warning
Converting one database type to another is not a well-tested process and you may experience issues. It is better to choose the final database type at the type of the first installation. Be aware that SQLite does not scale; if you expect your instance to grow at a later time, you should choose another database type.
:::
If you use an unsupported database version, please [get in touch](/help/support) with us for information on our Extended Support Contracts. We can provide testing and support for older databases and integrate those fixes into the Gitea codebase.
Database instance can be on same machine as Gitea (local database setup), or on different machine (remote database).
:::note
All steps below requires that the database engine of your choice is installed on your system. For remote database setup, install the server application on database instance and client program on your Gitea server. The client program is used to test connection to the database from Gitea server, while Gitea itself use database driver provided by Go to accomplish the same thing. 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.
:::
## MySQL/MariaDB
1. For remote database setup, you will need to make MySQL listen to your IP address. Configure the `bind-address` option in `/etc/mysql/my.cnf` on database instance by adding the following lines:
```ini
[mysqld]
bind-address = 203.0.113.3
```
2. On database instance, login to database console as root:
```sh
mysql -u root -p
```
Enter the password as prompted.
3. Create database user which will be used by Gitea, authenticated by password. This example uses `'gitea'` as password. Please use a secure password for your instance.
For local database:
```sql
SET old_passwords=0;
CREATE USER 'gitea'@'%' IDENTIFIED BY 'gitea';
```
For remote database:
```sql
SET old_passwords=0;
CREATE USER 'gitea'@'192.0.2.10' IDENTIFIED BY 'gitea';
```
where `192.0.2.10` is the IP address of your Gitea instance.
Replace username and password above as appropriate.
4. Create database with UTF-8 charset and case-sensitive collation.
`utf8mb4_bin` is a common collation for both MySQL/MariaDB.
When Gitea starts, it will try to find a better collation (`utf8mb4_0900_as_cs` or `uca1400_as_cs`) and alter the database if it is possible.
If you would like to use other collation, you can set `[database].CHARSET_COLLATION` in the `app.ini` file.
```sql
CREATE DATABASE giteadb CHARACTER SET 'utf8mb4' COLLATE 'utf8mb4_bin';
```
Replace database name as appropriate.
5. Grant all privileges on the database to database user created above.
For local database:
```sql
GRANT ALL PRIVILEGES ON giteadb.* TO 'gitea';
FLUSH PRIVILEGES;
```
For remote database:
```sql
GRANT ALL PRIVILEGES ON giteadb.* TO 'gitea'@'192.0.2.10';
FLUSH PRIVILEGES;
```
6. Quit from database console by `exit`.
7. On your Gitea server, test connection to the database:
```
mysql -u gitea -h 203.0.113.3 -p giteadb
```
where `gitea` is database username, `giteadb` is database name, and `203.0.113.3` is IP address of database instance. Omit `-h` option for local database.
You should be connected to the database.
## PostgreSQL
1. For remote database setup, configure PostgreSQL on database instance to listen to your IP address by editing `listen_addresses` on `postgresql.conf` to:
```ini
listen_addresses = 'localhost, 203.0.113.3'
```
2. PostgreSQL uses `md5` challenge-response encryption scheme for password authentication by default. Nowadays this scheme is not considered secure anymore. Use SCRAM-SHA-256 scheme instead by editing the `postgresql.conf` configuration file on the database server to:
```ini
password_encryption = scram-sha-256
```
Restart PostgreSQL to apply the setting.
3. On the database server, login to the database console as superuser:
```
su -c "psql" - postgres
```
4. Create database user (role in PostgreSQL terms) with login privilege and password. Please use a secure, strong password instead of `'gitea'` below:
```sql
CREATE ROLE gitea WITH LOGIN PASSWORD 'gitea';
```
Replace username and password as appropriate.
5. Create database with UTF-8 charset and owned by the database user created earlier. Any `libc` collations can be specified with `LC_COLLATE` and `LC_CTYPE` parameter, depending on expected content:
```sql
CREATE DATABASE giteadb WITH OWNER gitea TEMPLATE template0 ENCODING UTF8 LC_COLLATE 'en_US.UTF-8' LC_CTYPE 'en_US.UTF-8';
```
Replace database name as appropriate.
6. Allow the database user to access the database created above by adding the following authentication rule to `pg_hba.conf`.
For local database:
```ini
local giteadb gitea scram-sha-256
```
For remote database:
```ini
host giteadb gitea 192.0.2.10/32 scram-sha-256
```
Replace database name, user, and IP address of Gitea instance with your own.
:::note
Rules on `pg_hba.conf` are evaluated sequentially, that is the first matching rule will be used for authentication. Your PostgreSQL installation may come with generic authentication rules that match all users and databases. You may need to place the rules presented here above such generic rules if it is the case.
:::
Restart PostgreSQL to apply new authentication rules.
7. On your Gitea server, test connection to the database.
For local database:
```bash
psql -U gitea -d giteadb
```
For remote database:
```bash
psql "postgres://gitea@203.0.113.3/giteadb"
```
where `gitea` is database user, `giteadb` is database name, and `203.0.113.3` is IP address of your database instance.
You should be prompted to enter password for the database user, and connected to the database.
## Database Connection over TLS
If the communication between Gitea and your database instance is performed through a private network, or if Gitea and the database are running on the same server, this section can be omitted since the security between Gitea and the database instance is not critically exposed. If instead the database instance is on a public network, use TLS to encrypt the connection to the database, as it is possible for third-parties to intercept the traffic data.
### Prerequisites
- You need two valid TLS certificates, one for the database instance (database server) and one for the Gitea instance (database client). Both certificates must be signed by a trusted CA.
- The database certificate must contain `TLS Web Server Authentication` in the `X509v3 Extended Key Usage` extension attribute, while the client certificate needs `TLS Web Client Authentication` in the corresponding attribute.
- On the database server certificate, one of `Subject Alternative Name` or `Common Name` entries must be the fully-qualified domain name (FQDN) of the database instance (e.g. `db.example.com`). On the database client certificate, one of the entries mentioned above must contain the database username that Gitea will be using to connect.
- You need domain name mappings of both Gitea and database servers to their respective IP addresses. Either set up DNS records for them or add local mappings to `/etc/hosts` (`%WINDIR%\System32\drivers\etc\hosts` in Windows) on each system. This allows the database connections to be performed by domain name instead of IP address. See documentation of your system for details.
### PostgreSQL TLS
The PostgreSQL driver used by Gitea supports two-way TLS. In two-way TLS, both database client and server authenticate each other by sending their respective certificates to their respective opposite for validation. In other words, the server verifies client certificate, and the client verifies server certificate.
1. On the server with the database instance, place the following credentials:
- `/path/to/postgresql.crt`: Database instance certificate
- `/path/to/postgresql.key`: Database instance private key
- `/path/to/root.crt`: CA certificate chain to validate client certificates
2. Add following options to `postgresql.conf`:
```ini
ssl = on
ssl_ca_file = '/path/to/root.crt'
ssl_cert_file = '/path/to/postgresql.crt'
ssl_key_file = '/path/to/postgresql.key'
ssl_min_protocol_version = 'TLSv1.2'
```
3. Adjust credentials ownership and permission, as required by PostgreSQL:
```
chown postgres:postgres /path/to/root.crt /path/to/postgresql.crt /path/to/postgresql.key
chmod 0600 /path/to/root.crt /path/to/postgresql.crt /path/to/postgresql.key
```
4. Edit `pg_hba.conf` rule to only allow Gitea database user to connect over SSL, and to require client certificate verification.
For PostgreSQL 12:
```ini
hostssl giteadb gitea 192.0.2.10/32 scram-sha-256 clientcert=verify-full
```
For PostgreSQL 11 and earlier:
```ini
hostssl giteadb gitea 192.0.2.10/32 scram-sha-256 clientcert=1
```
Replace database name, user, and IP address of Gitea instance as appropriate.
5. Restart PostgreSQL to apply configurations above.
6. On the server running the Gitea instance, place the following credentials under the home directory of the user who runs Gitea (e.g. `git`):
- `~/.postgresql/postgresql.crt`: Database client certificate
- `~/.postgresql/postgresql.key`: Database client private key
- `~/.postgresql/root.crt`: CA certificate chain to validate server certificate
:::note
Those file names above are hardcoded in PostgreSQL and it is not possible to change them.
:::
7. Adjust credentials, ownership and permission as required:
```
chown git:git ~/.postgresql/postgresql.crt ~/.postgresql/postgresql.key ~/.postgresql/root.crt
chown 0600 ~/.postgresql/postgresql.crt ~/.postgresql/postgresql.key ~/.postgresql/root.crt
```
8. Test the connection to the database:
```
psql "postgres://gitea@example.db/giteadb?sslmode=verify-full"
```
You should be prompted to enter password for the database user, and then be connected to the database.
### MySQL/MariaDB TLS
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:
- `/path/to/mysql.crt`: Database instance certificate
- `/path/to/mysql.key`: Database instance key
- `/path/to/ca.crt`: CA certificate chain. This file isn't used on one-way TLS, but is used to validate client certificates on two-way TLS.
2. Add following options to `my.cnf`:
```ini
[mysqld]
ssl-ca = /path/to/ca.crt
ssl-cert = /path/to/mysql.crt
ssl-key = /path/to/mysql.key
tls-version = TLSv1.2,TLSv1.3
```
3. Adjust credentials ownership and permission:
```
chown mysql:mysql /path/to/ca.crt /path/to/mysql.crt /path/to/mysql.key
chmod 0600 /path/to/ca.crt /path/to/mysql.crt /path/to/mysql.key
```
4. Restart MySQL to apply the setting.
5. The database user for Gitea may have been created earlier, but it would authenticate only against the IP addresses of the server running Gitea. To authenticate against its domain name, recreate the user, and this time also set it to require TLS for connecting to the database:
```sql
DROP USER 'gitea'@'192.0.2.10';
CREATE USER 'gitea'@'example.gitea' IDENTIFIED BY 'gitea' REQUIRE SSL;
GRANT ALL PRIVILEGES ON giteadb.* TO 'gitea'@'example.gitea';
FLUSH PRIVILEGES;
```
Replace database user name, password, and Gitea instance domain as appropriate.
6. Make sure that the CA certificate chain required to validate the database server certificate is on the system certificate store of both the database and Gitea servers. Consult your system documentation for instructions on adding a CA certificate to the certificate store.
7. On the server running Gitea, test connection to the database:
```
mysql -u gitea -h example.db -p --ssl
```
You should be connected to the database.

240
versioned_docs/version-1.25/installation/from-binary.md Normal file
View File

@@ -0,0 +1,240 @@
---
date: "2017-06-19T12:00:00+02:00"
slug: "install-from-binary"
sidebar_position: 15
aliases:
- /en-us/install-from-binary
---
# Installation from binary
All downloads come with SQLite, MySQL and PostgreSQL support, and are built with
embedded assets. This can be different from Gogs.
## Download
You can find the file matching your platform from the [downloads page](https://dl.gitea.com/gitea/) after navigating to the version you want to download.
### Choosing the right file
**For Linux**, you will likely want `linux-amd64`. It's for 64-bit Intel/AMD platforms, but there are other platforms available, including `arm64` (e.g. Raspberry PI 4), `386` (i.e. 32-bit), `arm-5`, and `arm-6`.
**For Windows**, you will likely want `windows-4.0-amd64`. It's for all modern versions of Windows, but there is also a `386` platform available designed for older, 32-bit versions of Windows.
:::info
There is also a `gogit-windows` file available that was created to help with some [performance problems](https://github.com/go-gitea/gitea/pull/15482) reported by some Windows users on older systems/versions. You should consider using this file if you're experiencing performance issues, and let us know if it improves performance.
:::
**For macOS**, you should choose `darwin-arm64` if your hardware uses Apple Silicon, or `darwin-amd64` for Intel.
**For FreeBSD**, you should choose `freebsd12-amd64` for 64-bit Intel/AMD platforms.
### Downloading with wget
Copy the commands below and replace the URL within the one you wish to download.
```shell
wget -O gitea https://dl.gitea.com/gitea/@version@/gitea-@version@-linux-amd64
chmod +x gitea
```
Note that the above command will download Gitea @version@ for 64-bit Linux.
## Verify GPG signature
Gitea signs all binaries with a [GPG key](https://keys.openpgp.org/search?q=teabot%40gitea.io) 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.
```sh
gpg --keyserver hkps://keys.openpgp.org --recv 7C9E68152594688862D62AF62D9AE806EC1592E2
gpg --verify gitea-@version@-linux-amd64.asc gitea-@version@-linux-amd64
```
Look for the text `Good signature from "Teabot <teabot@gitea.io>"` to assert a good binary,
despite warnings like `This key is not certified with a trusted signature!`.
## Recommended server configuration
:::note
Many of the following directories can be configured using [Environment Variables](../administration/environment-variables.md) as well!
Of note, configuring `GITEA_WORK_DIR` will tell Gitea where to base its working directory, as well as ease installation.
:::
### Prepare environment
Check that Git is installed on the server. If it is not, install it first. Gitea requires Git version >= 2.0.
```sh
git --version
```
Create a user to run Gitea (e.g. `git`)
```sh
# On Ubuntu/Debian:
adduser \
--system \
--shell /bin/bash \
--gecos 'Git Version Control' \
--group \
--disabled-password \
--home /home/git \
git
# On Fedora/RHEL/CentOS:
groupadd --system git
adduser \
--system \
--shell /bin/bash \
--comment 'Git Version Control' \
--gid git \
--home-dir /home/git \
--create-home \
git
```
### Create required directory structure
```sh
mkdir -p /var/lib/gitea/{custom,data,log}
chown -R git:git /var/lib/gitea/
chmod -R 750 /var/lib/gitea/
mkdir /etc/gitea
chown root:git /etc/gitea
chmod 770 /etc/gitea
```
:::note
> `/etc/gitea` is temporarily set with write permissions for user `git` so that the web installer can write the configuration file. After the installation is finished, it is recommended to set permissions to read-only using:
:::
>
> ```sh
> chmod 750 /etc/gitea
> chmod 640 /etc/gitea/app.ini
> ```
If you don't want the web installer to be able to write to the config file, it is possible to make the config file read-only for the Gitea user (owner/group `root:git`, mode `0640`) however you will need to edit your config file manually to:
* Set `INSTALL_LOCK= true`,
* Ensure all database configuration details are set correctly
* Ensure that the `SECRET_KEY` and `INTERNAL_TOKEN` values are set. (You may want to use the `gitea generate secret` to generate these secret keys.)
* Ensure that any other secret keys you need are set.
See the [command line documentation](../administration/command-line.md) for information on using `gitea generate secret`.
### Configure Gitea's working directory
:::note
If you plan on running Gitea as a Linux service, you can skip this step, as the service file allows you to set `WorkingDirectory`. Otherwise, consider setting this environment variable (semi-)permanently so that Gitea consistently uses the correct working directory.
:::
```sh
export GITEA_WORK_DIR=/var/lib/gitea/
```
### Copy the Gitea binary to a global location
```sh
cp gitea /usr/local/bin/gitea
```
### Adding bash/zsh autocompletion (from 1.19)
A script to enable bash-completion can be found at [`contrib/autocompletion/bash_autocomplete`](https://raw.githubusercontent.com/go-gitea/gitea/main/contrib/autocompletion/bash_autocomplete). This can be copied to `/usr/share/bash-completion/completions/gitea`
or sourced within your `.bashrc`.
Similarly a script for zsh-completion can be found at [`contrib/autocompletion/zsh_autocomplete`](https://raw.githubusercontent.com/go-gitea/gitea/main/contrib/autocompletion/zsh_autocomplete). This can be copied to `/usr/share/zsh/_gitea` or sourced within your
`.zshrc`.
YMMV and these scripts may need further improvement.
## Running Gitea
After you complete the above steps, you can run Gitea two ways:
### 1. Creating a service file to start Gitea automatically (recommended)
See how to create [Linux service](installation/run-as-service-in-ubuntu.md)
### 2. Running from command-line/terminal
```sh
GITEA_WORK_DIR=/var/lib/gitea/ /usr/local/bin/gitea web -c /etc/gitea/app.ini
```
## 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.
The binary file name should not be changed during the update to avoid problems in existing repositories.
It is recommended that you make a [backup](../administration/backup-and-restore.md) before updating your installation.
If you have carried out the installation steps as described above, the binary should
have the generic name `gitea`. Do not change this, i.e. to include the version number.
### 1. Restarting Gitea with systemd (recommended)
As we explained before, we recommend to use systemd as the service manager. In this case, `systemctl restart gitea` should be fine.
### 2. Restarting Gitea without systemd
To restart your Gitea instance, we recommend to use SIGHUP signal. If you know your Gitea PID, use `kill -1 $GITEA_PID`, otherwise you can use `killall -1 gitea`.
To gracefully stop the Gitea instance, a simple `kill $GITEA_PID` or `killall gitea` is enough.
:::note
We don't recommend to use the SIGKILL signal (`-9`); you may be forcefully stopping some of Gitea's internal tasks, and it will not gracefully stop (tasks in queues, indexers, etc.)
:::
See below for troubleshooting instructions to repair broken repositories after
an update of your Gitea version.
## Troubleshooting
### Old glibc versions
Older Linux distributions (such as Debian 7 and CentOS 6) may not be able to load the
Gitea binary, usually producing an error such as `./gitea: /lib/x86_64-linux-gnu/libc.so.6:
version 'GLIBC\_2.14' not found (required by ./gitea)`. This is due to the integrated
SQLite support in the binaries provided by dl.gitea.com. In this situation, it is usually
possible to [install from source](installation/from-source.md), without including
SQLite support.
### Running Gitea on another port
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
is possible using `./gitea web -p $PORT`. It's possible another instance of Gitea
is already running.
### Running Gitea on Raspbian
As of v1.8, there is a problem with the arm7 version of Gitea, and it doesn't run on Raspberry Pis and similar devices.
It is recommended to switch to the arm6 version, which has been tested and shown to work on Raspberry Pis and similar devices.
<!---
please remove after fixing the arm7 bug
--->
### Git error after updating to a new version of Gitea
If during the update, the binary file name has been changed to a new version of Gitea,
Git Hooks in existing repositories will not work any more. In that case, a Git
error will be displayed when pushing to the repository.
```
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
binary.
To solve this, go to the admin options and run the task `Resynchronize pre-receive,
update and post-receive hooks of all repositories` to update all hooks to contain
the new binary path. Please note that this overwrites all Git Hooks, including ones
with customizations made.
If you aren't using the Gitea built-in SSH server, you will also need to re-write
the authorized key file by running the `Update the '.ssh/authorized_keys' file with
Gitea SSH keys.` task in the admin options.

109
versioned_docs/version-1.25/installation/from-package.md Normal file
View File

@@ -0,0 +1,109 @@
---
date: "2016-12-01T16:00:00+02:00"
slug: "install-from-package"
sidebar_position: 20
aliases:
- /en-us/install-from-package
---
# Installation from Package
## Official packages
### macOS
Currently, the only supported method of installation on MacOS is [Homebrew](http://brew.sh/).
Following the [deployment from binary](installation/from-binary.md) guide may work,
but is not supported. To install Gitea via `brew`:
```
brew install gitea
```
## Unofficial packages
### Alpine Linux
Alpine Linux has [Gitea](https://pkgs.alpinelinux.org/packages?name=gitea&branch=edge) in its community repository which follows the latest stable version.
```sh
apk add gitea
```
### Arch Linux
The rolling release distribution has [Gitea](https://www.archlinux.org/packages/extra/x86_64/gitea/) in their official extra repository and package updates are provided with new Gitea releases.
```sh
pacman -S gitea
```
### Arch Linux ARM
Arch Linux ARM provides packages for [aarch64](https://archlinuxarm.org/packages/aarch64/gitea), [armv7h](https://archlinuxarm.org/packages/armv7h/gitea) and [armv6h](https://archlinuxarm.org/packages/armv6h/gitea).
```sh
pacman -S gitea
```
### Gentoo Linux
The rolling release distribution has [Gitea](https://packages.gentoo.org/packages/www-apps/gitea) in their official community repository and package updates are provided with new Gitea releases.
```sh
emerge gitea -va
```
### Canonical Snap
There is a [Gitea Snap](https://snapcraft.io/gitea) package which follows the latest stable version.
*Note: The Gitea snap package is [strictly confined](https://snapcraft.io/docs/snap-confinement). Strictly confined snaps run in complete isolation, so some of the Gitea functionals may not work with the confinement*
```sh
snap install gitea
```
### SUSE and openSUSE
OpenSUSE build service provides packages for [openSUSE and SLE](https://software.opensuse.org/download/package?package=gitea&project=devel%3Atools%3Ascm)
in the Development Software Configuration Management Repository
### Windows
There is a [Gitea](https://chocolatey.org/packages/gitea) package for Windows by [Chocolatey](https://chocolatey.org/).
```sh
choco install gitea
```
Or follow the [deployment from binary](installation/from-binary.md) guide.
### FreeBSD
A FreeBSD port `www/gitea` is available. To install the pre-built binary package:
```
pkg install gitea
```
For the most up to date version, or to build the port with custom options,
[install it from the port](https://www.freebsd.org/doc/handbook/ports-using.html):
```
su -
cd /usr/ports/www/gitea
make install clean
```
The port uses the standard FreeBSD file system layout: config files are in `/usr/local/etc/gitea`,
bundled templates, options, plugins and themes are in `/usr/local/share/gitea`, and a start script
is in `/usr/local/etc/rc.d/gitea`.
To enable Gitea to run as a service, run `sysrc gitea_enable=YES` and start it with `service gitea start`.
### Others
Various other third-party packages of Gitea exist.
To see a curated list, head over to [awesome-gitea](https://gitea.com/gitea/awesome-gitea/src/branch/master/README.md#user-content-packages).
Do you know of an existing package that isn't on the list? Send in a PR to get it added!

255
versioned_docs/version-1.25/installation/from-source.md Normal file
View File

@@ -0,0 +1,255 @@
---
date: "2016-12-01T16:00:00+02:00"
slug: "install-from-source"
sidebar_position: 30
aliases:
- /en-us/install-from-source
---
# Installation from source
You should [install go](https://go.dev/doc/install) and set up your go
environment correctly. In particular, it is recommended to set the `$GOPATH`
environment variable and to add the go bin directory or directories
`${GOPATH//://bin:}/bin` to the `$PATH`. See the Go wiki entry for
[GOPATH](https://github.com/golang/go/wiki/GOPATH).
Next, [install Node.js with npm](https://nodejs.org/en/download/) which is
required to build the JavaScript and CSS files. The minimum supported Node.js
version is @minNodeVersion@ and the latest LTS version is recommended.
:::note
Go version @minGoVersion@ or higher is required. However, it is recommended to
obtain the same version as our continuous integration, see the advice given in
[Hacking on Gitea](development/hacking-on-gitea.md)
:::
## Download
First, we must retrieve the source code. Since, the advent of go modules, the
simplest way of doing this is to use Git directly as we no longer have to have
Gitea built from within the GOPATH.
```bash
git clone https://github.com/go-gitea/gitea
```
(Previous versions of this document recommended using `go get`. This is
no longer necessary.)
Decide which version of Gitea to build and install. Currently, there are
multiple options to choose from. The `main` branch represents the current
development version. To build with main, skip to the [build section](#build).
To work with tagged releases, the following commands can be used:
```bash
git branch -a
git checkout @sourceBranch@
```
To validate a Pull Request, first enable the new branch (`xyz` is the PR id;
for example `2663` for [#2663](https://github.com/go-gitea/gitea/pull/2663)):
```bash
git fetch origin pull/xyz/head:pr-xyz
```
To build Gitea from source at a specific tagged release (like @sourceVersion@), list the
available tags and check out the specific tag.
List available tags with the following.
```bash
git tag -l
git checkout @sourceVersion@ # or git checkout pr-xyz
```
## Build
To build from source, the following programs must be present on the system:
- `go` @minGoVersion@ or higher, see [here](https://go.dev/dl/)
- `node` @minNodeVersion@ or higher with `npm`, see [here](https://nodejs.org/en/download/)
- `make`, see [here](development/hacking-on-gitea.md#installing-make)
Various [make tasks](https://github.com/go-gitea/gitea/blob/main/Makefile)
are provided to keep the build process as simple as possible.
Depending on requirements, the following build tags can be included.
- `bindata`: Build a single monolithic binary, with all assets included. Required for production build.
- `sqlite sqlite_unlock_notify`: Enable support for a
[SQLite3](https://sqlite.org/) database. Suggested only for tiny
installations.
- `pam`: Enable support for PAM (Linux Pluggable Authentication Modules). Can
be used to authenticate local users or extend authentication to methods
available to PAM.
- `gogit`: (EXPERIMENTAL) Use go-git variants of Git commands.
Bundling all assets (JS/CSS/templates, etc) into the binary. Using the `bindata` build tag is required for
production deployments. You could exclude `bindata` when you are developing/testing Gitea or able to separate the assets correctly.
To include all assets, use the `bindata` tag:
```bash
TAGS="bindata" make build
```
In the default release build of our continuous integration system, the build
tags are: `TAGS="bindata sqlite sqlite_unlock_notify"`. The simplest
recommended way to build from source is therefore:
```bash
TAGS="bindata sqlite sqlite_unlock_notify" make build
```
The `build` target is split into two sub-targets:
- `make backend` which requires [Go @minGoVersion@](https://go.dev/dl/) or greater.
- `make frontend` which requires [Node.js @minNodeVersion@](https://nodejs.org/en/download/) or greater.
If pre-built frontend files are present it is possible to only build the backend:
```bash
TAGS="bindata" make backend
```
## Test
After following the steps above, a `gitea` binary will be available in the working directory.
It can be tested from this directory or moved to a directory with test data. When Gitea is
launched manually from command line, it can be killed by pressing `Ctrl + C`.
```bash
./gitea web
```
## Changing default paths
Gitea will search for a number of things from the _`CustomPath`_. By default this is
the `custom/` directory in the current working directory when running Gitea. It will also
look for its configuration file _`CustomConf`_ in `$(CustomPath)/conf/app.ini`, and will use the
current working directory as the relative base path _`AppWorkPath`_ for a number configurable
values. Finally the static files will be served from _`StaticRootPath`_ which defaults to the _`AppWorkPath`_.
These values, although useful when developing, may conflict with downstream users preferences.
One option is to use a script file to shadow the `gitea` binary and create an appropriate
environment before running Gitea. However, when building you can change these defaults
using the `LDFLAGS` environment variable for `make`. The appropriate settings are as follows
- To set the _`CustomPath`_ use `LDFLAGS="-X \"code.gitea.io/gitea/modules/setting.CustomPath=custom-path\""`
- For _`CustomConf`_ you should use `-X \"code.gitea.io/gitea/modules/setting.CustomConf=conf.ini\"`
- For _`AppWorkPath`_ you should use `-X \"code.gitea.io/gitea/modules/setting.AppWorkPath=working-path\"`
- For _`StaticRootPath`_ you should use `-X \"code.gitea.io/gitea/modules/setting.StaticRootPath=static-root-path\"`
- To change the default PID file location use `-X \"code.gitea.io/gitea/cmd.PIDFile=/run/gitea.pid\"`
Add as many of the strings with their preceding `-X` to the `LDFLAGS` variable and run `make build`
with the appropriate `TAGS` as above.
Running `gitea help` will allow you to review what the computed settings will be for your `gitea`.
## Cross Build
The `go` compiler toolchain supports cross-compiling to different architecture targets that are supported by the toolchain. See [`GOOS` and `GOARCH` environment variable](https://go.dev/doc/install/source#environment) for the list of supported targets. Cross compilation is helpful if you want to build Gitea for less-powerful systems (such as Raspberry Pi).
To cross build Gitea with build tags (`TAGS`), you also need a C cross compiler which targets the same architecture as selected by the `GOOS` and `GOARCH` variables. For example, to cross build for Linux ARM64 (`GOOS=linux` and `GOARCH=arm64`), you need the `aarch64-unknown-linux-gnu-gcc` cross compiler. This is required because Gitea build tags uses `cgo`'s foreign-function interface (FFI).
Cross-build Gitea for Linux ARM64, without any tags:
```
GOOS=linux GOARCH=arm64 make build
```
Cross-build Gitea for Linux ARM64, with recommended build tags:
```
CC=aarch64-unknown-linux-gnu-gcc GOOS=linux GOARCH=arm64 TAGS="bindata sqlite sqlite_unlock_notify" make build
```
Replace `CC`, `GOOS`, and `GOARCH` as appropriate for your architecture target.
You will sometimes need to build a static compiled image. To do this you will need to add:
```
LDFLAGS="-linkmode external -extldflags '-static' $LDFLAGS" TAGS="netgo osusergo $TAGS" make build
```
This can be combined with `CC`, `GOOS`, and `GOARCH` as above.
### Adding bash/zsh autocompletion (from 1.19)
A script to enable bash-completion can be found at [`contrib/autocompletion/bash_autocomplete`](https://raw.githubusercontent.com/go-gitea/gitea/main/contrib/autocompletion/bash_autocomplete). This should be altered as appropriate and can be `source` in your `.bashrc`
or copied as `/usr/share/bash-completion/completions/gitea`.
Similarly, a script for zsh-completion can be found at [`contrib/autocompletion/zsh_autocomplete`](https://raw.githubusercontent.com/go-gitea/gitea/main/contrib/autocompletion/zsh_autocomplete). This can be copied to `/usr/share/zsh/_gitea` or sourced within your
`.zshrc`.
YMMV and these scripts may need further improvement.
## Compile or cross-compile using Linux with Zig
Follow [Getting Started of Zig](https://ziglang.org/learn/getting-started/#installing-zig) to install zig.
- Compile (Linux ➝ Linux)
```sh
CC="zig cc -target x86_64-linux-gnu" \
CGO_ENABLED=1 \
CGO_CFLAGS="-O2 -g -pthread" \
CGO_LDFLAGS="-linkmode=external -v"
GOOS=linux \
GOARCH=amd64 \
TAGS="bindata sqlite sqlite_unlock_notify" \
make build
```
- Cross-compile (Linux ➝ Windows)
```sh
CC="zig cc -target x86_64-windows-gnu" \
CGO_ENABLED=1 \
CGO_CFLAGS="-O2 -g -pthread" \
GOOS=windows \
GOARCH=amd64 \
TAGS="bindata sqlite sqlite_unlock_notify" \
make build
```
## Compile or cross-compile with Zig using Windows
Compile with `GIT BASH`.
- Compile (Windows ➝ Windows)
```sh
CC="zig cc -target x86_64-windows-gnu" \
CGO_ENABLED=1 \
CGO_CFLAGS="-O2 -g -pthread" \
GOOS=windows \
GOARCH=amd64 \
TAGS="bindata sqlite sqlite_unlock_notify" \
make build
```
- Cross-compile (Windows ➝ Linux)
```sh
CC="zig cc -target x86_64-linux-gnu" \
CGO_ENABLED=1 \
CGO_CFLAGS="-O2 -g -pthread" \
CGO_LDFLAGS="-linkmode=external -v"
GOOS=linux \
GOARCH=amd64 \
TAGS="bindata sqlite sqlite_unlock_notify" \
make build
```
## Source Maps
By default, gitea generates reduced source maps for frontend files to conserve space. This can be controlled with the `ENABLE_SOURCEMAP` environment variable:
- `ENABLE_SOURCEMAP=true` generates all source maps, the default for development builds
- `ENABLE_SOURCEMAP=reduced` generates limited source maps, the default for production builds
- `ENABLE_SOURCEMAP=false` generates no source maps

43
versioned_docs/version-1.25/installation/on-cloud-provider.md Normal file
View File

@@ -0,0 +1,43 @@
---
date: "2016-12-01T16:00:00+02:00"
slug: "install-on-cloud-provider"
sidebar_position: 90
aliases:
- /en-us/install-on-cloud-provider
---
# Installation on Cloud Provider
## Cloudron
Gitea is available as a 1-click install on [Cloudron](https://cloudron.io).
Cloudron makes it easy to run apps like Gitea on your server and keep them up-to-date and secure.
[![Install](/cloudron.svg)](https://cloudron.io/button.html?app=io.gitea.cloudronapp)
The Gitea package is maintained [here](https://git.cloudron.io/cloudron/gitea-app).
There is a [demo instance](https://my.demo.cloudron.io) (username: cloudron password: cloudron) where
you can experiment with running Gitea.
## Linode
[Linode](https://www.linode.com/) has Gitea as an app in their marketplace.
To deploy Gitea to Linode, have a look at the [Linode Marketplace](https://www.linode.com/marketplace/apps/linode/gitea/).
## alwaysdata
[alwaysdata](https://www.alwaysdata.com/) has Gitea as an app in their marketplace.
To deploy Gitea to alwaysdata, have a look at the [alwaysdata Marketplace](https://www.alwaysdata.com/en/marketplace/gitea/).
## Exoscale
[Exoscale](https://www.exoscale.com/) provides Gitea managed by [Glasskube](https://glasskube.eu/) in their marketplace.
Exoscale is a European cloud service provider.
The package is maintained and update via the open source [Glasskube Kubernetes Operator](https://github.com/glasskube/operator).
To deploy Gitea to Exoscale, have a look at the [Exoscale Marketplace](https://www.exoscale.com/marketplace/listing/glasskube-gitea/).

63
versioned_docs/version-1.25/installation/on-kubernetes.md Normal file
View File

@@ -0,0 +1,63 @@
---
date: "2020-03-19T19:27:00+02:00"
slug: "install-on-kubernetes"
sidebar_position: 80
aliases:
- /en-us/install-on-kubernetes
---
# Install on Kubernetes
Gitea provides a Helm Chart to allow for installation on kubernetes.
A non-customized install can be done with:
```
helm repo add gitea-charts https://dl.gitea.com/charts/
helm install gitea gitea-charts/gitea
```
If you would like to customize your install, which includes kubernetes ingress, please refer to the complete [Gitea helm chart configuration details](https://gitea.com/gitea/helm-chart/)
## Health check endpoint
Gitea comes with a health check endpoint `/api/healthz`, you can configure it in kubernetes like this:
```yaml
livenessProbe:
httpGet:
path: /api/healthz
port: http
initialDelaySeconds: 200
timeoutSeconds: 5
periodSeconds: 10
successThreshold: 1
failureThreshold: 10
```
a successful health check response will respond with http code `200`, here's example:
```json
HTTP/1.1 200 OK
{
"status": "pass",
"description": "Gitea: Git with a cup of tea",
"checks": {
"cache:ping": [
{
"status": "pass",
"time": "2022-02-19T09:16:08Z"
}
],
"database:ping": [
{
"status": "pass",
"time": "2022-02-19T09:16:08Z"
}
]
}
}
```
for more information, please reference to kubernetes documentation [Define a liveness HTTP request](https://kubernetes.io/docs/tasks/configure-pod-container/configure-liveness-readiness-startup-probes/#define-a-liveness-http-request)

68
versioned_docs/version-1.25/installation/run-as-service-in-ubuntu.md Normal file
View File

@@ -0,0 +1,68 @@
---
date: "2017-07-21T12:00:00+02:00"
slug: "linux-service"
sidebar_position: 40
aliases:
- /en-us/linux-service
---
# Run as a Linux service
You can run Gitea as a Linux service, using either systemd or supervisor. The steps below tested on Ubuntu 16.04, but those should work on any Linux distributions (with little modification).
## Using systemd
Copy the sample [gitea.service](https://github.com/go-gitea/gitea/blob/main/contrib/systemd/gitea.service) to `/etc/systemd/system/gitea.service`, then edit the file with your favorite editor.
Uncomment any service that needs to be enabled on this host, such as MySQL.
Change the user, home directory, and other required startup values. Change the
PORT or remove the -p flag if default port is used.
Enable and start Gitea at boot:
```
sudo systemctl enable gitea
sudo systemctl start gitea
```
If you have systemd version 220 or later, you can enable and immediately start Gitea at once by:
```
sudo systemctl enable gitea --now
```
## Using supervisor
Install supervisor by running below command in terminal:
```
sudo apt install supervisor
```
Create a log dir for the supervisor logs:
```
# assuming Gitea is installed in /home/git/gitea/
mkdir /home/git/gitea/log/supervisor
```
Append the configuration from the sample
[supervisord config](https://github.com/go-gitea/gitea/blob/main/contrib/supervisor/gitea) to `/etc/supervisor/supervisord.conf`.
Using your favorite editor, change the user (`git`) and home
(`/home/git`) settings to match the deployment environment. Change the PORT
or remove the -p flag if default port is used.
Lastly enable and start supervisor at boot:
```
sudo systemctl enable supervisor
sudo systemctl start supervisor
```
If you have systemd version 220 or later, you can enable and immediately start supervisor by:
```
sudo systemctl enable supervisor --now
```

91
versioned_docs/version-1.25/installation/upgrade-from-gitea.md Normal file
View File

@@ -0,0 +1,91 @@
---
date: "2021-09-02T16:00:00+08:00"
slug: "upgrade-from-gitea"
sidebar_position: 100
aliases:
- /en-us/upgrade-from-gitea
---
# Upgrade from an old Gitea
Follow below steps to ensure a smooth upgrade to a new Gitea version.
## Check the Changelog for breaking changes
To make Gitea better, some breaking changes are unavoidable, especially for big milestone releases.
Before upgrading, please read the [Changelog on Gitea blog](https://blog.gitea.com/)
and check whether the breaking changes affect your Gitea instance.
## Verify there are no deprecated configuration options
New versions of Gitea often come with changed configuration syntax or options which are usually displayed for
at least one release cycle inside at the top of the Site Administration panel. If these warnings are not
resolved, Gitea may refuse to start in the following version.
## Backup for downgrade
Gitea keeps compatibility for patch versions whose first two fields are the same (`a.b.x` -> `a.b.y`),
these patch versions can be upgraded and downgraded with the same database structure.
Otherwise (`a.b.?` -> `a.c.?`), a newer Gitea version will upgrade the old database
to a new structure that may differ from the old version.
For example:
| From | To | Result |
| --- | --- | --- |
| 1.4.0 | 1.4.1 | ✅ |
| 1.4.1 | 1.4.0 | ⚠️ Not recommended, take your own risk! Although it may work if the database structure doesn't change, it's highly recommended to use a backup to downgrade. |
| 1.4.x | 1.5.y | ✅ Database gets upgraded. You can upgrade from 1.4.x to the latest 1.5.y directly. |
| 1.5.y | 1.4.x | ❌ Database already got upgraded and can not be used for an old Gitea, use a backup to downgrade. |
**Since you can not run an old Gitea with an upgraded database,
a backup should always be made before a database upgrade.**
If you use Gitea in production, it's always highly recommended to make a backup before upgrade,
even if the upgrade is between patch versions.
Backup steps:
* Stop Gitea instance
* Backup database
* Backup Gitea config
* Backup Gitea data files in `APP_DATA_PATH`
* Backup Gitea external storage (eg: S3/MinIO or other storages if used)
If you are using cloud services or filesystems with snapshot feature,
a snapshot for the Gitea data volume and related object storage is more convenient.
After all of steps have been prepared, download the new version, stop the application, perform a backup and
then start the new application. On each startup, Gitea verifies that the database is up to date and will automatically
perform any necessary migrations. Depending on the size of the database, this can take some additional time on the
first launch during which the application will be unavailable.
## Upgrade with Docker
* `docker pull` the latest Gitea release.
* Stop the running instance, backup data.
* Use `docker` or `docker-compose` to start the newer Gitea Docker container.
## Upgrade from package
* Stop the running instance, backup data.
* Use your package manager to upgrade Gitea to the latest version.
* Start the Gitea instance.
## Upgrade from binary
* Download the latest Gitea binary to a temporary directory.
* Stop the running instance, backup data.
* Replace the installed Gitea binary with the downloaded one.
* Start the Gitea instance.
A script automating these steps for a deployment on Linux can be found at [`contrib/upgrade.sh` in Gitea's source tree](https://github.com/go-gitea/gitea/blob/main/contrib/upgrade.sh).
## Take care about customized templates
Gitea's template structure and variables may change between releases, if you are using customized templates,
do pay attention if your templates are compatible with the Gitea you are using.
If the customized templates don't match Gitea version, you may experience:
`50x` server error, page components missing or malfunctioning, strange page layout, ...
Remove or update the incompatible templates and Gitea web will work again.

72
versioned_docs/version-1.25/installation/windows-service.md Normal file
View File

@@ -0,0 +1,72 @@
---
date: "2016-12-21T15:00:00-02:00"
slug: "windows-service"
sidebar_position: 50
aliases:
- /en-us/windows-service
---
# Register as a Windows service
## Prerequisites
The following changes are made in C:\gitea\custom\conf\app.ini:
```ini title="app.ini"
RUN_USER = COMPUTERNAME$
```
Sets Gitea to run as the local system user.
COMPUTERNAME is whatever the response is from `echo %COMPUTERNAME%` on the command line. If the response is `USER-PC` then `RUN_USER = USER-PC$`
### Use absolute paths
If you use SQLite3, change the `PATH` to include the full path:
```ini title="app.ini"
[database]
PATH = c:/gitea/data/gitea.db
```
## Register Gitea
To register Gitea as a Windows service, open a command prompt (cmd) as an Administrator,
then run the following command:
```sh
sc.exe create gitea start= auto binPath= "\"C:\gitea\gitea.exe\" web --config \"C:\gitea\custom\conf\app.ini\""
```
Do not forget to replace `C:\gitea` with the correct Gitea directory.
Open "Windows Services", search for the service named "gitea", right-click it and click on
"Run". If everything is OK, Gitea will be reachable on `http://localhost:3000` (or the port
that was configured).
### Service startup type
It was observed that on loaded systems during boot Gitea service may fail to start with timeout records in Windows Event Log.
In that case change startup type to `Automatic-Delayed`. This can be done during service creation, or by running config command
```sh
sc.exe config gitea start= delayed-auto
```
### Adding startup dependencies
To add a startup dependency to the Gitea Windows service (eg Mysql, Mariadb), as an Administrator, then run the following command:
```sh
sc.exe config gitea depend= mariadb
```
This will ensure that when the Windows machine restarts, the automatic starting of Gitea is postponed until the database is ready and thus mitigate failed startups.
## Unregister Gitea
To unregister Gitea as a Windows service, open a command prompt (cmd) as an Administrator and run:
```sh
sc.exe delete gitea
```

365
versioned_docs/version-1.25/installation/with-docker-rootless.md Normal file
View File

@@ -0,0 +1,365 @@
---
date: "2020-02-09T20:00:00+02:00"
slug: "install-with-docker-rootless"
sidebar_position: 60
aliases:
- /en-us/install-with-docker-rootless
---
# Installation with Docker (rootless)
Gitea provides automatically updated Docker images within its Docker Hub organization. It is
possible to always use the latest stable tag or to use another service that handles updating
Docker images.
The rootless image uses Gitea internal SSH to provide Git protocol and doesn't support OpenSSH.
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
the official [install instructions](https://docs.docker.com/compose/install/).
## Basics
The most simple setup just creates a volume and a network and starts the `docker.gitea.com/gitea:latest-rootless`
image as a service. Since there is no database available, one can be initialized using SQLite3.
Create a directory for `data` and `config`:
```sh
mkdir -p gitea/{data,config}
cd gitea
touch docker-compose.yml
```
Then paste the following content into a file named `docker-compose.yml`:
```yaml
version: "2"
services:
server:
image: docker.gitea.com/gitea:@dockerVersion@-rootless
restart: always
volumes:
- ./data:/var/lib/gitea
- ./config:/etc/gitea
- /etc/timezone:/etc/timezone:ro
- /etc/localtime:/etc/localtime:ro
ports:
- "3000:3000"
- "2222:2222"
```
Note that the volume should be owned by the user/group with the UID/GID specified in the config file. By default Gitea in docker will use uid:1000 gid:1000. If needed you can set ownership on those folders with the command:
```sh
sudo chown 1000:1000 config/ data/
```
> If you don't give the volume correct permissions, the container may not start.
For a stable release you could use `:latest-rootless`, `:1-rootless` or specify a certain release like `:@dockerVersion@-rootless`, but if you'd like to use the latest development version then `:nightly-rootless` would be an appropriate tag. If you'd like to run the latest commit from a release branch you can use the `:1.x-nightly-rootless` tag, where x is the minor version of Gitea. (e.g. `:1.16-nightly-rootless`)
## Custom port
To bind the integrated ssh 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
the container like they are.
```diff
version: "2"
services:
server:
image: docker.gitea.com/gitea:@dockerVersion@-rootless
restart: always
volumes:
- ./data:/var/lib/gitea
- ./config:/etc/gitea
- /etc/timezone:/etc/timezone:ro
- /etc/localtime:/etc/localtime:ro
ports:
- - "3000:3000"
- - "2222:2222"
+ - "80:3000"
+ - "22:2222"
```
## MySQL database
To start Gitea in combination with a MySQL database, apply these changes to the
`docker-compose.yml` file created above.
```diff
version: "2"
services:
server:
image: docker.gitea.com/gitea:@dockerVersion@-rootless
+ environment:
+ - GITEA__database__DB_TYPE=mysql
+ - GITEA__database__HOST=db:3306
+ - GITEA__database__NAME=gitea
+ - GITEA__database__USER=gitea
+ - GITEA__database__PASSWD=gitea
restart: always
volumes:
- ./data:/var/lib/gitea
- ./config:/etc/gitea
- /etc/timezone:/etc/timezone:ro
- /etc/localtime:/etc/localtime:ro
ports:
- "3000:3000"
- "2222:2222"
+ depends_on:
+ - db
+
+ db:
+ image: docker.io/library/mysql:8
+ restart: always
+ environment:
+ - MYSQL_ROOT_PASSWORD=gitea
+ - MYSQL_USER=gitea
+ - MYSQL_PASSWORD=gitea
+ - MYSQL_DATABASE=gitea
+ volumes:
+ - ./mysql:/var/lib/mysql
```
## PostgreSQL database
To start Gitea in combination with a PostgreSQL database, apply these changes to
the `docker-compose.yml` file created above.
```diff
version: "2"
services:
server:
image: docker.gitea.com/gitea:@dockerVersion@-rootless
environment:
+ - GITEA__database__DB_TYPE=postgres
+ - GITEA__database__HOST=db:5432
+ - GITEA__database__NAME=gitea
+ - GITEA__database__USER=gitea
+ - GITEA__database__PASSWD=gitea
restart: always
volumes:
- ./data:/var/lib/gitea
- ./config:/etc/gitea
- /etc/timezone:/etc/timezone:ro
- /etc/localtime:/etc/localtime:ro
ports:
- "3000:3000"
- "2222:2222"
+ depends_on:
+ - db
+
+ db:
+ image: docker.io/library/postgres:14
+ restart: always
+ environment:
+ - POSTGRES_USER=gitea
+ - POSTGRES_PASSWORD=gitea
+ - POSTGRES_DB=gitea
+ volumes:
+ - ./postgres:/var/lib/postgresql/data
```
## Named volumes
To use named volumes instead of host volumes, define and use the named volume
within the `docker-compose.yml` configuration. This change will automatically
create the required volume. You don't need to worry about permissions with
named volumes; Docker will deal with that automatically.
```diff
version: "2"
+volumes:
+ gitea-data:
+ driver: local
+ gitea-config:
+ driver: local
+
services:
server:
image: docker.gitea.com/gitea:@dockerVersion@-rootless
restart: always
volumes:
- - ./data:/var/lib/gitea
+ - gitea-data:/var/lib/gitea
- - ./config:/etc/gitea
+ - gitea-config:/etc/gitea
- /etc/timezone:/etc/timezone:ro
- /etc/localtime:/etc/localtime:ro
ports:
- "3000:3000"
- "2222:2222"
```
MySQL or PostgreSQL containers will need to be created separately.
## Custom user
You can choose to use a custom user (following --user flag definition https://docs.docker.com/engine/reference/run/#user).
As an example to clone the host user `git` definition use the command `id -u git` and add it to `docker-compose.yml` file:
Please make sure that the mounted folders are writable by the user.
```diff
version: "2"
services:
server:
image: docker.gitea.com/gitea:@dockerVersion@-rootless
restart: always
+ user: 1001
volumes:
- ./data:/var/lib/gitea
- ./config:/etc/gitea
- /etc/timezone:/etc/timezone:ro
- /etc/localtime:/etc/localtime:ro
ports:
- "3000:3000"
- "2222:2222"
```
## Startup
:::note
From July 2023 Compose V1 stopped receiving updates. It's also no longer available in new releases of Docker Desktop.
Compose V2 is included with all currently supported versions of Docker Desktop. Please use V2 to do below operations.
:::
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
started properly. Logs can be viewed with `docker-compose logs`.
To shut down the setup, execute `docker-compose down`. This will stop
and kill the containers. The volumes will still exist.
:::note
If using a non-3000 port on http, change app.ini to match
`LOCAL_ROOT_URL = http://localhost:3000/`.
:::
## Install
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.
## Customization
Customization files described [here](../administration/customizing-gitea.md) should
be placed in `/var/lib/gitea/custom` 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
`/var/lib/docker/volumes/gitea_gitea/_/var_lib_gitea`. The configuration file will be saved at
`/etc/gitea/app.ini` after the installation.
## Upgrading
:::warning
:exclamation::exclamation: **Make sure you have volumed data to somewhere outside Docker container** :exclamation::exclamation:
:::
To upgrade your installation to the latest release:
```bash
# Edit `docker-compose.yml` to update the version, if you have one specified
# Pull new images
docker-compose pull
# Start a new container, automatically removes old one
docker-compose up -d
```
## Upgrading from standard image
- Backup your setup
- Change volume mountpoint from /data to /var/lib/gitea
- If you used a custom app.ini move it to a new volume mounted to /etc/gitea
- Rename folder (inside volume) gitea to custom
- Edit app.ini if needed
- Set START_SSH_SERVER = true
- Use image docker.gitea.com/gitea:@dockerVersion@-rootless
## Managing Deployments With Environment Variables
In addition to the environment variables above, any settings in `app.ini` can be set
or overridden with an environment variable of the form: `GITEA__SECTION_NAME__KEY_NAME`.
These settings are applied each time the docker container starts, and won't be passed into Gitea's sub-processes.
Full information [here](https://github.com/go-gitea/gitea/tree/main/contrib/environment-to-ini).
These environment variables can be passed to the docker container in `docker-compose.yml`.
The following example will enable a smtp mail server if the required env variables
`GITEA__mailer__FROM`, `GITEA__mailer__HOST`, `GITEA__mailer__PASSWD` are set on the host
or in a `.env` file in the same directory as `docker-compose.yml`.
The settings can be also set or overridden with the content of a file by defining an environment variable of the form:
`GITEA__section_name__KEY_NAME__FILE` that points to a file.
```bash
...
services:
server:
environment:
- GITEA__mailer__ENABLED=true
- GITEA__mailer__FROM=${GITEA__mailer__FROM:?GITEA__mailer__FROM not set}
- GITEA__mailer__PROTOCOL=smtp
- GITEA__mailer__HOST=${GITEA__mailer__HOST:?GITEA__mailer__HOST not set}
- GITEA__mailer__IS_TLS_ENABLED=true
- GITEA__mailer__USER=${GITEA__mailer__USER:-apikey}
- GITEA__mailer__PASSWD="""${GITEA__mailer__PASSWD:?GITEA__mailer__PASSWD not set}"""
```
To set required TOKEN and SECRET values, consider using Gitea's built-in [generate utility functions](../administration/command-line.md#generate).
# 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 commands from the host to the container. This setup is explained in the following.
This guide assumes that you have created a user on the host called `git` with permission to run `docker exec`, and that the Gitea container is called `gitea`. You will need to modify that user's shell to forward the commands to the `sh` executable inside the container, using `docker exec`.
First, create the file `/usr/local/bin/gitea-shell` on the host, with the following contents:
```bash
#!/bin/sh
/usr/bin/docker exec -i --env SSH_ORIGINAL_COMMAND="$SSH_ORIGINAL_COMMAND" gitea sh "$@"
```
Note that `gitea` in the docker command above is the name of the container. If you named yours differently, don't forget to change that.
You should also make sure that you’ve set the permissions of the shell wrapper correctly:
```bash
sudo chmod +x /usr/local/bin/gitea-shell
```
Once the wrapper is in place, you can make it the shell for the `git` user:
```bash
sudo usermod -s /usr/local/bin/gitea-shell git
```
Now that all the SSH commands are forwarded to the container, you need to set up the SSH authentication on the host. This is done by leveraging the [SSH AuthorizedKeysCommand](../administration/command-line.md#keys) to match the keys against those accepted by Gitea. Add the following block to `/etc/ssh/sshd_config`, on the host:
```bash
Match User git
AuthorizedKeysCommandUser git
AuthorizedKeysCommand /usr/bin/docker exec -i gitea /usr/local/bin/gitea keys -c /etc/gitea/app.ini -e git -u %u -t %t -k %k
```
(From 1.16.0 you will not need to set the `-c /etc/gitea/app.ini` option.)
All that is left to do is restart the SSH server:
```bash
sudo systemctl restart sshd
```
**Notes**
This isn't actually using the docker SSH - it is simply using the commands around it.
You could theoretically not run the internal SSH server.

650
versioned_docs/version-1.25/installation/with-docker.md Normal file
View File

@@ -0,0 +1,650 @@
---
date: "2020-03-19T19:27:00+02:00"
slug: "install-with-docker"
sidebar_position: 70
aliases:
- /en-us/install-with-docker
---
# Installation with Docker
Gitea provides automatically updated Docker images within its Docker Hub organization. It is
possible to always use the latest stable tag or to use another service that handles updating
Docker images.
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
the official [install instructions](https://docs.docker.com/compose/install/).
## Basics
The most simple setup just creates a volume and a network and starts the `docker.gitea.com/gitea:latest`
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`.
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.
For a stable release you can use `:latest`, `:1` or specify a certain release like `:@dockerVersion@`, but if you'd like to use the latest development version of Gitea then you could use the `:nightly` tag. If you'd like to run the latest commit from a release branch you can use the `:1.x-nightly` tag, where x is the minor version of Gitea. (e.g. `:1.16-nightly`)
```yaml
version: "3"
networks:
gitea:
external: false
services:
server:
image: docker.gitea.com/gitea:@dockerVersion@
container_name: gitea
environment:
- USER_UID=1000
- USER_GID=1000
restart: always
networks:
- gitea
volumes:
- ./gitea:/data
- /etc/timezone:/etc/timezone:ro
- /etc/localtime:/etc/localtime:ro
ports:
- "3000:3000"
- "222:22"
```
## 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
the container like they are.
```diff
version: "3"
networks:
gitea:
external: false
services:
server:
image: docker.gitea.com/gitea:@dockerVersion@
container_name: gitea
environment:
- USER_UID=1000
- USER_GID=1000
restart: always
networks:
- gitea
volumes:
- ./gitea:/data
- /etc/timezone:/etc/timezone:ro
- /etc/localtime:/etc/localtime:ro
ports:
- - "3000:3000"
- - "222:22"
+ - "8080:3000"
+ - "2221:22"
```
## Databases
### MySQL database
To start Gitea in combination with a MySQL database, apply these changes to the
`docker-compose.yml` file created above.
```diff
version: "3"
networks:
gitea:
external: false
services:
server:
image: docker.gitea.com/gitea:@dockerVersion@
container_name: gitea
environment:
- USER_UID=1000
- USER_GID=1000
+ - GITEA__database__DB_TYPE=mysql
+ - GITEA__database__HOST=db:3306
+ - GITEA__database__NAME=gitea
+ - GITEA__database__USER=gitea
+ - GITEA__database__PASSWD=gitea
restart: always
networks:
- gitea
volumes:
- ./gitea:/data
- /etc/timezone:/etc/timezone:ro
- /etc/localtime:/etc/localtime:ro
ports:
- "3000:3000"
- "222:22"
+ depends_on:
+ - db
+
+ db:
+ image: docker.io/library/mysql:8
+ restart: always
+ environment:
+ - MYSQL_ROOT_PASSWORD=gitea
+ - MYSQL_USER=gitea
+ - MYSQL_PASSWORD=gitea
+ - MYSQL_DATABASE=gitea
+ networks:
+ - gitea
+ volumes:
+ - ./mysql:/var/lib/mysql
```
### PostgreSQL database
To start Gitea in combination with a PostgreSQL database, apply these changes to
the `docker-compose.yml` file created above.
```diff
version: "3"
networks:
gitea:
external: false
services:
server:
image: docker.gitea.com/gitea:@dockerVersion@
container_name: gitea
environment:
- USER_UID=1000
- USER_GID=1000
+ - GITEA__database__DB_TYPE=postgres
+ - GITEA__database__HOST=db:5432
+ - GITEA__database__NAME=gitea
+ - GITEA__database__USER=gitea
+ - GITEA__database__PASSWD=gitea
restart: always
networks:
- gitea
volumes:
- ./gitea:/data
- /etc/timezone:/etc/timezone:ro
- /etc/localtime:/etc/localtime:ro
ports:
- "3000:3000"
- "222:22"
+ depends_on:
+ - db
+
+ db:
+ image: docker.io/library/postgres:14
+ restart: always
+ environment:
+ - POSTGRES_USER=gitea
+ - POSTGRES_PASSWORD=gitea
+ - POSTGRES_DB=gitea
+ networks:
+ - gitea
+ volumes:
+ - ./postgres:/var/lib/postgresql/data
```
## Named volumes
To use named volumes instead of host volumes, define and use the named volume
within the `docker-compose.yml` configuration. This change will automatically
create the required volume. You don't need to worry about permissions with
named volumes; Docker will deal with that automatically.
```diff
version: "3"
networks:
gitea:
external: false
+volumes:
+ gitea:
+ driver: local
+
services:
server:
image: docker.gitea.com/gitea:@dockerVersion@
container_name: gitea
restart: always
networks:
- gitea
volumes:
- - ./gitea:/data
+ - gitea:/data
- /etc/timezone:/etc/timezone:ro
- /etc/localtime:/etc/localtime:ro
ports:
- "3000:3000"
- "222:22"
```
MySQL or PostgreSQL containers will need to be created separately.
## Startup
:::note
From July 2023 Compose V1 stopped receiving updates. It's also no longer available in new releases of Docker Desktop.
Compose V2 is included with all currently supported versions of Docker Desktop. Please use V2 to do below operations.
:::
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
started properly. Logs can be viewed with `docker-compose logs`.
To shut down the setup, execute `docker-compose down`. This will stop
and kill the containers. The volumes will still exist.
:::note
If using a non-3000 port on http, change app.ini to match
`LOCAL_ROOT_URL = http://localhost:3000/`.
:::
## 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.
## Configure the user inside Gitea using environment variables
- `USER`: **git**: The username of the user that runs Gitea within the container.
- `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](../administration/customizing-gitea.md) should
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
`/var/lib/docker/volumes/gitea_gitea/_data`. The configuration file will be saved at
`/data/gitea/conf/app.ini` after the installation.
Example: Analogous to the non-docker-installation customization linked above, you can create a `/public` folder within `/data/gitea` and place your custom `robots.txt` there which will then be served normally.
## Upgrading
:::warning
Make sure you have volumed data to somewhere outside Docker container
:::
To upgrade your installation to the latest release:
```bash
# Edit `docker-compose.yml` to update the version, if you have one specified
# Pull new images
docker-compose pull
# Start a new container, automatically removes old one
docker-compose up -d
```
## Managing Deployments With Environment Variables
In addition to the environment variables above, any settings in `app.ini` can be set
or overridden with an environment variable of the form: `GITEA__SECTION_NAME__KEY_NAME`.
These settings are applied each time the docker container starts, and won't be passed into Gitea's sub-processes.
Full information [here](https://github.com/go-gitea/gitea/tree/master/contrib/environment-to-ini).
These environment variables can be passed to the docker container in `docker-compose.yml`.
The following example will enable an smtp mail server if the required env variables
`GITEA__mailer__FROM`, `GITEA__mailer__HOST`, `GITEA__mailer__PASSWD` are set on the host
or in a `.env` file in the same directory as `docker-compose.yml`.
The settings can be also set or overridden with the content of a file by defining an environment variable of the form:
`GITEA__section_name__KEY_NAME__FILE` that points to a file.
```yaml
...
services:
server:
environment:
- GITEA__mailer__ENABLED=true
- GITEA__mailer__FROM=${GITEA__mailer__FROM:?GITEA__mailer__FROM not set}
- GITEA__mailer__PROTOCOL=smtps
- GITEA__mailer__SMTP_ADDR=${GITEA__mailer__SMTP_ADDR:?GITEA__mailer__SMTP_ADDR not set}
- GITEA__mailer__SMTP_PORT=${GITEA__mailer__SMTP_PORT:?GITEA__mailer__SMTP_PORT not set}
- GITEA__mailer__USER=${GITEA__mailer__USER:-apikey}
- GITEA__mailer__PASSWD="""${GITEA__mailer__PASSWD:?GITEA__mailer__PASSWD not set}"""
```
Gitea will generate new secrets/tokens for every new installation automatically and write them into the app.ini. If you want to set the secrets/tokens manually, you can use the following docker commands to use of Gitea's built-in [generate utility functions](../administration/command-line.md#generate). Do not lose/change your SECRET_KEY after the installation, otherwise the encrypted data can not be decrypted anymore.
The following commands will output a new `SECRET_KEY` and `INTERNAL_TOKEN` to `stdout`, which you can then place in your environment variables.
```bash
docker run -it --rm docker.gitea.com/gitea:1 gitea generate secret SECRET_KEY
docker run -it --rm docker.gitea.com/gitea:1 gitea generate secret INTERNAL_TOKEN
```
```yaml
...
services:
server:
environment:
- GITEA__security__SECRET_KEY=[value returned by generate secret SECRET_KEY]
- GITEA__security__INTERNAL_TOKEN=[value returned by generate secret INTERNAL_TOKEN]
```
## 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 for Gitea users to ssh to a Gitea user on the host which will then relay those connections to the docker. Alternatively, if the host machine has more than one IP address, the host can listen on one and Gitea on another.
### Understanding SSH access to Gitea (without passthrough)
To understand what needs to happen, you first need to understand what happens without passthrough. So we will try to explain this:
1. The client adds their SSH public key to Gitea using the webpage.
2. Gitea will add an entry for this key to the `.ssh/authorized_keys` file of its running user, `git`.
3. This entry has the public key, but also has a `command=` option. It is this command that Gitea uses to match this key to the client user and manages authentication.
4. The client then makes an SSH request to the SSH server using the `git` user, e.g. `git clone git@domain:user/repo.git`.
5. The client will attempt to authenticate with the server, passing one or more public keys one at a time to the server.
6. For each key the client provides, the SSH server will first check its configuration for an `AuthorizedKeysCommand` to see if the public key matches, and then the `git` user's `authorized_keys` file.
7. The first entry that matches will be selected, and assuming this is a Gitea entry, the `command=` will now be executed.
8. The SSH server creates a user session for the `git` user, and using the shell for the `git` user runs the `command=`
9. This runs `gitea serv` which takes over control of the rest of the SSH session and manages gitea authentication & authorization of the git commands.
Now, for the SSH passthrough to work, we need the host SSH to match the public keys and then run the `gitea serv` on the docker. There are multiple ways of doing this. However, all of these require some information about the docker being passed to the host.
### SSHing Shim (with authorized_keys)
In this option, the idea is that the host simply uses the `authorized_keys` that gitea creates but at step 9 the `gitea` command that the host runs is a shim that actually runs ssh to go into the docker and then run the real docker `gitea` itself.
- To make the forwarding work, the SSH port of the container (22) needs to be mapped to the host port 2222 in `docker-compose.yml` . Since this port does not need to be exposed to the outside world, it can be mapped to the `localhost` of the host machine:
```yaml
ports:
# [...]
- "127.0.0.1:2222:22"
```
- Next on the host create the `git` user which shares the same `UID`/ `GID` as the container values `USER_UID`/ `USER_GID`. These values can be set as environment variables in the `docker-compose.yml`:
```yaml
environment:
- USER_UID=1000
- USER_GID=1000
```
- Mount `/home/git/.ssh` of the host into the container. This ensures that the `authorized_keys` file is shared between the host `git` user and the container `git` user otherwise the SSH authentication cannot work inside the container.
```yaml
volumes:
- /home/git/.ssh/:/data/git/.ssh
```
- Now a SSH key pair needs to be created on the host. This key pair will be used to authenticate the `git` user on the host to the container. As an administrative user on the host run: (by administrative user we mean a user that can sudo to root)
```bash
sudo -u git ssh-keygen -t rsa -b 4096 -C "Gitea Host Key"
```
- Please note depending on the local version of ssh you may want to consider using `-t ecdsa` here.
- `/home/git/.ssh/authorized_keys` on the host now needs to be modified. It needs to act in the same way as `authorized_keys` within the Gitea container. Therefore add the public key of the key you created above ("Gitea Host Key") to `/home/git/.ssh/authorized_keys`. As an administrative user on the host run:
```bash
sudo -u git cat /home/git/.ssh/id_rsa.pub | sudo -u git tee -a /home/git/.ssh/authorized_keys
sudo -u git chmod 600 /home/git/.ssh/authorized_keys
```
Important: The pubkey from the `git` user needs to be added "as is" while all other pubkeys added via the Gitea web interface will be prefixed with `command="/usr [...]`.
`/home/git/.ssh/authorized_keys` should then look somewhat like
```bash
# SSH pubkey from git user
ssh-rsa <Gitea Host Key>
# other keys from users
command="/usr/local/bin/gitea --config=/data/gitea/conf/app.ini serv key-1",no-port-forwarding,no-X11-forwarding,no-agent-forwarding,no-pty <user pubkey>
```
- The next step is to create the fake host `gitea` command that will forward commands from the host to the container. The name of this file depends on your version of Gitea:
- For Gitea v1.16.0+. As an administrative user on the host run:
```bash
cat <<"EOF" | sudo tee /usr/local/bin/gitea
#!/bin/sh
ssh -p 2222 -o StrictHostKeyChecking=no git@127.0.0.1 "SSH_ORIGINAL_COMMAND=\"$SSH_ORIGINAL_COMMAND\" $0 $@"
EOF
sudo chmod +x /usr/local/bin/gitea
```
Here is a detailed explanation what is happening when a SSH request is made:
1. The client adds their SSH public key to Gitea using the webpage.
2. Gitea in the container will add an entry for this key to the `.ssh/authorized_keys` file of its running user, `git`.
- However, because `/home/git/.ssh/` on the host is mounted as `/data/git/.ssh` this means that the key has been added to the host `git` user's `authorized_keys` file too.
3. This entry has the public key, but also has a `command=` option.
- This command matches the location of the Gitea binary on the container, but also the location of the shim on the host.
4. The client then makes an SSH request to the host SSH server using the `git` user, e.g. `git clone git@domain:user/repo.git`.
5. The client will attempt to authenticate with the server, passing one or more public keys in turn to the host.
6. For each key the client provides, the host SSH server will first check its configuration for an `AuthorizedKeysCommand` to see if the public key matches, and then the host `git` user's `authorized_keys` file.
- Because `/home/git/.ssh/` on the host is mounted as `/data/git/.ssh` this means that the key they added to the Gitea web will be found
7. The first entry that matches will be selected, and assuming this is a Gitea entry, the `command=` will now be executed.
8. The host SSH server creates a user session for the `git` user, and using the shell for the host `git` user runs the `command=`
9. This means that the host runs the host `/usr/local/bin/gitea` shim that opens an SSH from the host to container passing the rest of the command arguments directly to `/usr/local/bin/gitea` on the container.
10. Meaning that the container `gitea serv` is run, taking over control of the rest of the SSH session and managing gitea authentication & authorization of the git commands.
**Notes**
SSH container passthrough using `authorized_keys` will work only if
- `opensshd` is used in the container
- if `AuthorizedKeysCommand` is _not used_ in combination with `SSH_CREATE_AUTHORIZED_KEYS_FILE=false` to disable authorized files key generation
- `LOCAL_ROOT_URL` is not changed (depending on the changes)
If you try to run `gitea` on the host, you will attempt to ssh to the container and thence run the `gitea` command there.
Never add the `Gitea Host Key` as a SSH key to a user on the Gitea interface.
### SSHing Shell (with authorized_keys)
In this option, the idea is that the host simply uses the `authorized_keys` that gitea creates but at step 8 above we change the shell that the host runs to ssh directly into the docker and then run the shell there. This means that the `gitea` that is then run is the real docker `gitea`.
- In this case we setup as per SSHing Shim except instead of creating `/usr/local/bin/gitea`
we create a new shell for the git user. As an administrative user on the host run:
```bash
cat <<"EOF" | sudo tee /home/git/ssh-shell
#!/bin/sh
shift
ssh -p 2222 -o StrictHostKeyChecking=no git@127.0.0.1 "SSH_ORIGINAL_COMMAND=\"$SSH_ORIGINAL_COMMAND\" $@"
EOF
sudo chmod +x /home/git/ssh-shell
sudo usermod -s /home/git/ssh-shell git
```
Be careful here - if you try to login as the git user in future you will ssh directly to the docker.
Here is a detailed explanation what is happening when a SSH request is made:
1. The client adds their SSH public key to Gitea using the webpage.
2. Gitea in the container will add an entry for this key to the `.ssh/authorized_keys` file of its running user, `git`.
- However, because `/home/git/.ssh/` on the host is mounted as `/data/git/.ssh` this means that the key has been added to the host `git` user's `authorized_keys` file too.
3. This entry has the public key, but also has a `command=` option.
- This command matches the location of the Gitea binary on the container.
4. The client then makes an SSH request to the host SSH server using the `git` user, e.g. `git clone git@domain:user/repo.git`.
5. The client will attempt to authenticate with the server, passing one or more public keys in turn to the host.
6. For each key the client provides, the host SSH server will first check its configuration for an `AuthorizedKeysCommand` to see if the public key matches, and then the host `git` user's `authorized_keys` file.
- Because `/home/git/.ssh/` on the host is mounted as `/data/git/.ssh` this means that the key they added to the Gitea web will be found
7. The first entry that matches will be selected, and assuming this is a Gitea entry, the `command=` will now be executed.
8. The host SSH server creates a user session for the `git` user, and using the shell for the host `git` user runs the `command=`
9. The shell of the host `git` user is now our `ssh-shell` which opens an SSH connection from the host to container, (which opens a shell on the container for the container `git`).
10. The container shell now runs the `command=` option meaning that the container `gitea serv` is run, taking over control of the rest of the SSH session and managing gitea authentication & authorization of the git commands.
**Notes**
SSH container passthrough using `authorized_keys` will work only if
- `opensshd` is used in the container
- if `AuthorizedKeysCommand` is _not used_ in combination with `SSH_CREATE_AUTHORIZED_KEYS_FILE=false` to disable authorized files key generation
- `LOCAL_ROOT_URL` is not changed (depending on the changes)
If you try to login as the `git` user on the host in future you will ssh directly to the docker.
Never add the `Gitea Host Key` as a SSH key to a user on the Gitea interface.
### Docker Shell (with authorized_keys)
Similar to the above ssh shell technique we can use a shell which simply uses `docker exec`. As an administrative user on the host run:
```bash
cat <<"EOF" | sudo tee /home/git/docker-shell
#!/bin/sh
/usr/bin/docker exec -i -u git --env SSH_ORIGINAL_COMMAND="$SSH_ORIGINAL_COMMAND" gitea sh "$@"
EOF
sudo chmod +x /home/git/docker-shell
sudo usermod -s /home/git/docker-shell git
```
Here is a detailed explanation what is happening when a SSH request is made:
1. The client adds their SSH public key to Gitea using the webpage.
2. Gitea in the container will add an entry for this key to the `.ssh/authorized_keys` file of its running user, `git`.
- However, because `/home/git/.ssh/` on the host is mounted as `/data/git/.ssh` this means that the key has been added to the host `git` user's `authorized_keys` file too.
3. This entry has the public key, but also has a `command=` option.
- This command matches the location of the Gitea binary on the container.
4. The client then makes an SSH request to the host SSH server using the `git` user, e.g. `git clone git@domain:user/repo.git`.
5. The client will attempt to authenticate with the server, passing one or more public keys in turn to the host.
6. For each key the client provides, the host SSH server will first check its configuration for an `AuthorizedKeysCommand` to see if the public key matches, and then the host `git` user's `authorized_keys` file.
- Because `/home/git/.ssh/` on the host is mounted as `/data/git/.ssh` this means that the key they added to the Gitea web will be found
7. The first entry that matches will be selected, and assuming this is a Gitea entry, the `command=` will now be executed.
8. The host SSH server creates a user session for the `git` user, and using the shell for the host `git` user runs the `command=`
9. The shell of the host `git` user is now our `docker-shell` which uses `docker exec` to open a shell for the `git` user on the container.
10. The container shell now runs the `command=` option meaning that the container `gitea serv` is run, taking over control of the rest of the SSH session and managing gitea authentication & authorization of the git commands.
Note that `gitea` in the docker command above is the name of the container. If you named yours differently, don't forget to change that. The host `git` user also has to have
permission to run `docker exec`.
**Notes**
Docker shell passthrough using `authorized_keys` will work only if
- `opensshd` is used in the container
- if `AuthorizedKeysCommand` is _not used_ in combination with `SSH_CREATE_AUTHORIZED_KEYS_FILE=false` to disable authorized files key generation
- `LOCAL_ROOT_URL` is not changed (depending on the changes)
If you try to login as the `git` user on the host in future you will `docker exec` directly to the docker.
A Docker execing shim could be created similarly to above.
### Docker Shell with AuthorizedKeysCommand
The AuthorizedKeysCommand route provides another option that does not require many changes to the compose file or the `authorized_keys` - but does require changes to the host `/etc/sshd_config`.
In this option, the idea is that the host SSH uses an `AuthorizedKeysCommand` instead of relying on sharing the `authorized_keys` file that gitea creates. We continue to use a special shell at step 8 above to exec into the docker and then run the shell there. This means that the `gitea` that is then run is the real docker `gitea`.
- On the host create a `git` user with permission to run `docker exec`.
- We will again assume that the Gitea container is called `gitea`.
- Modify the `git` user's shell to forward commands to the `sh` executable inside the container using `docker exec`. As an administrative user on the host run:
```bash
cat <<"EOF" | sudo tee /home/git/docker-shell
#!/bin/sh
/usr/bin/docker exec -i -u git --env SSH_ORIGINAL_COMMAND="$SSH_ORIGINAL_COMMAND" gitea sh "$@"
EOF
sudo chmod +x /home/git/docker-shell
sudo usermod -s /home/git/docker-shell git
```
Now all attempts to login as the `git` user on the host will be forwarded to the docker - including the `SSH_ORIGINAL_COMMAND`. We now need to set-up SSH authentication on the host.
We will do this by leveraging the [SSH AuthorizedKeysCommand](../administration/command-line.md#keys) to match the keys against those accepted by Gitea.
Add the following block to `/etc/ssh/sshd_config`, on the host:
```bash
Match User git
AuthorizedKeysCommandUser git
AuthorizedKeysCommand /usr/bin/docker exec -i -u git gitea /usr/local/bin/gitea keys -c /data/gitea/conf/app.ini -e git -u %u -t %t -k %k
```
(From 1.16.0 you will not need to set the `-c /data/gitea/conf/app.ini` option.)
Finally restart the SSH server. As an administrative user on the host run:
```bash
sudo systemctl restart sshd
```
Here is a detailed explanation what is happening when a SSH request is made:
1. The client adds their SSH public key to Gitea using the webpage.
2. Gitea in the container will add an entry for this key to its database.
3. The client then makes an SSH request to the host SSH server using the `git` user, e.g. `git clone git@domain:user/repo.git`.
4. The client will attempt to authenticate with the server, passing one or more public keys in turn to the host.
5. For each key the client provides, the host SSH server will checks its configuration for an `AuthorizedKeysCommand`.
6. The host runs the above `AuthorizedKeysCommand`, which execs in to the docker and then runs the `gitea keys` command.
7. Gitea on the docker will look in it's database to see if the public key matches and will return an entry like that of an `authorized_keys` command.
8. This entry has the public key, but also has a `command=` option which matches the location of the Gitea binary on the container.
9. The host SSH server creates a user session for the `git` user, and using the shell for the host `git` user runs the `command=`.
10. The shell of the host `git` user is now our `docker-shell` which uses `docker exec` to open a shell for the `git` user on the container.
11. The container shell now runs the `command=` option meaning that the container `gitea serv` is run, taking over control of the rest of the SSH session and managing gitea authentication & authorization of the git commands.
**Notes**
Docker shell passthrough using `AuthorizedKeysCommand` will work only if
- The host `git` user is allowed to run the `docker exec` command.
If you try to login as the `git` user on the host in future you will `docker exec` directly to the docker.
A Docker execing shim could be created similarly to above.
### SSH Shell with AuthorizedKeysCommand
Create a key for the host `git` user as above, add it to the docker `/data/git/.ssh/authorized_keys` then finally create and set the `ssh-shell` as above.
Add the following block to `/etc/ssh/sshd_config`, on the host:
```bash
Match User git
AuthorizedKeysCommandUser git
AuthorizedKeysCommand /usr/bin/ssh -p 2222 -o StrictHostKeyChecking=no git@127.0.0.1 /usr/local/bin/gitea keys -c /data/gitea/conf/app.ini -e git -u %u -t %t -k %k
```
(From 1.16.0 you will not need to set the `-c /data/gitea/conf/app.ini` option.)
Finally restart the SSH server. As an administrative user on the host run:
```bash
sudo systemctl restart sshd
```
Here is a detailed explanation what is happening when a SSH request is made:
1. The client adds their SSH public key to Gitea using the webpage.
2. Gitea in the container will add an entry for this key to its database.
3. The client then makes an SSH request to the host SSH server using the `git` user, e.g. `git clone git@domain:user/repo.git`.
4. The client will attempt to authenticate with the server, passing one or more public keys in turn to the host.
5. For each key the client provides, the host SSH server will checks its configuration for an `AuthorizedKeysCommand`.
6. The host runs the above `AuthorizedKeysCommand`, which will SSH in to the docker and then run the `gitea keys` command.
7. Gitea on the docker will look in it's database to see if the public key matches and will return an entry like that of an `authorized_keys` command.
8. This entry has the public key, but also has a `command=` option which matches the location of the Gitea binary on the container.
9. The host SSH server creates a user session for the `git` user, and using the shell for the host `git` user runs the `command=`.
10. The shell of the host `git` user is now our `git-shell` which uses SSH to open a shell for the `git` user on the container.
11. The container shell now runs the `command=` option meaning that the container `gitea serv` is run, taking over control of the rest of the SSH session and managing gitea authentication & authorization of the git commands.
**Notes**
SSH container passthrough using `AuthorizedKeysCommand` will work only if
- `opensshd` is running on the container
If you try to login as the `git` user on the host in future you will `ssh` directly to the docker.
Never add the `Gitea Host Key` as a SSH key to a user on the Gitea interface.
SSHing shims could be created similarly to above.
### SSH with multiple IP addresses
This assumes that the host machine has more than one reachable IP address: `192.168.1.1` (host) `192.168.1.2` (gitea)
On the host machine, configure SSHD in `/etc/ssh/sshd_config` to listen on one IP address `ListenAddress 192.168.1.1`. In the compose file the SSH port forwarding then needs to be changed to `"192.168.1.2:22:22"`. The port forwarding needs to be adjusted similarily for all other forwarded ports to avoid problems with DNS.