brandon/oam
1
0
Fork 0
mirror of https://gitea.com/mcereda/oam.git synced 2026-02-09 05:44:23 +00:00
Code Issues Packages Projects Releases Wiki Activity

chore(gitea): improve kubernetes settings and knowledge

Browse Source
This commit is contained in:
Michele Cereda
2024-09-23 20:34:31 +02:00
parent ed00719fe6
commit c827dfaeb8
3 changed files with 242 additions and 33 deletions
Download Patch File Download Diff File Expand all files Collapse all files

178
knowledge base/gitea.md
View File

@@ -4,8 +4,11 @@
1. [Installation](#installation)
1. [Configuration](#configuration)
1. [LFS](#lfs)
1. [HTTPS certificates](#https-certificates)
1. [Set up HTTP redirection](#set-up-http-redirection)
1. [HTTPS](#https)
1. [HTTP redirection to HTTPS](#http-redirection-to-https)
1. [Send emails](#send-emails)
1. [Use Oauth2 for authentication](#use-oauth2-for-authentication)
1. [Map OAuth2 users to Gitea teams and organizations](#map-oauth2-users-to-gitea-teams-and-organizations)
1. [Further readings](#further-readings)
1. [Sources](#sources)
@@ -46,15 +49,15 @@ helm upgrade --install 'gitea' 'gitea-charts/gitea'
## Installation
<details>
<summary>Container</summary>
<summary style="padding-bottom: 1rem">Container image</summary>
Docker [compose file].
[Compose file example][compose file].
The `git` user has UID and GID set to 1000 by default.<br/>
Change those in the compose file or whatever.
The `git` user has UID and GID set to `1000` by default.<br/>
Change those in the compose file or whatever one needs to.
One can optionally define the administrative user during the initial setup.<br/>
If no administrative user is defined in that moment, the first registered user becomes the administrator.
If no administrative user is defined in that moment, the **first registered user** becomes the administrator.
</details>
@@ -62,83 +65,194 @@ If no administrative user is defined in that moment, the first registered user b
Refer the [Configuration cheat sheet].
Settings are loaded from the configuration file usually found at `/etc/gitea/app.ini`.
Container users can update the configuration file through environment variables.<br/>
The image runs `environment-to-ini` before running the server, which maps them to values in the ini file:
- Variables in the form `GITEA__{{SECTION_NAME}}__{{KEY_NAME}}` are mapped to the `[section_name]` ini section and the
`KEY_NAME` key with the provided value.
- Variables in the form `GITEA__{{SECTION_NAME}}__{{KEY_NAME}}__{{PATH_TO_FILE}}` are mapped to the `[section_name]` ini
section and the `KEY_NAME` key with the value loaded from the specified file.
Environment variables usually restricted to the `0-9A-Z_` reduced character.<br/>
To allow setting up sections with characters outside of that set, characters shall be escaped as a UTF8 byte string.
E.g. to configure:
```ini
[log.console]
COLORIZE = false
STDERR = true
```
One would need to encode `.` as `_0X2E_` and set the environment variables `GITEA__LOG_0x2E_CONSOLE__COLORIZE=false` and
`GITEA__LOG_0x2E_CONSOLE__STDERR=false`.<br/>
Other examples can be found on the [configuration cheat sheet].
If using the helm chart with Kubernetes, the configuration settings defined in the values' `gitea.config` key are saved
in the `gitea-inline-config` secret and are then used to build the configuration file in the container.
### LFS
Enable the built-in LFS support by updating the `app.ini` configuration file:
Enable the built-in LFS support:
```ini
[server]
LFS_START_SERVER = true
[lfs]
PATH = /home/gitea/data/lfs # defaults to {{data}}/lfs
PATH = /home/gitea/data/lfs # defaults to "{{data_directory}}/lfs"
```
### HTTPS certificates
### HTTPS
Refer [HTTPS setup to encrypt connections to Gitea].
If the certificate is signed by a third party certificate authority (i.e. not self-signed), then `cert.pem` should
contain the certificate chain.<br/>
If the certificate is signed by a third party certificate authority (i.e. not self-signed), then the `cert.pem` file
shall contain the certificate chain too.<br/>
The server certificate must be **the first entry** in `cert.pem`, followed by the intermediaries in order (if any).<br/>
The root certificate does **not** have to be included as the connecting client must already have it in order to
The root certificate does **not** need to be included, as the connecting client must already have it in order to
establish any trust relationship.
The file path in the configuration is relative to the `GITEA_CUSTOM` environment variable when it is a relative path.
<details>
<details style="padding-left: 1rem">
<summary>Self-signed certificate</summary>
1. Generate a self signed certificate:
```sh
gitea cert --host 'git.host.fqdn'
docker compose exec server gitea cert --host 'git.host.fqdn'
gitea cert --host 'gitea.company.com'
docker compose exec server gitea cert --host 'gitea.company.com'
```
1. Change the `app.ini` configuration file:
1. Reference the certificate files in the configuration file:
```ini
[server]
PROTOCOL = https
ROOT_URL = https://git.host.fqdn:3000/
ROOT_URL = https://gitea.company.com:3000/
HTTP_PORT = 3000
CERT_FILE = /path/to/cert.pem
KEY_FILE = /path/to/key.pem
```
</details>
<details>
<details style="padding-left: 1em">
<summary>ACME certificate</summary>
Defaults to using Let's Encrypt.
Change the `app.ini` configuration file:
```ini
[server]
PROTOCOL=https
DOMAIN=git.example.com
ENABLE_ACME=true
ACME_ACCEPTTOS=true
ACME_DIRECTORY=https
ACME_EMAIL=email@example.com # can be omitted here and provided manually at first run, after which it is cached
PROTOCOL = https
DOMAIN = gitea.company.com
ENABLE_ACME = true
ACME_ACCEPTTOS = true
ACME_DIRECTORY = https
ACME_EMAIL = user@company.com # can be omitted here and provided manually at first run, after which it is cached
```
</details>
### Set up HTTP redirection
#### HTTP redirection to HTTPS
Gitea server is able to listen on one single port. Enable the HTTP redirection service to redirect HTTP requests to the
HTTPS port:
Gitea's server is able to listen on one port only and requires a separate service to provide redirection.<br/>
If HTTPS is enabled and one wants to offer an HTTP port to redirect HTTP requests from, enable the HTTP redirection
service:
```ini
[server]
REDIRECT_OTHER_PORT = true
PORT_TO_REDIRECT = 3080 # http port to be redirected to https
PORT_TO_REDIRECT = 3080 # http port that will be redirected to the https port
```
When using Docker, make sure this port is published.
When using Docker, make sure this port is published too.
### Send emails
Use SMTP servers as relay should one want to leverage accounts at email providers.
<details>
<summary>AWS</summary>
```ini
[mailer]
ENABLED = true
PROTOCOL = smtp+starttls
SMTP_ADDR = email-smtp.eu-west-1.amazonaws.com
SMTP_PORT = 587
USER = AKIA…7890
PASSWD = `ABCD…7890`
FROM = noreply@gitea.company.com
```
</details>
<details>
<summary style="padding-bottom: 1rem">Gmail</summary>
> Gmail will not allow the direct use of one's Google account password.<br/>
> Create an App password and enable 2FA on one's Google account.
```ini
[mailer]
ENABLED = true
PROTOCOL = smtps
SMTP_ADDR = smtp.gmail.com
SMTP_PORT = 465
FROM = user@gmail.com
USER = user
PASSWD = `App_Password`
```
</details>
### Use Oauth2 for authentication
Remember to set up a mailer should one want to require email confirmation during registration.
<details>
<summary>Google Cloud example</summary>
1. Create a Client ID in [Google Cloud](https://console.cloud.google.com/apis/credentials) with at least the following
settings:
```yaml
Application type: web application
Name: whatever # anything is fine here
Authorized JavaScript origins:
- https://gitea.company.com:3000 # the ROOT_URL of one's instance
Authorized redirect URIs:
- # the 'Google' identifier here needs to be the name given to the provider in the next step
https://gitea.company.com:3000/user/oauth2/Google/callback
```
1. Configure the provider in the Gitea instance at
_Site Administration_ > _Identity & Access_ > _Authentication Sources_ with at least the following settings:
```yaml
Authentication Type: OAuth2
Authentication Name: Google # this defines the identifier for the redirect URI above
OAuth2 Provider: Google
Client ID (Key): 012345678901-abcdefghijklmnopqrstuvwxyz012345.apps.googleusercontent.com
Client Secret: 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
```
1. Configure the Gitea instance to automatically create users from the provider:
```ini
[oauth2_client]
ENABLE_AUTO_REGISTRATION: true
USERNAME: email
```
</details>
#### Map OAuth2 users to Gitea teams and organizations
TODO
## Further readings