Gitea is a lightweight, self-hosted DevOps platform with features such as Git hosting, code review, team collaboration, package registry, and CI/CD.
To ensure that Gitea meets your needs, it is recommended to read the comparison table for Gitea and other competing products (e.g. GitLab CE) before installing it.

Install Podman ¹

Podman can be installed using package managers (recommended) or manually build from source.

1
2
3
4
5
6

# Debian & Ubuntu
sudo apt-get install podman
# Arch & Manjaro
sudo pacman -S podman
# Alpine
sudo apk add podman

If you are using RHEL, please read the appropriate docs in the Red Hat Knowledgebase.

Install Podman Compose ²

Podman itself does NOT support the compose specification. To use features like Docker Compose with Podman, we need to install a community-maintained utility named Podman Compose.

Alternatively, since Podman has native support for Kubernetes, you can use Kubernetes configurations to run Gitea instead.

It is suggested to install Podman Compose using pip, a package manager for Python packages.

1
2

sudo apt-get install python3-pip -y
pip3 install podman-compose

If you get errors saying externally-managed-environment, here are two ways to resolve this issue.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10

# Use pipx
sudo apt-get install pipx -y
sudo pipx ensurepath --global
pipx install podman-compose

# Create a virtual environment
# You can ONLY use podman-compose in the current folder with this method.
python3 -m venv .venv
source .venv/bin/activate
pip install podman-compose

Write Compose File ³

Podman Compose uses the same syntax as Docker Compose. So you can even just copy the docker-compose.yml from the official Gitea docs.

Below is my compose file for reference.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13

services:
  gitea:
    image: docker.io/gitea/gitea:latest
    container_name: gitea
    restart: unless-stopped
    network_mode: host
    environment:
      - USER_UID=1000
      - USER_GID=1000
    volumes:
      - /usr/local/gitea/data:/data
      - /etc/timezone:/etc/timezone:ro
      - /etc/localtime:/etc/localtime:ro

To use my configuration, you will need to enter the following commands.

1
2
3
4
5
6

# Create directories for Gitea
mkdir /usr/local/gitea /usr/local/gitea/data
# Allow the container to read and write data to the data folder
chown 1000:1000 /usr/local/gitea/data
# Run podman compose
podman-compose up -d

Note: Gitea uses SQLite as the default database. If you want to use an external database (MySQL or PostgreSQL), please add the corresponding part after Gitea’s compose configuration.

Configure Gitea

After starting the container, you should visit http://SERVER_IP:3000 and follow the installation wizard. The first user registered will become the admin.

Then, you can find the configuration file for Gitea at CUSTOM_FOLDER/gitea/conf/app.ini, which includes the settings you entered in the installation wizard.

Email Notification ⁴

Gitea supports the following protocols: smtp, smtps, smtp+starttls, smtp+unix, sendmail, dummy. The most common protocol is smtps, so if you are not sure which one to use, use that one.

The value of FROM attribute should be something like Sender Name <Email Address>, e.g. Gitea <[email protected]>. You can also just simply enter the email address [email protected].

If your password contains special characters, you should include single quotation marks (') on both sides of your password.

1
2
3
4
5
6
7
8

[mailer]
ENABLED = true
FROM = 
PROTOCOL = 
SMTP_ADDR = 
SMTP_PORT = 
USER = 
PASSWD = 

Other Settings

See the Cheat Sheet for explanations of more configuration items such as SSL, Git LFS, and Oauth.

End

Now, enjoy your Gitea - git with a cup of tea!