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).


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.; 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 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. 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": [
  3. On any Windows workstation that needs to access the private CA,

    1. Install the private CA into the system certificate store

      1. Windows 10 install certificate dialogue
        Double-click on, select ‘Install certificate’ and click ‘OK’
      2. Select ‘Local Machine’ in install certificate wizard
        For ‘Store Location’ select ‘Local Machine’ and click ‘Next’. You may be prompted for your administrative credentials.
      3. Selection of location to install certificate in the install certificate wizard
        Select ‘Place all certificates in the following store’ and click ‘Browse…’
      4. Selection of which system-wide store to use in the install certificate wizard
        Select ‘Trusted Root Certification Authorities’ and click ‘OK’
      5. Confirmation page for install certificate wizard
        Confirm the details presented and click ‘Finish’
    2. For making the CA available for recent Firefox system-wide:

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

      2. Copy 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": [

      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:,, and

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

  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 --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-* 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 and 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* root.crt /srv/gitea/
  2. sudo chown gitea:gitea /srv/gitea/* /srv/gitea/root.crt
  3. You can now remove the client cert and key from your admin user account: rm*
  4. sudo -u gitea -sH
  5. cd ~
  6. chmod 700 .
  7. mkdir .postgresql
  8. chmod 700 .postgresql
  9. mv* root.crt .postgresql
  10. cd .postgresql
  11. mv postgresql.crt
  12. mv postgresql.key
  13. cp root.crt /usr/local/share/ca-certificates/
  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

  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 --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

psql "postgres://"

(%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.


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 /etc/gitea/
      sudo cp /etc/gitea/
      sudo -sH
      cd /etc/gitea
      chown root:gitea
      chown root:gitea
      chmod 640
      chmod 644
  4. Add a config such as (substituting the secrets above, and the database password):

    APP_NAME = Example Gitea
    RUN_USER = gitea
    RUN_MODE = prod
    INSTALL_LOCK       = true
    DB_TYPE  = postgres
    HOST     =
    NAME     = giteadb
    USER     =
    SSL_MODE = verify-full
    CHARSET  = utf8
    LOG_SQL  = false
    ROOT = /srv/gitea-data/repositories
    SSH_DOMAIN       =
    DOMAIN           =
    HTTP_PORT        = 443
    PROTOCOL         = https
    ROOT_URL         =
    DISABLE_SSH      = false
    SSH_PORT         = 22
    LFS_CONTENT_PATH = /srv/gitea-data/lfs
    OFFLINE_MODE     = true
    CERT_FILE        = /srv/gitea-config/
    KEY_FILE         = /srv/gitea-config/
    ENABLED = false
    REGISTER_EMAIL_CONFIRM            = false
    ENABLE_NOTIFY_MAIL                = false
    DISABLE_REGISTRATION              = true
    ENABLE_CAPTCHA                    = false
    REQUIRE_SIGNIN_VIEW               = false
    NO_REPLY_ADDRESS                  =
    PROVIDER = db
    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

If you omit PostgreSQL and use SQLite3

Replace the [database] section above with:

DB_TYPE  = sqlite3
NAME     = gitea
LOG_SQL  = false

Add Fail2Ban configs (optional)

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

    # gitea.conf
    failregex =  .*(Failed authentication attempt|invalid credentials|Attempted access of unknown user).* from <HOST>
    ignoreregex =
  2. Create /etc/fail2ban/jail.d/gitea.conf

    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

Description=Gitea (Git with a cup of tea)

# Modify these two values and uncomment them if you have
# repos with lots of files and get an HTTP error 500 because
# of that
# 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)
ExecStart=/usr/local/bin/gitea web --config /etc/gitea/app.ini
Environment=USER=gitea HOME=/srv/gitea/home GITEA_WORK_DIR=/srv/gitea/data


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

    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
    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 --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
  4. exit
  5. Log back in as admin using the new port ssh -p 22172

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 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 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 --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 --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