Skip to main content

Installing Gitea

Gitea is a self-hosted git server.

This page has brief instructions and problem solving for setting up a local Git server using Gitea, running in a Docker container on Ubuntu linux.

This page uses a docker container called testgitea running on HTTP port 8081 and SSH port 2221. These values will vary for every installation.

Installing git

Gitea uses git and git-lfs, so install those first:

sudo apt install git
sudo apt install git-lfs

Installing docker-compose

This is based on instructions here

Installation is on an existing ZFS pool at /mnt/zfspool

# make a directory for gitea
cd /mnt/zfspool/gitea

# install docker
sudo apt install gnome-terminal
sudo apt-get update
curl -O https://desktop.docker.com/linux/main/amd64/docker-desktop-amd64.deb?utm_source=docker&utm_medium=webreferral&utm_campaign=docs-driven-download-linux-amd64
sudo apt install -y ca-certificates curl gnupg lsb-release
sudo mkdir -p /etc/apt/keyrings
curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gpg --dearmor -o /etc/apt/keyrings/docker.gpg
echo "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.gpg] https://download.docker.com/linux/ubuntu $(lsb_release -cs) stable" | sudo tee /etc/apt/sources.list.d/docker.list > /dev/null
sudo apt update -y
sudo apt-get install ./docker-desktop-amd64.deb
sudo apt install docker.io

Security

Add your host user to the docker group on the host machine

sudo usermod -aG docker $USER
newgrp docker

Docker service

Configure docker to start when the system starts

systemctl --user start docker-desktop
systemctl --user enable docker-desktop
sudo systemctl start docker
sudo systemctl daemon-reload

Docker volumes

Gitea runs in a docker container. A docker volume is a directory external to the docker container which, if required, can be shared across multiple containers. The gitea docker container mounts the docker volume and creates its file system in that volume.

We will be running gitea using a docker volume. This means if we every require it we can back up the volume without using the container.

We link the default directory in which docker volumes get created (/var/lib/docker/volumes) to a directory on the ZFS pool (/mnt/zfspool/docker_volumes) by doing this:

sudo systemctl stop docker
sudo mv /var/lib/docker/volumes /mnt/zfspool/docker_volumes
sudo ln -s /mnt/zfspool/docker_volumes /var/lib/docker/volumes
sudo systemctl start docker

Then we make a named volume for gitea data. The volume name is testgiteadata

docker volume create testgiteadata

The actual directory for this volume can be found at /mnt/zfspool/docker_volumes/testgiteadata

Preparing Gitea

This is based on the 'Basics' section of https://docs.gitea.com/next/installation/install-with-docker

Making a new docker container which will run gitea:

cd /mnt/zfspool/gitea

Paste the lines below into a file called docker-compose.yml:

networks:
gitea:
external: false

volumes:
testgiteadata:
external: true

services:
server:
image: docker.gitea.com/gitea:latest
container_name: gitea
environment:
- USER_UID=1000
- USER_GID=1000
restart: always
networks:
- gitea
volumes:
- testgiteadata:/data
- /etc/timezone:/etc/timezone:ro
- /etc/localtime:/etc/localtime:ro
ports:
- "8081:3000"
- "2221:2221"

Key settings:

  • the docker volume is specified in this section:
volumes:  
testgiteadata:

and here:

services:
server:
volumes:
- testgiteadata:/data

The name specified in both places needs to correspond to the name used in the docker volume create command above.

  • the image setting is

image: docker.gitea.com/gitea:latest

which will use the latest stable version, whereas the gitea installation example uses :nightly which is probably not what you want.

Problems with port numbers

The last lines in docker-compose.yml define which ports will used for HTTP access and SSH. It looks as though you can map the SSH port by setting it to ""2221:22", so you connect to 2221 and get forwarded to 22 in the container. This does not work like that. Attempting to connect to 2221 by doing this:

git clone git@tower:2221/jfarrow/TestRepo.git

will connect to port 22 on the host, not on the gitea docker container. You get this response:

Cloning into 'TestRepo'...
git@tower's password:

You can verify this is not from the container by using docker compose down to shut down the container - you still get the same response.

Also, if you set the SSH port in docker-compose.yml to "2221:22" and create a repository the SSH connection string will appear like this:

git@tower:jfarrow/TestRepo.git

which is incorrect (and does not work) because it does not contain the port number.

The fix for these problems is to make the internal port number not be 22, for example setting the port string in docker-compose.yml to "2221:2221". If you do this gitea will give you repository connection strings which contain the port number, such as ssh://git@tower:2221/jfarrow/TestRepo.git

Starting gitea

cd /mnt/zfspool/gitea 
docker compose up -d

To run the docker container in the foreground, which shows useful logging information, use docker compose up, and to shut it down use control-c.

To run the docker container in the background, use docker compose up -d, and to shut it down use docker compose down.

Once it is started with docker compose up -d and is running in the background you can use the docker ps command to list docker processes:

docker ps

This shows useful information including:

  • the docker id

ddce3fca7e43

  • the mapping of ports from the host machine to inside the docker container: run

0.0.0.0:2221->22/tcp, [::]:2221->22/tcp, 0.0.0.0:8080->3000/tcp, [::]:8080->3000/tcp

Initializing gitea

Once gitea is running you can point a browser to http://SERVERNAME:8081 to access the gitea web interface:

Change the SSH Server Port to whatever value you specified in the ports section of the docker-compose.yml file, i.e. in this example I changed it to 2221.

Press the Install Gitea button to install gitea.

Registering a user

You will be prompted to register a user. For simplicity make the username the same as your host login name. Fill in the details and press Register Account:

You should see the main gitea screen:

Making a repository

Gitea behaves very like github.com. To create a new repository, press the + button and select New Repository:

Give it a name and maybe change the default branch and the press the Create Repository button. This screen appears, press the SSH tab to show the repository connection string which should contain the port number like ssh://git@tower:2221/jfarrow/TestRepo.git

Setting up SSH in the container

The SSH server running in the container is configured using a file called app.ini. This is present on the docker volume, so use sudo to access it:

sudo bash
nano ../docker_volumes/testgiteadata/_data/gitea/conf/app.ini

change the line
> SSH_LISTEN_PORT = 22
to match the port specified in docker-compose.yml such as
> SSH_LISTEN_PORT = 2222

add the line
START_SSH_SERVER = true

save the file and exit sudo

Restart the gitea docker instance:

docker compose down
docker compose up -d

Note that docker compose restart is not enough.

Testing SSH on Windows and Linux

You can use the command to see what keys are being sent.

ssh -vT git@tower -p 2221

If you see this:

Are you sure you want to continue connecting (yes/no/[fingerprint])?

type yes

If you see this:

debug1: Connecting to tower [10.0.0.10] port 2221.
debug1: connect to address 10.0.0.10 port 2221: Connection refused
ssh: connect to host tower port 2221: Connection refused

Mostly likely the SSH server is not running on port 2221 or is not running at all; check that the app.ini file contains START_SSH_SERVER = true and the other settings as specified above and that it has been restarted as described above.

Cloning the repository to Windows

Setting up SSH public keys

You Windows SSH keys are in c:\users\USERNAME\.ssh

If you don't have an ssh key see here for instructions on generating one.

To give gitea your public key:

  • Open a windows command line window
  • Find the public key file such as c:\users\USERNAME\.ssh\id_ed25519.pub and open it in a text editor
  • Copy the contents
  • Open the gitea UI in a web browser, choose Setting in the dropdown next to your username:

  • Choose the SSH/GPG Keys on the left-hand side, click Add Key on the top right, then enter a key name and the contents of the public key file such as id_ed25519.pub

  • click the middle Add Key button to save the key.

Cloning

Clone the repository with a command like this:

git clone ssh://git@tower:2221/jfarrow/TestRepo.git

You should see something like:

Cloning into 'TestRepo'...
warning: You appear to have cloned an empty repository.

Cloning the repository to Linux

Setting up SSH public keys

You linux SSH keys are in ~/.ssh

If you don't have an ssh key see here for instructions on generating one.

To give gitea your public key:

  • Open a command line such as bash
  • Find the public key file such as id_ed25519.pub and open it in a text editor
  • Copy the contents
  • Open the gitea UI in a web browser, choose Setting in the dropdown next to your username:

  • Choose the SSH/GPG Keys on the left-hand side, click Add Key on the top right, then enter a key name and the contents of the public key file such as id_ed25519.pub

  • click the middle Add Key button to save the key.

Cloning

Clone the repository with a command like this:

git clone ssh://git@tower:2221/jfarrow/TestRepo.git

You should see something like:

Cloning into 'TestRepo'...
warning: You appear to have cloned an empty repository.

Setting up git-lfs

Once you have cloned the repository execute these commands so setup lfs:

git lfs track *.uasset
git lfs track *.umap
git add .gitattributes
git commit -m "setup lfs" .
git push

This ends the section on getting gitea up and running.

SSH notes

Things I learned getting gitea to work with SSH.

Making sure SSH is really running on Linux

sudo systemctl enable --now ssh

Adding a git user if needed on Linux

sudo adduser --system --group --shell /bin/bash git

Connection choices

When a Windows or Linux machine attempts to connect to the gitea instance it chooses a key from the ones in the .ssh directory. If you only have one key this won't be a problem, but if you have multiple keys it might send one which is not the one you gave gitea the public key for.

If the wrong key is being sent, or you were using a key and then started using a different key, you might see a message about a man-in-the-middle attack.

What key is sent to a server is remembered in the file

c:\users\USERNAME\.ssh\known_hosts.txt or ~/.ssh/known_hosts

For example, if I connected to the host called "tower" on port 2221 there will be a line in the file like this:

[tower]:2221 ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIHSRDVujka5tV6ciMIwBovZlfn6hBSltltorhx0L8+7A

To reset that connection delete the line from the known_hosts or known_hosts.txt file.

Looking at logs

Use:

docker logs [containername] | grep ssh

Running netstat inside the container

Use:

docker exec -it testgitea sh
netstat -tlnp | grep 2222

Resetting docker

If you are not using docker for anything else you can delete the containers, volumes and cached images by following the instructions at https://thelinuxcode.com/how-do-clean-restart-docker-instance/

Resetting gitea

If you don't have anything important running yet you can delete the docker volume that the gitea docker container uses and recreate it. Once you restart it, it will be back at the Initial Configuration stage.

To do this identify the docker volume name (we used testgiteadata in the example above) and delete it by deleting the file, so we need to know where the docker volumes are located:

docker compose down
sudo rm /mnt/zfspool/docker_volumes/testgiteadata
docker volume create testgiteadata
docker compose up -d

Gitea documentation

Here is a very long page on SSH container passthrough.