Podman - Setup Gitea
Running your own Git server for your project, private work or your company is very common. With Podman and Gitea, you can get things going in minutes. In this guide, I will demonstrate how you can set up your own Gitea instance on Podman, including auto-start and auto-updates.
Podman is a container software, very similar to Docker. Both can run containers, build images and much more on a single host. This is perfect for a simple home server or private VPS, where you want to play with some software and put each software in its own sandbox.
We already published a bunch of articles and guides about Podman in the past. You may want to have a look at them first, if you never used Podman before.
Gitea is a quite simple, yet powerful software to host your own Git server, similar to GitHub, GitLab or Bitbucket. It provides many features like issue handling, a wiki, organizations and permissions for different users. The footprint is also very small, and it does not have many dependencies.
Please have a look here and check the comparison to similar software and here to get a better understanding of Gitea itself.
The story, we want to handle, will be most likely something like this:
"As a developer, I need a repository with a graphical Web UI, so I can easily store, share, merge, document and publish my code."
Some acceptance criteria and requirements can be defined, too:
- Web UI via http/https
- Git SSH must work
- container setup
- Fedora as host OS
- Gitea must auto-update
- Containers must start, if the server restarts
- solution to persist data
This should pretty much sum up, what we want to do.
The prerequisites for Gitea and our setup are pretty simple. We just need to have an additional look here and can write down:
- CPU: 2 cores
- RAM: 1 GB
- HDD: 20 GB
- OS: Fedora 34
Even a Raspberry Pi is sufficient. If you consider using a Raspberry Pi, please have a look here to install Fedora on it.
It is best practice to run every deployment in a dedicated container network. This will ensure, that every container can reach only the related containers. As explained in the "Podman - Networking" articles, this is as easy as:
$ sudo podman network create gitea-net
Afterwards, we can start defining the containers.
Automatic updating of containers is pretty easy. I have explained the details in this article. For now, we only need to enable the timer.
# Enable the auto update timer $ sudo systemctl enable --now podman-auto-update.timer
Gitea requires some kind of database to store meta-data. For this tutorial, we will use MariaDB. You can also play with PostgreSQL, if you want.
Since we want to have MariaDB started on reboot and updated on a regular basis, we will need a systemd service file. The below example provides everything you need. More details about Podman and how you can handle containers with systemd can be found here.
We just need to create a new systemd unit file for our container.
# Create mariadb systemd unit $ sudo touch /etc/systemd/system/container-gitea-db.service
We need to edit the file with the editor of our choice and fill in the below content. Please also adjust the DB password to your liking.
The data will be persisted in the named volume gitea-db-volume, which is located in /var/lib/containers/storage/volumes/.
Starting and enabling this service will automatically download the correct image and enable auto-update features for it.
# Re-read systemd service file $ sudo systemctl daemon-reload # Enable and start the service $ sudo systemctl enable --now container-gitea-db # Check the service $ sudo systemctl status container-gitea-db # Check the container $ sudo podman ps
Now that we are having a database, we can deploy a Gitea container, too. Gitea offers a rootless image and the "regular" image, which runs Gitea in the container with root privileges. I am opting for the rootless image here, because I can. ;)
We just need to create another file for Gitea.
# Create gitea systemd unit $ sudo touch /etc/systemd/system/container-gitea-app.service
And again fill in some content there. You also need to use the same DB password and user as you used in the above MariaDB container.
The data will be persisted in the named volumes gitea-config-volume and gitea-data-volume, which are located in /var/lib/containers/storage/volumes/.
Enabling and starting the container service works exactly the same as for the MariaDB container.
# Re-read systemd service file $ sudo systemctl daemon-reload # Enable and start the service $ sudo systemctl enable --now container-gitea-app # Check the service $ sudo systemctl status container-gitea-app # Check the container $ sudo podman ps
Finalizing / Testing
After some seconds, you should be able to connect to your new Gitea instance with a browser. Just point it to http://IP-ADDRESS:3000, and you are good to go to review the installer.
You can also provide an admin user before hitting the "Install Gitea" button.
Since we have started the podman-auto-update.timer and provided the container labels
--label "io.containers.autoupdate=registry" \, Podman will take care of updating the images. You can read more about Auto Updates and how it works in this article.
Docs & Links
I have already addressed many of the needed background on my own, but there is also plenty of documentation for Podman and Gitea.
This was only the first guide to tackle deployments in containers for a specific software. In the future we will have a look at more interesting setups for load balancers, let's encrypt and much more.
Getting started with some repository was logical for me, so you can follow more tutorials without the need of GitHub, Bitbucket or some other hosted solutions.