Updated git documentations and wrote a blog post about it

This commit is contained in:
Julien Dessaux 2022-07-17 15:26:23 +02:00
parent e0f6531624
commit 5da6e5f3ca
Signed by: adyxax
GPG key ID: F92E51B86E07177E
6 changed files with 202 additions and 102 deletions

View file

@ -0,0 +1,30 @@
---
title: Migrating from gitea to gitolite and cgit
description: A quest for simplicity
date: 2022-07-15
---
## Introduction
I switched to gitea in 2020 in order to host repositories for non tech people, but I no longer have that need.
Gitea is simple enough to host but it has way too many features and way too frequent (security) updates! I therefore chose to simplify things again and went back to gitolite which I used for almost a decade before I switched to gitea. I chose to keep a web frontend because I do not want to link to github in my blog articles and settled on cgit to fill that role.
## Installation and configuration
The installation is documented in the following docs articles on this website:
- [gitolite]({{< ref "gitolite" >}})
- [cgit]({{< ref "cgit" >}})
If you are following these installation notes as a guide, there is one important thing to know: I wanted to keep gitea links mostly working (at least redirecting to the correct repository), so I create all my publicly available repositories under an `adyxax` folder. This shows mostly in the cgit and nginx configurations.
## Challenges
The main challenge I encountered was how to make `go get` or `go install` work with cgit. When go tries to fetch a dependency from a remote git repository, it expects a particular header to be present in the http response, something like:
```html
<meta name="go-import" content="git.adyxax.org/adyxax/bareos-zabbix-check git https://git.adyxax.org/adyxax/bareos-zabbix-check">
```
I solved that issue of injecting this header by:
- setting a `cgit.extra-head-content` in the gitconfig of my go repositories
- configuring gitolite to accept such header by customizing its `GIT_CONFIG_KEYS`

View file

@ -1,15 +1,19 @@
--- ---
title: "git" title: "git"
description: adyxax.org gitea instance description: adyxax.org git server
--- ---
## Introduction ## Introduction
git.adyxax.org is a [gitea](https://gitea.io/) instance. For about 10 years I used a gitolite installation but I finally went for a gui instead in order to host repositories for non tech people. git.adyxax.org is the server hosting my git repositories. It uses gitolite as backend (reachable over ssh) with cgit and nginx as the read only web frontend.
From October 2020 to June 2022 I relied on a [gitea](https://gitea.io/) instance and for the decade before that i relied on a gitolite (without a web frontend). I initially switched to gitea in order to host repositories for non tech people, but I no longer have that need. Gitea is simple enough to host but it has way too many features and way too frequent (security) updates! I therefore chose to simplify things again. I went with cgit as a web frontend because I did not want to link to github in my blog articles. Github is only a mirror of some of my work and I do not want it to be more than that.
## Captain's log ## Captain's log
- 2022-06-01 : Migrated to cgit on FreeBSD.
- 2021-11-12 : Migrated to a podman setup on dalinar, and from PostgreSQL to SQLite - 2021-11-12 : Migrated to a podman setup on dalinar, and from PostgreSQL to SQLite
- 2020-10-05 : Initial setup of gitea on yen.adyxax.org's OpenBSD - 2020-10-05 : Initial setup of gitea on yen.adyxax.org's OpenBSD
- circa 2010 : Initial setup of gitolite on legend.adyxax.org's Centos 5
## Docs ## Docs

View file

@ -5,8 +5,7 @@ description: Backups of git.adyxax.org
## Documentation ## Documentation
Backups are configured with borg on `dalinar.adyxax.org` to `yen.adyxax.org`. Backups are run with borg and stored on `yen.adyxax.org`.
There are two jobs : There is only one job :
- a filesystem backup of `/srv/gitea-data` - a filesystem backup of `/srv/git`
- a `VACUUM INTO` backup job of gitea's SQLite database

View file

@ -0,0 +1,94 @@
---
title: "cgit and nginx"
description: Installation notes of cgit
---
## Introduction
This article details how I installed and configured cgit on FreeBSD to serve as the web frontend of my gitolite repositories.
## Installation
cgit can be bootstrapped with the following :
```yaml
pkg install cgit fcgiwrap
```
## Configuration
Here is my `/usr/local/etc/cgitrc-adyxax` file:
```cfg
about-filter=/usr/local/lib/cgit/filters/about-formatting.sh
clone-url=https://$HTTP_HOST/$CGIT_REPO_URL
enable-commit-graph=1
enable-follow-links=1
enable-git-config=1
enable-log-filecount=1
enable-log-linecount=1
enable-subject-links=1
mimetype.gif=image/gif
mimetype.html=text/html
mimetype.jpg=image/jpeg
mimetype.jpeg=image/jpeg
mimetype.pdf=application/pdf
mimetype.png=image/png
mimetype.svg=image/svg+xml
noplainemail=1
readme=:README.md
remove-suffix=1
snapshots=tar.gz tar.bz2 zip
root-desc=All public git repositories by Adyxax
#root-readme=/var/www/htdocs/about.html
root-title=Adyxax's git repositories
virtual-root=/
scan-path=/home/git/repositories
```
## fcgiwrap
fcgiwrap is a necessary interface for nginx to call cgit. It is entirely configured from `/etc/rc.conf`, you just need to add:
```cfg
fcgiwrap_enable="YES"
fcgiwrap_profiles="git"
fcgiwrap_git_socket="unix:/var/run/fcgiwrap/git.socket"
fcgiwrap_git_user="git"
fcgiwrap_git_group="git"
fcgiwrap_git_socket_owner="www"
fcgiwrap_git_socket_group="www"
```
This ensures the cgit processes run as the `git` user, while nginx running as the `www` user can connect to it.
## nginx
I presume nginx is already setup, here is the snippet of configuration needed to serve cgit with fcgiwrap:
```cfg
server {
listen 80;
listen [::]:80;
server_name git.adyxax.org;
location / {
return 308 https://$server_name$request_uri;
}
}
server {
listen 443 ssl;
listen [::]:443 ssl;
server_name git.adyxax.org;
location /adyxax {
try_files $uri @cgit-adyxax;
}
location @cgit-adyxax {
include fastcgi_params;
fastcgi_param CGIT_CONFIG /usr/local/etc/cgitrc-adyxax;
fastcgi_param SCRIPT_FILENAME /usr/local/www/cgit/cgit.cgi;
fastcgi_param PATH_INFO $uri;
fastcgi_param QUERY_STRING $args;
fastcgi_param HTTP_HOST $server_name;
fastcgi_pass unix:/var/run/fcgiwrap/git.socket;
}
ssl_certificate /usr/local/etc/adyxax.org.fullchain;
ssl_certificate_key /usr/local/etc/adyxax.org.key;
}
```

View file

@ -0,0 +1,69 @@
---
title: "gitolite"
description: Installation notes of gitolite
---
## Introduction
This article details how I installed and configured gitolite on FreeBSD, with ansible.
## Installation
gitolite can be bootstrapped with the following :
```yaml
- name: Install common freebsd packages
package:
name:
- gitolite
```
I create a system group and a system user:
```yaml
- name: Create git group on server
group:
name: git
system: yes
- name: Create git user on server
user:
name: git
group: git
shell: /bin/sh
home: /srv/git
createhome: yes
system: yes
password: '*'
```
Repositories will be kept under `/srv/git`. This password is a special value for the user module that specifies a disabled password.
## Initial setup
For this step you need to upload your public ssh key to the server and put it in the `/srv/git` directory. The following will then create a `gitolite-admin` repository and configure your public ssh key so that you can access it:
```sh
su - git
gitolite setup -pk id_ed25519.pub
```
You should then be able to clone the `gitolite-admin` repository on your workstation:
```sh
git clone git@git.adyxax.org:gitolite-admin
```
## Configuration
In order to customize the cgit frontend, I needed to allow some git configuration keys in `/srv/git/.gitolite.rc`. I manage the whole file with ansible, but here is the relevant line near the top of the file:
```perl
GIT_CONFIG_KEYS => 'cgit.desc cgit.extra-head-content cgit.homepage cgit.hide cgit.ignore cgit.owner cgit.section',
```
These keys allow me to specify repositories like this:
```perl
repo adyxax/bareos-zabbix-check
RW+ = adyxax
config cgit.desc = A Zabbix check for bareos backups
config cgit.extra-head-content=<meta name="go-import" content="git.adyxax.org/adyxax/bareos-zabbix-check git https://git.adyxax.org/adyxax/bareos-zabbix-check">
config cgit.owner = Julien Dessaux
config cgit.section = Active
```
The `cgit.extra-head-content` is vital for `go get` and `go install` to work properly and took me some google-fu to figure out.

View file

@ -1,96 +0,0 @@
---
title: "Installation"
description: Installation notes of gitea on podman
---
## Introduction
Please refer to [the official website](https://docs.gitea.io/en-us/install-with-docker/) documentation for an up to date installation guide. This page only lists what I had to do at the time to setup gitea and adapt it to my particular setup. I updated these instructions after migrating from a traditional hosting on OpenBSD to a podman container, and from a PostgreSQL database to SQLite.
## Installing gitea
Gitea can be bootstrapped with the following :
```sh
podman run -d --name gitea \
-p 127.0.0.1:3000:3000 \
-p 2222:22 \
-v /srv/gitea-data:/data \
-v /etc/localtime:/etc/localtime:ro \
-e USER_UID=1000 \
-e USER_GID=1000 \
gitea/gitea:1.15.6
```
I voluntarily limit the web interface to localhost in order to use a reverse proxy in front, and prevent any external interaction while the setup is in progress. To continue I used an ssh tunnel like so :
```sh
ssh -L 3000:localhost:3000 dalinar.adyxax.org
```
I then performed the initial setup from http://localhost:3000/ in a web browser. Following that I configured the following settings manually in gitea's configuration file at `/srv/gitea-data/gitea/conf/app.ini`:
```conf
[server]
LANDING_PAGE = explore
[other]
SHOW_FOOTER_BRANDING = false
SHOW_FOOTER_VERSION = false
SHOW_FOOTER_TEMPLATE_LOAD_TIME = false
```
The container needs to be restarted following this :
```sh
podman restart gitea
```
## nginx reverse proxy
dalinar is an Alpine linux, nginx is simply installed with :
```sh
apk add ninx
```
The configuration in `/etc/nginx/http.d/git.conf` looks like :
```conf
server {
listen 80;
listen [::]:80;
server_name git.adyxax.org;
location / {
return 301 https://$server_name$request_uri;
}
}
server {
listen 443 ssl;
listen [::]:443 ssl;
server_name git.adyxax.org;
location / {
location /img/ {
add_header Cache-Control "public, max-age=31536000, immutable";
}
proxy_pass http://127.0.0.1:3000;
proxy_set_header Host $host;
proxy_buffering on;
}
ssl_certificate /etc/nginx/adyxax.org-fullchain.cer;
ssl_certificate_key /etc/nginx/adyxax.org.key;
}
```
```sh
/etc/init.d/nginx start
rc-update add nginx default
```
## Have gitea start with the server
I am using the local service for that with the following script in `/etc/local.d/gitea.start` :
```sh
#!/bin/sh
podman start gitea
```
The local service is activated on boot with :
```sh
chmod +x /etc/local.d/gitea.start
rc-update add local default
```