Gitea Pi

This article describes setting up a Raspberry Pi Model B+ as a private Gitea (lightweight Git hosting) server.

Preface

In combination with the Raspberry Pi OS for a server and Using XCA to create private SSL certificates and PiSQL articles, this article describes setting up a Raspberry Pi Model B+ as a private Gitea (lightweight Git hosting) server. It assumes a separate PostgreSQL server is available on the network and does not use external storage (just a reasonably large SD card). Finally, this is intended only for internal use and is not expected to be publicly facing.

A caveat

This will work well for ordinary repositories, but for very large repositories like the Linux Kernel (>1 GB) the Pi is simply not powerful enough.

This is a limitation of Git rather than Gitea (even bare git operations on kernel repos do not fare well on a Pi).

Preliminaries

Prepare the server and certificates

1. Setup a Pi following the Raspberry Pi OS for a server article. For this server the author skipped the external storage related steps and packages as he is operating the server entirely from a large and fast enough SD card.

2. Create internal SSL CA and server certificate and key by following the Using XCA to create private SSL certificates article. (As with the PiSQL article, we require server certificates for the server (e.g. gitea.example.com); this time we do not need to generate a CA (Certificate Authority) but can use the existing one).

3. We also need to generate a ‘client’ certificate for this host, which uses the same procedure, except that instead of selecting the ‘[default] TLS_server’ template, we select the ‘[default] TLS_client’ template. For the client certificate I recommend using a name such gitea@gitea.example.com for the CN — you can still add the server DNS name as Subject Alternative Names (x509v3 SAN).

   Note that on the client certificate at one SAN and/or the CN must be the username gitea uses to connect to the database.

4. Increase the available amount of swap:

   1. sudo dd if=/dev/zero of=/var/swap2.img bs=1M count=1024

   2. sudo chmod 600 /var/swap2.img

   3. sudo mkswap /var/swap2.img

   4. sudoedit /etc/fstab and add a line such as:

      /var/swap2.img none swap defaults 0 0

   5. Enable the swap: sudo swapon -a

   6. Verify it is enabled: cat /proc/swaps

Prepare your clients to use SSL to the server

Because we are using a private CA your desktop and other Git clients need to be told to trust the private CA.

1. On any Debian/Ubuntu workstation that needs to access the private CA, copy the private CA certificate (e.g. ca-private.example.com) to /usr/local/share/ca-certificates and execute update-ca-certificates

2. Also on any Debian/Ubuntu workstation for which Firefox needs to access the server:

   mkdir -p /etc/firefox/policies
   sudoedit /etc/firefox/policies/policies.json

   In policies.json add:

   {
     "policies": {
       "Certificates": {
         "Install": [
           "/usr/local/share/ca-certificates/ca-private.example.com.crt"
         ]
       }
     }
   }

3. On any Windows workstation that needs to access the private CA,

   1. Install the private CA into the system certificate store

      1. 

      2. 

      3. 

      4. 

      5. 

   2. For making the CA available for recent Firefox system-wide:

      1. Create a directory called C:\\ProgramData\\FirefoxCertificates

      2. Copy ca-private.example.com.crt to C:\\ProgramData\\FirefoxCertificates

      3. Create a directory called distribution in C:\\Program Files\\Mozilla Firefox, and in the distribution directory add a file called policies.json containing:

         {
           "policies": {
             "Certificates": {
               "Install": [
                 "C:\\ProgramData\\FirefoxCertificates\\ca-private.example.com.crt"
               ]
             }
           }
         }

      See Also Mozilla’s GitHub repository for policy templates

Obtain, verify and ‘install’ Gitea

From the Gitea download area, select the current release and linux-arm-6 binaries. At the present time we want the following files: https://dl.gitea.io/gitea/1.14.3/gitea-1.14.3-linux-arm-6.xz, https://dl.gitea.io/gitea/1.14.3/gitea-1.14.3-linux-arm-6.xz.asc, and https://dl.gitea.io/gitea/1.14.3/gitea-1.14.3-linux-arm-6.xz.sha256.

1. You could for example use the following trio of commands:

   wget https://dl.gitea.io/gitea/1.14.3/gitea-1.14.3-linux-arm-6.xz
   wget https://dl.gitea.io/gitea/1.14.3/gitea-1.14.3-linux-arm-6.xz.asc
   wget https://dl.gitea.io/gitea/1.14.3/gitea-1.14.3-linux-arm-6.xz.sha256

2. Now verify the correctness of the download:

3. Execute

   sha256sum --ignore-missing -c gitea-1.14.3-linux-arm-6.xz.sha256

4. And that it it matches the version intended by the authors (signed by them)

   gpg --keyserver keyserver.ubuntu.com --recv-keys CC64B1DB67ABBEECAB24B6455FC346329753F4B0
   gpg --verify gitea-1.14.3-linux-arm-6.xz.asc gitea-1.14.3-linux-arm-6.xz

   As long as the report is of a good signature, you can ignore:

   gpg: WARNING: This key is not certified with a trusted signature!
   gpg:          There is no indication that the signature belongs to the owner.

   as the so-called Web of Trust which would resolve that message has not come to exist.

5. Now decompress the gitea binary:

   xz -d gitea-1.14.3-linux-arm-6.xz

6. And copy it to where you will use it and make it executable

   sudo cp gitea-1.14.3-linux-arm-6 /usr/local/bin/gitea
   sudo chmod 755 /usr/local/bin/gitea

7. You can now remove the gitea-1.1.4.3-linux-arm-6* files.

Prepare the environment

Create a Gitea user

sudo addgroup --system gitea
sudo adduser  --system --home /srv/gitea/home --shell /bin/bash --gecos "" --ingroup gitea --disabled-password --disabled-login gitea

Add the PostgreSQL client (optional)

We use this to create and prepare the database in a way that verifies that connections will work for the gitea process (i.e. when going live).

sudo apt install -y postgresql-client

Copy the SSL client keys to the Gitea user for PostgreSQL use

Assuming you have copied your client gitea@gitea.example.com.crt and gitea@gitea.example.com.pem to your admin user, as well as the ca certificate (which we will call ‘root.crt’), and that you are currently in your admin user account:

1. sudo cp gitea@gitea.example.com* root.crt /srv/gitea/
2. sudo chown gitea:gitea /srv/gitea/gitea@gitea.example.com* /srv/gitea/root.crt
3. You can now remove the client cert and key from your admin user account: rm gitea@gitea.example.com*
4. sudo -u gitea -sH
5. cd ~
6. chmod 700 .
7. mkdir .postgresql
8. chmod 700 .postgresql
9. mv gitea@gitea.example.com* root.crt .postgresql
10. cd .postgresql
11. mv gitea@gitea.example.com.crt postgresql.crt
12. mv gitea@gitea.example.com.pem postgresql.key
13. cp root.crt /usr/local/share/ca-certificates/ca-private.gitea.internal.com
14. update-ca-certificates
15. cd ..

NB Keep this session open, we’ll come back to it

On the Database server, create user and database for Gitea

1. Login as your admin user to your database server

2. sudo su - postgres

3. createuser -P gitea@gitea.example.com

4. Enter a new strong password when prompted (you will need to enter it twice).

5. For C.UTF-8 below substitute the appropriate UTF-8 locale:

   createdb -O gitea@gitea.example.com --encoding UTF8 --locale C.UTF-8 --template template0 giteadb

6. exit

7. exit

See also: Gitea documentation on setting up PostgreSQL for Gitea

Back on the Gitea server, test DB connection

In the session as user gitea from above and assuming your db server is named pisql.example.com:

psql "postgres://gitea%40gitea.example.com@pisql.example.com/giteadb?sslmode=verify-full"

(%40 is the URL encoding of the ‘@’ symbol in the username)

Enter the database user’s password when prompted, and you should get a standard ‘psql’ prompt, such as:

psql (11.12 (Raspbian 11.12-0+deb10u1), server 11.11 (Raspbian 11.11-0+deb10u1))
SSL connection (protocol: TLSv1.3, cipher: TLS_AES_256_GCM_SHA384, bits: 256, compression: off)
Type "help" for help.

giteadb=>

Enter \l to see the list of databases, and \q to quit.

Back to admin, create the needed directories

exit the gitea user shell so that you are back into your admin user shell.

sudo mkdir -p /srv/gitea/data/{custom,data,log,lfs,repositories}
sudo mkdir -p /etc/gitea
sudo chown -R gitea:gitea /srv/gitea/data /etc/gitea
sudo chmod 750 /srv/gitea/data /etc/gitea
sudo chown root /etc/gitea
sudo touch /etc/gitea/app.ini
sudo chmod 640 /etc/gitea/app.ini
sudo chown root:gitea /etc/gitea/app.ini

Configure Gitea

Create the config file

1. Create and record the secrets you will need:

   1. gitea generate secret SECRET_KEY
   2. gitea generate secret INTERNAL_TOKEN
   3. gitea generate secret LFS_JWT_SECRET

2. sudoedit /srv/gitea-config/app.ini

3. Copy your server certificate and key to /etc/gitea:

   1. Assuming they are in your admin user’s home directory:

      sudo cp gitea.example.com.crt /etc/gitea/
      sudo cp gitea.example.com.key /etc/gitea/
      sudo -sH
      cd /etc/gitea
      chown root:gitea gitea.example.com.crt
      chown root:gitea gitea.example.com.key
      chmod 640 gitea.example.com.key
      chmod 644 gitea.example.com.crt

4. Add a config such as (substituting the secrets above, and the database password):

   APP_NAME = Example Gitea
   RUN_USER = gitea
   RUN_MODE = prod
   
   [security]
   INSTALL_LOCK       = true
   PASSWORD_HASH_ALGO = pbkdf2
   SECRET_KEY         = XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
   INTERNAL_TOKEN     = XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
   
   [database]
   DB_TYPE  = postgres
   HOST     = pisql.example.com:5432
   NAME     = giteadb
   USER     = gitea@gitea.example.com
   PASSWD   = XXXXXXXXXXXXXXXXXXXXXXX ; USE `XXXXXXXXXXXXXXX` if special characters appear in PASSWD
   SSL_MODE = verify-full
   CHARSET  = utf8
   LOG_SQL  = false
   
   [repository]
   ROOT = /srv/gitea-data/repositories
   DEFAULT_PUSH_CREATE_PRIVATE = false
   ENABLE_PUSH_CREATE_ORG = false
   ENABLE_PUSH_CREATE_USER = false
   DEFAULT_BRANCH = main
   
   [server]
   SSH_DOMAIN       = gitea.example.com
   DOMAIN           = gitea.example.com
   REDIRECT_OTHER_PORT = true
   PORT_TO_REDIRECT = 80
   HTTP_PORT        = 443
   PROTOCOL         = https
   ROOT_URL         = https://gitea.example.com/
   DISABLE_SSH      = false
   SSH_PORT         = 22
   LFS_START_SERVER = true
   LFS_CONTENT_PATH = /srv/gitea-data/lfs
   LFS_JWT_SECRET   = XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
   OFFLINE_MODE     = true
   START_SSH_SERVER = true
   CERT_FILE        = /srv/gitea-config/gitea.example.com.crt
   KEY_FILE         = /srv/gitea-config/gitea.example.com.key
   
   [mailer]
   ENABLED = false
   
   [service]
   REGISTER_EMAIL_CONFIRM            = false
   ENABLE_NOTIFY_MAIL                = false
   DISABLE_REGISTRATION              = true
   ALLOW_ONLY_EXTERNAL_REGISTRATION  = false
   ENABLE_CAPTCHA                    = false
   REQUIRE_SIGNIN_VIEW               = false
   DEFAULT_KEEP_EMAIL_PRIVATE        = false
   DEFAULT_ALLOW_CREATE_ORGANIZATION = false
   DEFAULT_ENABLE_TIMETRACKING       = false
   NO_REPLY_ADDRESS                  = noreply.example.com
   
   [oauth2]
   JWT_SECRET = XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
   
   [session]
   PROVIDER = db
   
   [indexer]
   ISSUE_INDEXER_TYPE = db
   
   [log]
   MODE                 = console
   LEVEL                = info
   ROOT_PATH            = /srv/gitea-data/log
   COLORIZE             = false
   # Router is quite noisy and not usually needed on a private server
   # Log to a file instead of journal (via console)
   ROUTER               = file
   
   DISABLE_GRAVATAR        = true
   ENABLE_FEDERATED_AVATAR = false
   
   [openid]
   ENABLE_OPENID_SIGNIN = false
   ENABLE_OPENID_SIGNUP = false
   
   [other]
   SHOW_FOOTER_VERSION = true
   SHOW_FOOTER_TEMPLATE_LOAD_TIME = true

If you omit PostgreSQL and use SQLite3

Replace the [database] section above with:

[database]
DB_TYPE  = sqlite3
NAME     = gitea
LOG_SQL  = false

Add Fail2Ban configs (optional)

1. Create /etc/fail2ban/filter.d/gitea.conf

   # gitea.conf
   [Definition]
   failregex =  .*(Failed authentication attempt|invalid credentials|Attempted access of unknown user).* from <HOST>
   ignoreregex =

2. Create /etc/fail2ban/jail.d/gitea.conf

   [gitea]
   enabled = true
   filter = gitea
   logpath = /var/log/syslog
   maxretry = 10
   findtime = 3600
   bantime = 900
   action = iptables-allports

3. Restart fail2ban

   sudo systemctl restart fail2ban

4. Verify fail2ban accepted your changes

   sudo systemctl status -l fail2ban

Add systemd service file

Modified from Gitea example systemd service file

Copy the following file to /etc/systemd/system/gitea.service

[Unit]
Description=Gitea (Git with a cup of tea)
After=syslog.target
After=network.target
###
#
#Requires=memcached.service
#Requires=redis.service
#

[Service]
# Modify these two values and uncomment them if you have
# repos with lots of files and get an HTTP error 500 because
# of that
###
#LimitMEMLOCK=infinity
#LimitNOFILE=65535
RestartSec=2s
Type=simple
User=gitea
Group=gitea
WorkingDirectory=/srv/gitea/data/
# If using Unix socket: tells systemd to create the /run/gitea folder, which will contain the gitea.sock file
# (manually creating /run/gitea doesn't work, because it would not persist across reboots)
#RuntimeDirectory=gitea
ExecStart=/usr/local/bin/gitea web --config /etc/gitea/app.ini
Restart=always
Environment=USER=gitea HOME=/srv/gitea/home GITEA_WORK_DIR=/srv/gitea/data
###
CapabilityBoundingSet=CAP_NET_BIND_SERVICE
AmbientCapabilities=CAP_NET_BIND_SERVICE
###

[Install]
WantedBy=multi-user.target

Create a wrapper script for CLI usage

1. Copy the following file to /usr/local/bin/gitea-wrapper

2. sudo chmod 755 /usr/local/bin/gitea-wrapper

   #!/bin/bash
   
   export USER=gitea
   export HOME=/srv/gitea/home
   export GITEA_WORK_DIR=/srv/gitea/data
   
   if [ "$(id -un)" != "gitea" ]; then
     echo "Must be run as user 'gitea'"
     exit 1
   fi
   
   exec /usr/local/bin/gitea --config /etc/gitea/app.ini "$@"

Initialize the database

sudo -u gitea gitea-wrapper migrate

Create an admin user

sudo -u gitea gitea-wrapper admin user create --username giteadmin --email you@example.com --admin --must-change-password --random-password --random-password-length 20

A random password will be generated for first login (at which time the user must change their password).

Configure firewall to allow alternate SSH port

sudo ufw allow in on eth0 proto tcp from any to any port 22172

Configure sshd to use alternate SSH port

We’re going to use port 22 for Git SSH, so make admin SSH a separate port.

1. sudoedit /etc/ssh/sshd_config
2. Add the line Port 22172 and save and exit.
3. sudo systemctl restart ssh — From now on, to administer the host we will need to tell SSH to use port 22172 (e.g. ssh -p 22172 pi@gitea.example.com).
4. exit
5. Log back in as admin using the new port ssh -p 22172 pi@gitea.example.com

Configure firewall to allow HTTP(S) connections

sudo ufw allow in on eth0 from any to any app "WWW Full"

Enable and launch Gitea

sudo systemctl enable --now gitea

Verify Gitea status

sudo systemctl status -l gitea

ss -ltn

It could be some minutes before Gitea is ready to accept connections, at which point ports 80, 443, and 22 will be accepting connections.

When Gitea is ready, login as admin user.

Gitea operational

You should now have a working Gitea Server

Configure backups

Assuming the use of restic as in the Pi OS for a server guide you could

1. sudo -u gitea -sH

2. cd ~

3. mkdir restic-files

4. cd restic-files

5. chmod 700 .

6. touch password-file

7. chmod 600 password-file

8. sensible-editor password-file

9. In the editor, add a strong password (e.g. 30 alphanumeric and special characters), then save and close (having a file with the password not ideal, but avoiding it is rather complicated, and out of scope for this article).

10. If using SFTP for backups, create a passwordless SSH keypair using:

    1. ssh-keygen -t rsa -f restic-gitea@piserver -C restic-gitea@piserver -N ''
    2. Copy the contents of restic-gitea@piserver.pub to your destination’s authorized_keys file.

11. Initialize your destination restic repository

12. Do an initial backup

    1. (assuming you have configured, ~/.ssh/config so that restic-gitea@backupserver.example.com uses the restic-gitea@piserver created above:

       /usr/local/bin/gitea-wrapper dump --custom-path /srv/gitea/data/custom --work-path /srv/gitea/data --type tar.gz -f - 2>/dev/null | restic -r sftp:restic-gitea@backupserver.example.com:/path/to/repo --password-file ~/restic-files/password-file backup --stdin --stdin-filename /gitea-dump.tar.gz

13. Now create a crontab entry to do this every four hours (you could of course adjust the frequency for your needs):

    1. crontab -e

    2. Add an entry such as:

       23  */4  *   *   *  /usr/local/bin/gitea-wrapper dump --custom-path /srv/gitea/data/custom --work-path /srv/gitea/data --type tar.gz -f - 2>/dev/null | restic -r sftp:restic-gitea@backupserver.example.com:/path/to/repo --quiet --password-file ~/restic-files/password-file backup --stdin --stdin-filename /gitea-dump.tar.gz 2>&1 | logger -t restic

    3. Save and exit the editor

14. exit