Git

💻 We use Git through Forgejo for working together on code and similar projects. We host our own instance of Forgejo on our server ➡️ https://git.kanthaus.online/

Git

Git is a distributed version control system. It allows many people to work on different copies of the same project, and merge the different changes in a coherent way. It's like a multiverse/time-machine for files. An actually-pretty-good game for learning git is Oh My Git! (Linux, macOS, and Windows) and a good book is git-scm.com

Forgejo

Forgejo is (code) forge. It provides a central location for git repositories so we can synchronize easily (otherwise we'd have to run around with USB sticks), a web interface (so you can make edits without using the terminal, or even having the files on your laptop) and an issue tracker (so you can have discussions separate-but-beside the project files)

What is stored where?

Among other things we have the following repositories:

• kanthaus.online, where we store our website, https://kanthaus.online/.
• kanthaus-private, where we store our residence record, internal meeting minutes, financial plans and other stuff that contains personal information. Everything of relevance that consists of text and has pieces of confidential data should be put here.
• kanthaus-public, which is publicly accessible as the name suggests. In this repository we do our task management via issues (which you can find here). This is especially important for our [[../social/roadmap.md|roadmap plannings]]. Other than that we have drafts, policies, signs, data on our water, electricity and gas usage and much more in here.
• expfloorer hosts a floorplan of Kanthaus.

How to get started

We use our Nextcloud accounts for signing into Forgejo, so you'll need one of those first. Then login to https://git.kanthaus.online/ and you will be automatically added to the “Kanthaus” organization in which our repositories are stored.

Migrating from Gitlab

Before Forgejo, we used Gitlab. If you still have local clones from Gitlab, you need to update those to point to Forgejo.

On the page of each repository, such as https://git.kanthaus.online/kanthaus/handbook, copy the clone URL you prefer. For instance, for the handbook, they look like this:

• HTTPS: https://git.kanthaus.online/kanthaus/handbook.git
• SSH: ssh://git@ssh.git.kanthaus.online:2222/kanthaus/handbook.git

In your local clone, run:

git remote set-url origin <new-url>

Note that if you want to use SSH URLs, you first need to add an SSH key.

Instructions for administrators

We are running Forgejo via Docker inside our Docker-Compose deployment of services on the kanthaus-server.

Setting it up from scratch

After launching the service via Docker, the following manual steps need to be taken to configure the instance:

• Go to https://git.kanthaus.online/ where the set-up screen should display. Change the following settings:
• Site title: “Kanthaus Git”
• SMTP host: gehrels.uberspace.de
• SMTP port: 587
• Send email as: git@kanthaus.online
• SMTP user: git@kanthaus.online
• SMTP password: found in the Kanthaus keepass
• Tick “Enable email notifications”
• Tick “Disable Gravatar”
• Tick “Allow registration only via external services”
• Tick “Hide email addresses by default”
• Domain for hidden email addresses: git.kanthaus.online
• Set up an admin user with credentials you own: we will delete it later on
• After validating the sign-up form, go to https://git.kanthaus.online/org/create and create a “kanthaus” organization. You can prettify it a little, by adding a bit of metadata at https://git.kanthaus.online/org/kanthaus/settings and uploading a logo from https://kanthaus.online/pics/newLogo.png
• In Forgejo’s configuration file (/data/services/forgejo/config/app.ini), add the following lines at the end:

[oauth2_client]
USERNAME = userid
ENABLE_AUTO_REGISTRATION = true

You can also take this opportunity to add LANDING_PAGE = /kanthaus in the [server] section. And disable OpenID login:

[openid]
ENABLE_OPENID_SIGNIN = false
ENABLE_OPENID_SIGNUP = false

• Make sure our Nextcloud instance has the OIDC Identity Provider app installed
• Go to Nextcloud’s security settings (while logged in with an administrator account in NextCloud) and generate a new OpenID Connect client (if it does not exist yet), with the following details
  • Name: Forgejo
  • Redirection URI: https://git.kanthaus.online/user/oauth2/NextCloud/callback
• Go to Forgejo’s Authentication Sources and click “Add an authentication source”, with the following settings:
  • Authentication type: OAuth2
  • Authentication name: “NextCloud”
  • OAuth2 provider: OpenID Connect
  • Client ID: the client ID produced at the previous step
  • Client secret: the client secret produced at the previous step
  • OpenID Connect Auto Discovery URL: https://cloud.kanthaus.online/.well-known/openid-configuration
  • Additional scopes: email
  • Claim name providing group names for this source: roles
  • Group claim value for administrator users: admin
  • Map claimed groups to Organization teams: {"Kanthaus": {"kanthaus": ["Owners"]}}
• Restart forgejo with docker-compose restart forgejo (in /opt/kh-services)

Note: this configuration relies on our NextCloud instance having the “clean URLs” option enabled. Otherwise, the URLs need to be adapted to add index.php in them, such as https://cloud.kanthaus.online/index.php/.well-known/openid-configuration.

Setting up SSH access

To let users clone via SSH, we need to take some additional steps. In the configuration file (/data/services/forgejo/config/app.ini), set those settings (if not set already):

[server]
START_SSH_SERVER = true
SSH_PORT = 2222
SSH_LISTEN_PORT = 2222
SSH_LISTEN_HOST = 0.0.0.0
SSH_DOMAIN = ssh.git.kanthaus.online

Then, set up a port forwarding in OpenWISP. You need to be connected to the kanthaus-admin network for this and go to the NAT Port Forward page. Create a new rule: * Interface: WAN * TCP/IP version: IPv4+IPv6 * Protocol: TCP * Destination: WAN address * Destination port range: (other) 2222 to (other) 2222 * Redirect target port: 2222 * Description: git SSH access for Forgejo

The ssh.git.kanthaus.online should point to the Fritzbox (not kanthaus-server) so that it can take care of forwarding the port. If the domain points to kanthaus-server, connecting over IPv6 will likely fail.

Setting up the continuous integration

In the configuration file (/data/services/forgejo/config/app.ini), set those settings (if not set already):

[actions]
ENABLED = true

Then, go to the Runners Management page and click “Create new Runner”. Copy the registration token and put it in /opt/kh-services/.env as FORGEJO_RUNNER_REGISTRATION_TOKEN.

Delete /data/services/forgejo_runner/.runner if it is present.

Restart the runner with docker-compose up -d in /opt/kh-services.

The runner will register and should become visible in Forgejo’s settings.

For each repository where you want to use the runner, you need to enable actions in the repository’s settings.

Backing up Forgejo’s data

You need to back up two things:

• the contents of /data/services/forgejo
• the Postgresql database.

To do so:

• First, find out the container id of the postgres instance with docker ps | grep kh-services_postgres and copy the first hash in the output to the second command, in place of <container-id>
• Run docker exec -it <container-id> pg_dump -U postgres --clean forgejo | gzip > forgejo_database_dump.sql.gz

To restore the backup, you need to:

• restore the contents of /data/services/forgejo
• restore the database similarly with: cat forgejo_database_dump.sql.gz | gunzip | docker exec -i <container-id> psql -U postgres forgejo