foster/forgejo-docs
0
0
Fork 0
mirror of https://codeberg.org/forgejo/docs.git synced 2024-11-21 17:36:59 -05:00
Code Issues Activity

database-preparation.md: adapt to Forgejo

Browse source
This commit is contained in:
Loïc Dachary 2023-03-08 14:39:56 +01:00
parent 5418b22c05
commit 3df262d742
2 changed files with 48 additions and 61 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

108
v1.19/admin/database-preparation.md
View file

@ -1,29 +1,15 @@
--- ---
date: "2020-01-16" layout: '~/layouts/Markdown.astro'
title: "Database Preparation" title: 'Database Preparation'
slug: "database-prep" license: 'Apache-2.0'
weight: 10 origin_url: 'https://github.com/go-gitea/gitea/blob/699f20234b9f7cdbbeeee3be004470c598fa1147/docs/content/doc/installation/database-preparation.en-us.md'
toc: false
draft: false
menu:
sidebar:
parent: "installation"
name: "Database preparation"
weight: 20
identifier: "database-prep"
--- ---
# Database Preparation You need a database to use Forgejo. Forgejo supports PostgreSQL (>=10), MySQL (>=5.7), SQLite, and MSSQL (>=2008R2 SP3). This page will guide into preparing database. Only PostgreSQL and MySQL will be covered here since those database engines are widely-used in production.
You need a database to use Gitea. Gitea supports PostgreSQL (>=10), MySQL (>=5.7), SQLite, and MSSQL (>=2008R2 SP3). This page will guide into preparing database. Only PostgreSQL and MySQL will be covered here since those database engines are widely-used in production. Database instance can be on same machine as Forgejo (local database setup), or on different machine (remote database).
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 Forgejo server. The client program is used to test connection to the database from Forgejo server, while Forgejo 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 Forgejo servers.
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.
**Table of Contents**
{{< toc >}}
## MySQL ## MySQL
@ -41,30 +27,30 @@ Note: All steps below requires that the database engine of your choice is instal
Enter the password as prompted. 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. 3. Create database user which will be used by Forgejo, authenticated by password. This example uses `'forgejo'` as password. Please use a secure password for your instance.
For local database: For local database:
```sql ```sql
SET old_passwords=0; SET old_passwords=0;
CREATE USER 'gitea' IDENTIFIED BY 'gitea'; CREATE USER 'forgejo' IDENTIFIED BY 'forgejo';
``` ```
For remote database: For remote database:
```sql ```sql
SET old_passwords=0; SET old_passwords=0;
CREATE USER 'gitea'@'192.0.2.10' IDENTIFIED BY 'gitea'; CREATE USER 'forgejo'@'192.0.2.10' IDENTIFIED BY 'forgejo';
``` ```
where `192.0.2.10` is the IP address of your Gitea instance. where `192.0.2.10` is the IP address of your Forgejo instance.
Replace username and password above as appropriate. Replace username and password above as appropriate.
4. Create database with UTF-8 charset and collation. Make sure to use `utf8mb4` charset instead of `utf8` as the former supports all Unicode characters (including emojis) beyond _Basic Multilingual Plane_. Also, collation chosen depending on your expected content. When in doubt, use either `unicode_ci` or `general_ci`. 4. Create database with UTF-8 charset and collation. Make sure to use `utf8mb4` charset instead of `utf8` as the former supports all Unicode characters (including emojis) beyond _Basic Multilingual Plane_. Also, collation chosen depending on your expected content. When in doubt, use either `unicode_ci` or `general_ci`.
```sql ```sql
CREATE DATABASE giteadb CHARACTER SET 'utf8mb4' COLLATE 'utf8mb4_unicode_ci'; CREATE DATABASE forgejodb CHARACTER SET 'utf8mb4' COLLATE 'utf8mb4_unicode_ci';
``` ```
Replace database name as appropriate. Replace database name as appropriate.
@ -74,26 +60,26 @@ Note: All steps below requires that the database engine of your choice is instal
For local database: For local database:
```sql ```sql
GRANT ALL PRIVILEGES ON giteadb.* TO 'gitea'; GRANT ALL PRIVILEGES ON forgejodb.* TO 'forgejo';
FLUSH PRIVILEGES; FLUSH PRIVILEGES;
``` ```
For remote database: For remote database:
```sql ```sql
GRANT ALL PRIVILEGES ON giteadb.* TO 'gitea'@'192.0.2.10'; GRANT ALL PRIVILEGES ON forgejodb.* TO 'forgejo'@'192.0.2.10';
FLUSH PRIVILEGES; FLUSH PRIVILEGES;
``` ```
6. Quit from database console by `exit`. 6. Quit from database console by `exit`.
7. On your Gitea server, test connection to the database: 7. On your Forgejo server, test connection to the database:
``` ```
mysql -u gitea -h 203.0.113.3 -p giteadb mysql -u forgejo -h 203.0.113.3 -p forgejodb
``` ```
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. where `forgejo` is database username, `forgejodb` 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. You should be connected to the database.
@ -119,10 +105,10 @@ Note: All steps below requires that the database engine of your choice is instal
su -c "psql" - postgres 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: 4. Create database user (role in PostgreSQL terms) with login privilege and password. Please use a secure, strong password instead of `'forgejo'` below:
```sql ```sql
CREATE ROLE gitea WITH LOGIN PASSWORD 'gitea'; CREATE ROLE forgejo WITH LOGIN PASSWORD 'forgejo';
``` ```
Replace username and password as appropriate. Replace username and password as appropriate.
@ -130,7 +116,7 @@ Note: All steps below requires that the database engine of your choice is instal
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: 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 ```sql
CREATE DATABASE giteadb WITH OWNER gitea TEMPLATE template0 ENCODING UTF8 LC_COLLATE 'en_US.UTF-8' LC_CTYPE 'en_US.UTF-8'; CREATE DATABASE forgejodb WITH OWNER forgejo TEMPLATE template0 ENCODING UTF8 LC_COLLATE 'en_US.UTF-8' LC_CTYPE 'en_US.UTF-8';
``` ```
Replace database name as appropriate. Replace database name as appropriate.
@ -140,53 +126,53 @@ Note: All steps below requires that the database engine of your choice is instal
For local database: For local database:
```ini ```ini
local giteadb gitea scram-sha-256 local forgejodb forgejo scram-sha-256
``` ```
For remote database: For remote database:
```ini ```ini
host giteadb gitea 192.0.2.10/32 scram-sha-256 host forgejodb forgejo 192.0.2.10/32 scram-sha-256
``` ```
Replace database name, user, and IP address of Gitea instance with your own. Replace database name, user, and IP address of Forgejo 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. 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. Restart PostgreSQL to apply new authentication rules.
7. On your Gitea server, test connection to the database. 7. On your Forgejo server, test connection to the database.
For local database: For local database:
``` ```
psql -U gitea -d giteadb psql -U forgejo -d forgejodb
``` ```
For remote database: For remote database:
``` ```
psql "postgres://gitea@203.0.113.3/giteadb" psql "postgres://forgejo@203.0.113.3/forgejodb"
``` ```
where `gitea` is database user, `giteadb` is database name, and `203.0.113.3` is IP address of your database instance. where `forgejo` is database user, `forgejodb` 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. You should be prompted to enter password for the database user, and connected to the database.
## Database Connection over TLS ## 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. If the communication between Forgejo and your database instance is performed through a private network, or if Forgejo and the database are running on the same server, this section can be omitted since the security between Forgejo 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 ### 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. - You need two valid TLS certificates, one for the database instance (database server) and one for the Forgejo 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. - 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. - 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 Forgejo 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. - You need domain name mappings of both Forgejo 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 ### PostgreSQL
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. The PostgreSQL driver used by Forgejo 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: 1. On the server with the database instance, place the following credentials:
@ -211,25 +197,25 @@ The PostgreSQL driver used by Gitea supports two-way TLS. In two-way TLS, both d
chmod 0600 /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. 4. Edit `pg_hba.conf` rule to only allow Forgejo database user to connect over SSL, and to require client certificate verification.
For PostgreSQL 12: For PostgreSQL 12:
```ini ```ini
hostssl giteadb gitea 192.0.2.10/32 scram-sha-256 clientcert=verify-full hostssl forgejodb forgejo 192.0.2.10/32 scram-sha-256 clientcert=verify-full
``` ```
For PostgreSQL 11 and earlier: For PostgreSQL 11 and earlier:
```ini ```ini
hostssl giteadb gitea 192.0.2.10/32 scram-sha-256 clientcert=1 hostssl forgejodb forgejo 192.0.2.10/32 scram-sha-256 clientcert=1
``` ```
Replace database name, user, and IP address of Gitea instance as appropriate. Replace database name, user, and IP address of Forgejo instance as appropriate.
5. Restart PostgreSQL to apply configurations above. 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`): 6. On the server running the Forgejo instance, place the following credentials under the home directory of the user who runs Forgejo (e.g. `git`):
- `~/.postgresql/postgresql.crt`: Database client certificate - `~/.postgresql/postgresql.crt`: Database client certificate
- `~/.postgresql/postgresql.key`: Database client private key - `~/.postgresql/postgresql.key`: Database client private key
@ -247,14 +233,14 @@ The PostgreSQL driver used by Gitea supports two-way TLS. In two-way TLS, both d
8. Test the connection to the database: 8. Test the connection to the database:
``` ```
psql "postgres://gitea@example.db/giteadb?sslmode=verify-full" psql "postgres://forgejo@example.db/forgejodb?sslmode=verify-full"
``` ```
You should be prompted to enter password for the database user, and then be connected to the database. You should be prompted to enter password for the database user, and then be connected to the database.
### MySQL ### MySQL
While the MySQL driver used by Gitea also supports two-way TLS, Gitea currently supports only one-way TLS. See issue #10828 for details. While the MySQL driver used by Forgejo also supports two-way TLS, Forgejo 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. 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.
@ -283,23 +269,23 @@ In one-way TLS, the database client verifies the certificate sent from server du
4. Restart MySQL to apply the setting. 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: 5. The database user for Forgejo may have been created earlier, but it would authenticate only against the IP addresses of the server running Forgejo. To authenticate against its domain name, recreate the user, and this time also set it to require TLS for connecting to the database:
```sql ```sql
DROP USER 'gitea'@'192.0.2.10'; DROP USER 'forgejo'@'192.0.2.10';
CREATE USER 'gitea'@'example.gitea' IDENTIFIED BY 'gitea' REQUIRE SSL; CREATE USER 'forgejo'@'example.forgejo' IDENTIFIED BY 'forgejo' REQUIRE SSL;
GRANT ALL PRIVILEGES ON giteadb.* TO 'gitea'@'example.gitea'; GRANT ALL PRIVILEGES ON forgejodb.* TO 'forgejo'@'example.forgejo';
FLUSH PRIVILEGES; FLUSH PRIVILEGES;
``` ```
Replace database user name, password, and Gitea instance domain as appropriate. Replace database user name, password, and Forgejo 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. 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 Forgejo 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: 7. On the server running Forgejo, test connection to the database:
``` ```
mysql -u gitea -h example.db -p --ssl mysql -u forgejo -h example.db -p --ssl
``` ```
You should be connected to the database. You should be connected to the database.

1
v1.19/admin/index.md
View file

@ -6,6 +6,7 @@ title: 'Forgejo v1.19 administrator guide'
These documents are targeted to people who run Forgejo on their machines. These documents are targeted to people who run Forgejo on their machines.
- [Seek Assistance](seek-assistance) - [Seek Assistance](seek-assistance)
- [Database Preparation](database-preparation)
- [Configuration Cheat Sheet](config-cheat-sheet) - [Configuration Cheat Sheet](config-cheat-sheet)
- [Upgrade guide](upgrade) - [Upgrade guide](upgrade)
- [Command Line](command-line) - [Command Line](command-line)