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.