Gitea on Raspberry Pi with Podman

---

Gitea on Raspberry Pi with Podman: A Complete Guide

Setting up a Gitea container on a Raspberry Pi using Podman is an excellent way to host your own light and self-hosted Git service. Podman is a direct, daemon-less replacement for Docker, making it ideal for resource-limited systems like the Raspberry Pi.

This guide covers the initial setup, container execution, and web configuration.

---

1. Prerequisites and System Preparation 🛠️

Ensure your Raspberry Pi (running Raspberry Pi OS/Raspbian) is up-to-date and you have Podman installed.

A. Update the System

sudo apt update
sudo apt upgrade -y

B. Install Podman

Podman is a key component. Use apt on modern Debian-based distributions, or snap as an alternative.

Option 1: Using apt (Recommended for modern Debian-based distributions)

sudo apt install podman -y

Option 2: Using snap (If apt fails or the version is old)

sudo apt install snapd -y
sudo snap install podman

Note: Installation using snap may take longer the first time.

C. Create Data Directories

It's crucial to separate the application data (databases, repositories) from the container to ensure persistence across updates and reboots.

# Main directory for all Gitea files and logs
sudo mkdir -p /var/lib/gitea
sudo mkdir -p /var/lib/gitea/log
sudo chmod -R 777 /var/lib/gitea

---

2. Download and Run the Gitea Container 🐳

We'll use the official Gitea image (gitea/gitea) and the podman run command to set up all necessary volumes, ports, and persistence options.

A. Run the Initial Container

We'll use the latest tag, which is optimized for ARM architectures (like the Raspberry Pi).

podman run -d \
  --name gitea \
  -p 3000:3000 \
  -p 222:22 \
  -v /var/lib/gitea:/data \
  --restart=always \
  gitea/gitea:latest

Command Breakdown

Parameter	Value	Description
-d		Runs the container in detached mode (in the background).
--name	gitea	Assigns an easy-to-use name to the container.
-p	3000:3000	Maps the Gitea HTTP/Web port (3000) to port 3000 on your Raspberry Pi.
-p	222:22	Maps Gitea's internal SSH port (22) to port 222 on your Raspberry Pi.
-v	/var/lib/gitea:/data	Persistence Volume. Maps the local directory /var/lib/gitea to the container's internal data directory (/data). This saves all your data.
--restart	always	Ensures the container restarts automatically if it fails or after a system reboot.
	gitea/gitea:latest	The official Gitea image to use.

B. Verify Status

Confirm that the container is running:

podman ps

You should see a line that includes gitea with the status as Up.

---

3. Initial Web Configuration ⚙️

You can now access the Gitea web interface to complete the installation.

A. Access the Web Server

Open your browser and navigate to your Raspberry Pi's IP address and port 3000.

http://[YOUR_RASPBERRY_PI_IP]:3000

(Example: http://192.168.1.100:3000)

If this is your first access, you'll see the "Initial Configuration" page.

B. Database Configuration

Configuration Option	Recommended Value	Notes
Database Type	SQLite3	Simplest and most efficient choice for a low-traffic Pi setup.
Database Path	/data/gitea/gitea.db	Crucial: Must be in the /data/ volume to persist across container updates.
Repository Root Path	/data/git/repositories	Default value; where Git repository data will be stored.

C. Application General Settings

Configuration Option	Recommended Value	Notes
Gitea Content Path	/data/gitea	Crucial: Must match your Podman volume mount (/data).
FFmpeg Root Path	Leave blank	Not necessary for normal use.
Application Name	Your preferred name	Appears in the Gitea interface.

D. SSH and HTTP Server Configuration

This section ensures correct connectivity for both web access and Git operations.

Configuration Option	Value to Use	Notes
SSH Server Domain	Your Raspberry Pi's Local IP or domain name.	E.g., 192.168.1.100. Avoid localhost.
SSH Port	222	Use the external port defined in your podman run command (-p 222:22).
SSH Listen Port	22	Keep this value. This is the container's internal port.
HTTP Protocol Base URL	http://	Assuming you haven't set up HTTPS/SSL yet.
Base URL Domain	Your Raspberry Pi's Local IP and Port.	E.g., http://192.168.1.100:3000/.
HTTP Listen Port	3000	Keep this value. This is the container's internal port.

E. Mail Server Configuration (Optional)

If you need Gitea to send emails (for registration, notifications, etc.), configure an external SMTP server here.

• If you don't plan to use email, uncheck the "Enable Mail Service" option.

F. Administrator Configuration 👤

The first account you create here will automatically be the administrator.

1. Enter a Username (e.g., admin).
2. Enter a strong Password.
3. Enter a Confirmation Email.

G. Finalize Installation

1. Click the "Install Gitea" button.
2. Gitea will complete the setup and redirect you to the login page.

---

4. Management and Maintenance with Podman 🔧

These essential commands help you manage your Gitea container.

A. Basic Commands

Task	Command
Stop the container	podman stop gitea
Start the container	podman start gitea
Restart the container	podman restart gitea
View logs (real-time)	podman logs -f gitea
Access the container's shell	podman exec -it gitea /bin/bash

B. Updating Gitea

The easiest way to update is to replace the old container with a new one while reusing your persistent data volume.

1. Stop the current container:

   podman  stop gitea

2. Remove the old container (data remains untouched in /var/lib/gitea):

   podman  rm gitea

3. Remove the old image (Optional, to save disk space):

   podman  rmi gitea/gitea:latest

4. Rerun the container (this automatically pulls the new latest image):

   podman  run -d --name gitea -p 3000:3000 -p 222:22 -v /var/lib/gitea:/data --restart=always gitea/gitea:latest

Your Gitea instance will now be running the latest version with all your previous data intact!