Gitea: your own GitHub on a Raspberry Pi

I’m studying systems administration and I produce lots of files: notes, scripts, lab configs… I wanted them under version control (Git) without uploading anything to an outside service. The answer: Gitea, a lightweight Git server with a web UI very similar to GitHub.

On a Raspberry Pi 5 it’s no effort at all: it starts in seconds and barely uses memory.

The docker-compose

services:
  gitea:
    image: docker.gitea.com/gitea:1.25
    container_name: gitea
    restart: unless-stopped
    environment:
      USER_UID: "1000"
      USER_GID: "1000"
      GITEA__database__DB_TYPE: sqlite3
      GITEA__server__ROOT_URL: http://192.168.1.50:3000/
      GITEA__server__SSH_PORT: "2222"
      GITEA__service__DISABLE_REGISTRATION: "true"
      GITEA__security__INSTALL_LOCK: "true"
    ports: ["3000:3000", "2222:22"]
    volumes:
      - ./gitea:/data
      - /etc/timezone:/etc/timezone:ro
      - /etc/localtime:/etc/localtime:ro

What’s worth explaining:

• Pinned image version (1.25) instead of latest. That way an update never catches me by surprise: I upgrade when I choose.
• SQLite as the database. Plenty for personal use, and everything ends up in the ./gitea folder. Backing up means copying that folder.
• The GITEA__section__key variables fill in Gitea’s configuration (app.ini) without editing it by hand.
• INSTALL_LOCK skips the web install wizard, since the config comes from the variables.
• DISABLE_REGISTRATION: nobody can create an account from the web. I create the accounts.

The SSH port

Git can work over HTTP or SSH. SSH is more convenient (no passwords, your key does the work), but there’s a catch: port 22 is already used by the Pi’s own SSH.

The fix is to publish the container’s SSH on another port: 2222:22. And tell Gitea with SSH_PORT, so the addresses it shows in the web UI are correct:

ssh://git@192.168.1.50:2222/ivan/my-project.git

Creating the admin user

Since sign-ups are closed and I skipped the wizard, the first user is created from the terminal:

docker exec -u git gitea gitea admin user create \
  --admin --username ivan --email me@example.com \
  --password 'a-temporary-one' --must-change-password

With --must-change-password, Gitea forces you to change it on first login. Do it, and keep the real one in your password manager. A temporary password jotted down in some notes is exactly the kind of thing that gets forgotten there forever.

Pushing a project you already have

1. In the Gitea web UI: + → New repository, empty, no README.
2. On your computer, inside the project folder:

git init
git add .
git commit -m "First commit"
git remote add origin http://192.168.1.50:3000/ivan/my-project.git
git push -u origin master

If you use the ssh:// address and have added your public key under Settings → SSH Keys, it won’t ask for a password ever again.

What if I already use GitHub?

They’re not mutually exclusive. Gitea can mirror GitHub repositories, and the other way round: push your home repositories to GitHub automatically. I use Gitea for personal stuff and anything I don’t want outside my home.

Backups

Everything is in ./gitea: repositories, SQLite database, configuration. My nightly NAS backup copies that folder along with the rest. For a more formal “hot” backup, Gitea ships the gitea dump command.

In short

Ten minutes of setup and you have your own GitHub at home, with history of everything you do. For someone studying systems, it’s also the perfect excuse to use Git every day.