Podman

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.

Daniel Schier

Daniel Schier

— 7 min read
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

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

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.

Guide

Hint
The guide is tested on Fedora 34 with Podman 3.2.3.

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.

Prerequisites

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.

Network

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.

Auto-Updates

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

Database

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.

# container-gitea-db.service

[Unit]
Description=Podman container-gitea-db.service

Wants=network.target
After=network-online.target
RequiresMountsFor=%t/containers

[Service]
Environment=PODMAN_SYSTEMD_UNIT=%n
Restart=on-failure
TimeoutStopSec=70
PIDFile=%t/container-gitea-db.pid
Type=forking

ExecStartPre=/bin/rm -f %t/container-gitea-db.pid %t/container-gitea-db.ctr-id

ExecStart=/usr/bin/podman container run \
          --conmon-pidfile %t/container-gitea-db.pid \
          --cidfile %t/container-gitea-db.ctr-id \
          --cgroups=no-conmon \
          --replace \
          --detach \
          --tty \
          --env MARIADB_RANDOM_ROOT_PASSWORD=yes \
          --env MARIADB_DATABASE=gitea \
          --env MARIADB_USER=gitea \
          --env MARIADB_PASSWORD=password \
          --volume gitea-db-volume:/var/lib/mysql/:Z \
          --label "io.containers.autoupdate=registry" \
          --network gitea-net \
          --name gitea-db \
          docker.io/library/mariadb:10

ExecStop=/usr/bin/podman stop --ignore --cidfile %t/container-gitea-db.ctr-id -t 10

ExecStopPost=/usr/bin/podman rm --ignore -f --cidfile %t/container-gitea-db.ctr-id

[Install]
WantedBy=multi-user.target default.target
/etc/systemd/system/container-gitea-db.service

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

Gitea

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.

# container-gitea-app.service

[Unit]
Description=Podman container-gitea-app.service

Wants=network.target
After=network-online.target
RequiresMountsFor=/var/lib/containers/storage /var/run/containers/storage

[Service]
Environment=PODMAN_SYSTEMD_UNIT=%n
Restart=on-failure
TimeoutStopSec=70
PIDFile=%t/container-gitea-app.pid
Type=forking

ExecStartPre=/bin/rm -f %t/container-gitea-app.pid %t/container-gitea-app.ctr-id
ExecStart=/usr/bin/podman container run \
          --conmon-pidfile %t/container-gitea-app.pid \
          --cidfile %t/container-gitea-app.ctr-id \
          --cgroups=no-conmon \
          --replace \
          --detach \
          --tty \
          --env DB_TYPE=mysql \
          --env DB_HOST=gitea-db:3306 \
          --env DB_NAME=gitea \
          --env DB_USER=gitea \
          --env DB_PASSWD=password \
          --volume gitea-data-volume:/var/lib/gitea:Z \
          --volume gitea-config-volume:/etc/gitea:Z \
          --network gitea-net \
          --publish 2222:2222 \
          --publish 3000:3000 \
          --label "io.containers.autoupdate=registry" \
          --name gitea-app \
          docker.io/gitea/gitea:1-rootless

ExecStop=/usr/bin/podman container stop \
          --ignore \
          --cidfile %t/container-gitea-app.ctr-id \
          -t 10

ExecStopPost=/usr/bin/podman container rm \
          --ignore \
          -f \
          --cidfile %t/container-gitea-app.ctr-id

[Install]
WantedBy=multi-user.target default.target
/etc/systemd/system/container-gitea-app.service

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.

Auto-Updates

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.

I have already addressed many of the needed background on my own, but there is also plenty of documentation for Podman and Gitea.

Podman - systemd container management
Podman is a daemonless container management engine. But how do you start containers on boot and manage them properly, if there is no daemon? The simple answer is: “systemd”. Podman integrates very well with systemd.
While True DoDaniel Schier
Podman - Auto Updates
Containers made it very easy to package and run applications on different Linux based platforms. Building and running a container can be done in seconds and is easy to reproduce.But what about updating the running containers on a regular basis?
While True DoDaniel Schier
Installation with Docker (rootless) - Docs
Docs
Config Cheat Sheet - Docs
Docs

Conclusion

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.

Read more