How to Set Up Gitea: A Self-Hosted Git Server on Raspberry Pi

Gitea is a lightweight, self-hosted Git service written in Go. It provides a GitHub-like experience for managing repositories, issues, pull requests, and more -- all running on your own hardware. A Raspberry Pi is the perfect low-power host for a personal or small-team Git server.

Prerequisites

Before you begin, make sure you have the following ready:

• A Raspberry Pi 3 or newer running Raspberry Pi OS (64-bit recommended).
• Docker and Docker Compose installed. If you haven't set these up yet, see our Docker setup guide.
• SSH access to your Raspberry Pi.
• A stable network connection with a known IP address for your Pi.

Step 1: Create the Project Directory

SSH into your Raspberry Pi and create a directory for Gitea:

mkdir -p ~/gitea && cd ~/gitea

Step 2: Create the Docker Compose File

Create a docker-compose.yml file in the ~/gitea directory with the following content:

version: "3"

services:
  server:
    image: gitea/gitea:latest
    container_name: gitea
    environment:
      - USER_UID=1000
      - USER_GID=1000
      - GITEA__database__DB_TYPE=postgres
      - GITEA__database__HOST=db:5432
      - GITEA__database__NAME=gitea
      - GITEA__database__USER=gitea
      - GITEA__database__PASSWD=gitea_db_password
    restart: always
    volumes:
      - ./gitea-data:/data
      - /etc/timezone:/etc/timezone:ro
      - /etc/localtime:/etc/localtime:ro
    ports:
      - "3000:3000"
      - "2222:22"
    depends_on:
      - db

  db:
    image: postgres:16-alpine
    container_name: gitea-db
    restart: always
    environment:
      - POSTGRES_USER=gitea
      - POSTGRES_PASSWORD=gitea_db_password
      - POSTGRES_DB=gitea
    volumes:
      - ./postgres-data:/var/lib/postgresql/data

Make sure to change gitea_db_password to a strong password of your choosing. Use the same password in both the server and db service definitions.

Step 3: Start the Containers

Launch Gitea and PostgreSQL with Docker Compose:

cd ~/gitea
docker compose up -d

Verify that both containers are running:

docker compose ps

You should see both gitea and gitea-db listed with a status of "Up".

Step 4: Complete the Initial Configuration

Open your browser and navigate to http://<your-pi-ip>:3000. You will be presented with the Gitea initial configuration wizard.

Most of the database settings will already be populated from the environment variables. Review the following fields:

• Site Title: Choose a name for your Gitea instance.
• SSH Server Port: Set this to 2222 to match the Docker port mapping.
• Gitea Base URL: Set to http://<your-pi-ip>:3000/.

Under Administrator Account Settings at the bottom of the page, create your admin user. Click Install Gitea to finish.

Step 5: Create Your First Repository

Once logged in, click the + icon in the top navigation bar and select New Repository. Fill in a repository name, add a description, and optionally initialize it with a README. Click Create Repository.

You can now clone the repository to your local machine:

git clone ssh://git@<your-pi-ip>:2222/your-username/your-repo.git

Or using HTTP:

git clone http://<your-pi-ip>:3000/your-username/your-repo.git

Step 6: Mirror a Repository from GitHub

Gitea can mirror repositories from GitHub, keeping a local copy that syncs automatically. To set up a mirror:

1. Click + and select New Migration.
2. Choose GitHub as the source.
3. Enter the clone URL of the GitHub repository (e.g., https://github.com/user/repo.git).
4. Check This repository will be a mirror to enable periodic syncing.
5. If mirroring a private repository, provide a GitHub personal access token.
6. Click Migrate Repository.

Gitea will pull the repository and periodically fetch updates from GitHub.

Step 7: Configure SSH Key Access

To use SSH for pushing and pulling, add your public key to Gitea:

1. Go to Settings > SSH / GPG Keys.
2. Click Add Key.
3. Paste the contents of your ~/.ssh/id_ed25519.pub (or id_rsa.pub) file.
4. Click Add Key to save.

Test the connection:

ssh -p 2222 git@<your-pi-ip>

You should see a message confirming your Gitea identity.

Updating Gitea

To update Gitea to the latest version, run:

cd ~/gitea
docker compose pull
docker compose up -d

Troubleshooting

• Cannot access port 3000: Ensure your firewall allows traffic on ports 3000 and 2222. Check with sudo ufw status if UFW is enabled.
• Database connection errors: Verify that the POSTGRES_PASSWORD matches between the server and db services in your docker-compose.yml.
• SSH clone fails: Make sure you are specifying port 2222 in your SSH clone URL. The default port 22 is used by the host system.
• Container won't start: Check the logs with docker compose logs server to identify the issue.
• Slow performance: PostgreSQL can be memory-intensive. If your Pi has limited RAM, consider using SQLite3 instead by removing the db service and changing DB_TYPE to sqlite3.

Conclusion

You now have a fully functional, self-hosted Git server running on your Raspberry Pi. Gitea gives you complete control over your repositories, user management, and project workflows without relying on third-party services. From here, you can explore webhooks, CI/CD integrations, and team collaboration features to build out your development workflow.