documentation/docs/engineering-guide/gitea-dmz.md

Gitea (Production)

Overview

DNS resolution is pointing to the F5/WAF for all services. HTTPS requests are terminated and inspected by the WAF, SSH is just proxied through to have a simple DNS setup.

Docker Setup

All Services are deployed as docker containers, these are namely:

• NGINX Reverse Proxy
  • Handling and distributing requests from WAF to the containers
• Gitea
  • GIT Forge container
• PostgreSQL
  • Gitea's database - only connected to Gitea container
• Caddy Webserver
  • Handling Pages requests (partially developed by PSI)
• Opengist
  • Handling Snippets

Like shown on the picture below, the nginx container is the only one able to take requests from outside the docker network and is only allowed to take requests from the WAF. On the WAF there is a certificate check active, that only lx-gitea-dmz-01.psi.ch is allowed to act as backend for gitea.psi.ch, pages.psi.ch and snippets.psi.ch. All services communicate inside the docker backend network and use names only known inside that network. See the ansible code for more information.

Ansible

The service is deployed and updated with ansible bootstrap. To upgrade or downgrade a container or tinker with configurations, logo, frontpage template you can edit the respective files and run the playbook. When installing the service from scratch and it will fail when deploying the snippets, pages and runner container due to missing tokens. These tokens must be generated within the running Gitea instance first and added to host_vars for upgrade and configuration purposes the playbook is idempotent.

• Gitea Admin User
  • Create a Administrative User within the GUI or CLI
• Access Token
  • Create a Access Token for that User that can be used with pages
• Runner Token
  • Create a Runner Token
• OAuth2 Client ID and Secret
  • Create a OAuth2 Application These tasks can all be done with the created Admin user. Add the secrets to the playbook and rerun it.

Update and Configure

• Update To update Gitea and its components, the exact version needs to be defined in "group_vars".
• Configure TODO: notify a docker restart, when editing config files

Logo and favicon

To edit any pictures inside Gitea the original picture needs to be in correct format. Follow these steps to do so:

• Clone https://gitea.psi.ch/linux/gitea.git (gitea code mirror)
• Copy the original pictures in assets
• run make generate-images (needs node and node canvas installed)
• copy the images from public/assets/img/ to files/srv/gitea/gitea/public/assets/img/ in bootstrap
• run the playbook

Templates

https://gitea.psi.ch/linux/gitea/src/branch/main/templates are all templates for customizing the view of gitea. Edit it accordingly and put them in /srv/gitea/gitea/templates/ respectively in their folder and restart gitea.

Authentication

The main authentication source is Entra-ID. The users are synced from LDAP and mapped upon login with their e-mail address. Authentication Type is OAuth2 and the Provider is OpenID Connect. Add the secrets from linux PW store and use the default claim name "groups". This will enable users to login again and access their projects.

Configuration

Since the configuration file contains all the secrets, only the custom parts are shown here. These can be added to /srv/gitea/gitea/conf/app.ini in no specific order.

[mailer]
ENABLED        = true
FROM           = gitea@psi.ch
PROTOCOL       = smtp+starttls
SMTP_ADDR      = smtp.psi.ch
SMTP_PORT      = 25

[oauth2_client]
USERNAME = email
ACCOUNT_LINKING = auto
ENABLE_AUTO_REGISTRATION = true

[repository.signing]
DEFAULT_TRUST_MODEL = committer

[service.explore]
DISABLE_USERS_PAGE = true

[service]
DISABLE_REGISTRATION = true
REQUIRE_SIGNIN_VIEW = false
REGISTER_EMAIL_CONFIRM = false
ENABLE_NOTIFY_MAIL = true
ALLOW_ONLY_EXTERNAL_REGISTRATION = false
DEFAULT_ALLOW_CREATE_ORGANIZATION = true
ENABLE_BASIC_AUTHENTICATION = false
ENABLE_PASSWORD_SIGNIN_FORM = false
DEFAULT_ORG_VISIBILITY = private
DEFAULT_USER_VISIBILITY = internal
ENABLE_PASSKEY_AUTHENTICATION = false
AUTO_WATCH_NEW_REPOS = false

[indexer]
ISSUE_INDEXER_PATH = /data/gitea/indexers/issues.bleve
REPO_INDEXER_ENABLED = true
REPO_INDEXER_PATH = indexers/repos.bleve
MAX_FILE_SIZE = 1048576
REPO_INDEXER_INCLUDE =
REPO_INDEXER_EXCLUDE = resources/bin/**

[actions]
ENABLED=true

Service Users

Since local login is disabled, service users need to be created inside the gitea container with the gitea admin "console". There is two types of users, bot and regular. Bot users can only be used in Gitea CI/CD workflows, to "login" to gitea with a script or similar a regular user is needed. See commands below.

# connect to the container as user git
docker exec -it --user git gitea bash

# create bot user
gitea admin user create --username {org-gitea} --email {username@psi.ch} --restricted --user-type bot

# create service user with random password and an access token for read operations
gitea admin user create --username {org-gitea}  --access-token --access-token-name read --access-token-scopes read:repository,read:package,read:issue,read:misc --email yourmail@psi.ch --random-password --must-change-password=false

# create a token with a give scope (scopes can be found here: https://gitea.psi.ch/user/settings/applications) that can be comma separated but without spaces!
gitea admin user generate-access-token --username {org-gitea} --token-name {username-scope} --scopes {read|write:scope}

Mapping AD Groups to Teams

To realize access control with Active Directory groups in Gitea organizations a JSON file needs to edited in the admin panel. This can be done as follows:

1. Navigate to: 'Site Administration -> Identity&Access -> Authentication Sources -> PSI LDAP -> "Map LDAP Groups.."

2. Configure the sync, i.e. mapping group to gitea team (attention: configuration seems to be case sensitive - https://forum.gitea.com/t/mapping-ldap-groups-to-organizations-and-teams/10438/2). The JSON string has following structure:

• LDAP Group DN as Primary Key
• Organization
• Team

If you get an error message updating, you probably made an error in formatting the JSON (Commas or indentation)

{
    "CN=kst-1337,OU=Official,OU=Groups,OU=psi,DC=d,DC=psi,DC=ch": {
        "ORGANIZATION": ["TEAM"]
    },
}

3. Trigger sync (this does take some time...)

The teams in the organizations must exist, the sync will not create the teams for you!!!

Restore Repos from backup

To restore accidentally deleted repos gitea, AIT needs to restore the disk to a point in time before the repo got deleted.

1. Mount the restore disk to a linux server
2. Copy the data to /srv/gitea/git/repositories/ORG/ NOTE: It is important that the repo name is all lower case and ends with .git and the permissions are set correctly. The owner must be git:git
3. Login to gitea, Site Administration -> Admin Settings (Right Panel) -> Code Assets -> Repositories. Click on "Unadopted Repositories" and adopt files.

SWITCH edu-ID Login for External Users

Gitea supports login through SWITCH edu-ID for external users.

The intended model is:

• Existing PSI users normally use the existing PSI authentication.
• External users can authenticate using their personal SWITCH edu-ID.
• edu-ID users do not need to be provisioned or synchronized into Gitea beforehand.
• A new edu-ID user is automatically created on first login.
• Accounts authenticating through the edu-ID source are treated as restricted users.
• Restricted users can then be explicitly added to the required repositories/projects.
• If an edu-ID email matches an existing Gitea account, Gitea automatically links the edu-ID identity to that account.

SWITCH edu-ID OIDC Resource

The OIDC application is registered in the SWITCH Resource Registry.

Application Type

The application is registered as:

Server-based web application, acting as confidential client

Gitea is a server-side OIDC client and stores the client secret itself.

General Settings

Setting	Value
Resource	External Users / PSI Gitea
Sector Identifier URI	https://gitea.psi.ch/
Offline Access	Disabled
Approving Organization	Paul Scherrer Institute
Subject Type	OIDC pairwise subject

The pairwise subject provides Gitea with a stable identifier for the edu-ID identity without exposing a globally reusable edu-ID identifier.

Redirect URI

The Gitea authentication source is named:

edu-id