diff options
Diffstat (limited to 'docs/content/doc/installation/database-preparation.en-us.md')
| -rw-r--r-- | docs/content/doc/installation/database-preparation.en-us.md | 58 |
1 files changed, 29 insertions, 29 deletions
diff --git a/docs/content/doc/installation/database-preparation.en-us.md b/docs/content/doc/installation/database-preparation.en-us.md index 13a215d814..b8ad5d6859 100644 --- a/docs/content/doc/installation/database-preparation.en-us.md +++ b/docs/content/doc/installation/database-preparation.en-us.md @@ -27,13 +27,13 @@ Note: All steps below requires that the database engine of your choice is instal ## MySQL -1. For remote database setup, you will need to make MySQL listen to your IP address. Edit `bind-address` option on `/etc/mysql/my.cnf` on database instance to: +1. For remote database setup, you will need to make MySQL listen to your IP address. Edit `bind-address` option on `/etc/mysql/my.cnf` on database instance to: ```ini bind-address = 203.0.113.3 ``` -2. On database instance, login to database console as root: +2. On database instance, login to database console as root: ``` mysql -u root -p @@ -41,7 +41,7 @@ Note: All steps below requires that the database engine of your choice is instal 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 Gitea, authenticated by password. This example uses `'gitea'` as password. Please use a secure password for your instance. For local database: @@ -61,7 +61,7 @@ Note: All steps below requires that the database engine of your choice is instal Replace username and password above as appropriate. -4. Create database with UTF-8 charset and collation. Make sure to use `utf8mb4` charset instead of `utf8` as the former supports all Unicode characters (including emojis) beyond _Basic Multilingual Plane_. Also, collation chosen depending on your expected content. When in doubt, use either `unicode_ci` or `general_ci`. +4. Create database with UTF-8 charset and collation. Make sure to use `utf8mb4` charset instead of `utf8` as the former supports all Unicode characters (including emojis) beyond _Basic Multilingual Plane_. Also, collation chosen depending on your expected content. When in doubt, use either `unicode_ci` or `general_ci`. ```sql CREATE DATABASE giteadb CHARACTER SET 'utf8mb4' COLLATE 'utf8mb4_unicode_ci'; @@ -69,7 +69,7 @@ Note: All steps below requires that the database engine of your choice is instal Replace database name as appropriate. -5. Grant all privileges on the database to database user created above. +5. Grant all privileges on the database to database user created above. For local database: @@ -85,9 +85,9 @@ Note: All steps below requires that the database engine of your choice is instal 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 Gitea server, test connection to the database: ``` mysql -u gitea -h 203.0.113.3 -p giteadb @@ -99,13 +99,13 @@ Note: All steps below requires that the database engine of your choice is instal ## 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: +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: +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 @@ -113,13 +113,13 @@ Note: All steps below requires that the database engine of your choice is instal Restart PostgreSQL to apply the setting. -3. On the database server, login to the database console as superuser: +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: +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'; @@ -127,7 +127,7 @@ Note: All steps below requires that the database engine of your choice is instal 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: +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'; @@ -135,7 +135,7 @@ Note: All steps below requires that the database engine of your choice is instal 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`. +6. Allow the database user to access the database created above by adding the following authentication rule to `pg_hba.conf`. For local database: @@ -155,7 +155,7 @@ Note: All steps below requires that the database engine of your choice is instal Restart PostgreSQL to apply new authentication rules. -7. On your Gitea server, test connection to the database. +7. On your Gitea server, test connection to the database. For local database: @@ -188,13 +188,13 @@ If the communication between Gitea and your database instance is performed throu 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: +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`: +2. Add following options to `postgresql.conf`: ```ini ssl = on @@ -204,14 +204,14 @@ The PostgreSQL driver used by Gitea supports two-way TLS. In two-way TLS, both d ssl_min_protocol_version = 'TLSv1.2' ``` -3. Adjust credentials ownership and permission, as required by PostgreSQL: +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. +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: @@ -227,9 +227,9 @@ The PostgreSQL driver used by Gitea supports two-way TLS. In two-way TLS, both d Replace database name, user, and IP address of Gitea 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 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 @@ -237,14 +237,14 @@ The PostgreSQL driver used by Gitea supports two-way TLS. In two-way TLS, both d 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: +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: +8. Test the connection to the database: ``` psql "postgres://gitea@example.db/giteadb?sslmode=verify-full" @@ -258,13 +258,13 @@ While the MySQL driver used by Gitea also supports two-way TLS, Gitea currently 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: +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`: +2. Add following options to `my.cnf`: ```ini [mysqld] @@ -274,16 +274,16 @@ In one-way TLS, the database client verifies the certificate sent from server du tls-version = TLSv1.2,TLSv1.3 ``` -3. Adjust credentials ownership and permission: +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. +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 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'; @@ -294,9 +294,9 @@ In one-way TLS, the database client verifies the certificate sent from server du 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. +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: +7. On the server running Gitea, test connection to the database: ``` mysql -u gitea -h example.db -p --ssl |