self-host-101/gitea

Gitea - Self hosted GITHUB

Installation

Installing Gitea via docker just requires a volume for SQLite database and start the docker.gitea.com/gitea:latest image.

• Create a gitea directory somewhere.
• Copy the content of docker compose and paste in file named docker-compose.yaml in that directory.
• Start the container by running

docker compose up -d

Gitea web-app is running on port 3000 but to access it from your browser, we first need to setup a reverse proxy for Gitea.

Reverse proxy (Caddy)

We'll expose it via Caddy reverse proxy at https://git.domain-name.com domain. Like the Caddy guide, make sure DNS A Record for git.domain-name.com point to the IP Address of VPS. Then add a reverse proxy config file (e.g. /etc/caddy/conf.d/gitea.Caddyfile). Setting up reverse proxy using caddy is as easy as

git.domain-name.com {
    reverse_proxy :3000{uri}
}

Gitea caddyfile has very minimal config reverse proxy. You can also use this file as a starting point for your own config too.

Reload Caddy after making changing:

sudo systemctl reload caddy

Now visit https://git.domain-name.com to access your own github. You must have also noticed this Caddy auto‑provision TLS certificate via LetsEncrypt.

Initial setup

Open git.domain-name.com, Gitea will open up with a installation guide.

• Database: I'll pick SQLite for simplicity. If you already have postgres running for some other service you can even use that.
• Site Title: Your org name or just "Gitea". Purely cosmetic.
• Repository Root Path: Leave default /data/git/repositories (persisted on the docker volume).
• LFS: You can keep it enabled, helpful if you upload very large files like binaries or images.
• Server Domain/ROOT_URL: Set it to the your gitea domain name git.domain-name.com.
• SSH Server: Enabled.
• Email: Configure SMTP if you need invites/notifications; I'll just skip it.

Enable SSH Container Passthrough

Since SSH is running inside the container we cannot directly create a connection to gitea to perform git actions via SSH. To make this happen SSH connections will be forwarded to the gitea container from host via SHIM script.

Reference: Official Gitea Documentation

1. Create the git User on the Host

This user will act as a relay between external SSH connections and the Gitea container.

Run this command as root or with sudo:

sudo useradd -mr -s /bin/bash git

• -m: Creates a system user (UID below the range for regular users, < 1000)
• -r: Creates user's home directory if it does not exist
• -s /bin/bash: Sets the login shell to bash

Set the container UID/GID same as the new git user created.

id git # uid=101(git) gid=101(git) groups=101(git)

Set it via environment variables in docker-compose.yaml

environment:
  - USER_UID=1000
  - USER_GID=1000

Mount /home/git/.ssh of the host into the container. This is to ensures that the authorized_keys file is shared between the host git user and the container. By adding this any keys added via Gitea webapp will be availble to host as well. Users can form SSH connection to host using the keys they have added which will be shimmed to container.

volumes:
  - /home/git/.ssh/:/data/git/.ssh

2. Generate SSH Key Pair for Host git User

This key pair will be used to authenticate the git user on the host to the container.

sudo -u git ssh-keygen -t ed25519 -f ~/.ssh/gitea_key -N ""
# This creates two files:
# - ~/.ssh/gitea_key (private key)
# - ~/.ssh/gitea_key.pub (public key)

Add the key generated on host to the ~/.ssh/authorized_keys so that it can be used to authenticate when shim creates a connection from host to container.

sudo -u git cat /home/git/.ssh/gitea_key.pub | sudo -u git tee -a /home/git/.ssh/authorized_keys
sudo -u git chmod 600 /home/git/.ssh/authorized_keys

3: Configure SSH Shim Script

Now we'll create a shell script that forwards SSH connections from the host git user to the Gitea container.

cat <<"EOF" | sudo tee /usr/local/bin/gitea
#!/bin/sh
ssh -p 2222 -o StrictHostKeyChecking=no git@127.0.0.1 "SSH_ORIGINAL_COMMAND=\"$SSH_ORIGINAL_COMMAND\" $0 $@"
EOF

# Make it executable
sudo chmod +x /home/git/ssh-shell

Then restart: docker compose restart User can add their SSH public keys to their Gitea accounts and perform operations via SSH.