---
title: Deploy Gitea using Podman on Linux
date: 2025-01-03
categories: Tech
---

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](https://docs.gitea.com/installation/comparison) for Gitea and other competing products (e.g. GitLab CE) before installing it.

### Install Podman [^1]

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

```bash
# 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](https://access.redhat.com/solutions/3650231) in Red Hat Knowledgebase.

### Install Podman Compose [^2]

Podman itself does NOT support the [compose specification](https://compose-spec.io). 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.

``` bash
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.

```bash
# 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 [^3]

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.

```yaml
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.

```bash
# 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 [^4]

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 <git@example.com>`. You can also just simply enter the email address `git@example.com`.

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

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

#### Other Settings

See the [Cheat Sheet](https://docs.gitea.com/administration/config-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!

[^1]: Podman Official Docs  
https://podman.io/docs/installation
[^2]: Podman Compose Github Repository  
https://github.com/containers/podman-compose
[^3]: Gitea Official Docs: *Installation with Docker*  
https://docs.gitea.com/installation/install-with-docker
[^4]: Gitea Official Docs: *Email setup*  
https://docs.gitea.com/administration/email-setup