self-host-101/gitea/readme.md

# Gitea - Self Hosted GitHub

Before starting, make sure you have:
* Caddy web server installed (see [Caddy guide](../caddy/readme.md))
* Docker and Docker Compose installed on your VPS

If you don't have docker installed, check the [installation guide](https://docs.docker.com/engine/install/) and install the docker engine.

**Important:**  Add yourself to the docker group, so that you don't need to use `sudo` to run docker commands.

```bash
sudo usermod -aG docker new_user
```

## Installation

We'll run Gitea using Docker (just a personal preference).
**Reference:** [installation guide](https://docs.gitea.com/next/installation/install-with-docker)

### 1. Set Up Docker Compose 

Create a directory for Gitea

```bash
mkdir -p ~/gitea
cd ~/gitea
```

Create a `docker-compose.yaml` file inside the gitea directory

```bash
cd ~/gitea
touch docker-compose.yaml
```

Copy the content of [docker-compose.yaml](./docker-compose.yaml) file to newly created `docker-compose.yaml` file.

### 2. Reverse Proxy Setup

To make it Gitea accessible outside the server we need to setup a subdomain for Gitea `https://git.domain.com` and set up a reverse proxy with Caddy.

Set Up DNS by creating an **A Record**
* **Name**: `git` (for `git.domain.com`)
* **Value**: Server's IP address

Create a reverse proxy for `git.domain.com` domain

Create the config file in Caddy's config directory:

```bash
sudo vim /etc/caddy/conf.d/gitea.Caddyfile
```

Copy the content from [gitea.Caddyfile](./gitea.Caddyfile).

After creating the config file, reload Caddy

```bash
sudo systemctl reload caddy
```

Change the `GITEA__server__ROOT_URL` environment variable inside the docker-compose file to the git subdomain.

Start the GITEA docker container

```bash
docker compose up -d
```

Gitea is now running on port 3000 and will show an installation wizard.

---

## Installation Setup

**Database** SQLite just to keep it simple

**Site Title:** a cool name or just use default "Gitea"

**Repository Root Path** keep the default`/data/git/repositories`

**Server Domain** Gitea domain `git.domain.com`

**SSH Port:** `2222`

**HTTP Port:** keep default`3000` or just use any available port

**Gitea Base Url:** `https://git.domain.com`

**Server Settings:** Enable `Local Mode` and disable `Self Registeration` if installing for personal use.

After this just click on **Install Gitea** button and your Gitea is ready to use

---

## Enable SSH

Since Gitea is running inside a Docker container, we cannot directly access git via SSH.
To achieve this we need to forward SSH connections from the host to the container.

To make this happen Gitea keys are prefixed with `command = ....` which executes the shim script (that we will create).
This script upon execution authenticates the host `git` user to docker container and passes the control to container.

<img
    src="https://ghub.lilj.studio/lilJ/self-host-101/raw/branch/trunk/assets/ssh-shim.png"
    alt="SSH_SHIM"
/>

**Reference:** [Official Gitea Documentation](https://docs.gitea.com/next/installation/install-with-docker#ssh-container-passthrough)

### 1. Create the `git` User on the Host

We'll create a special user called `git`.
When someone connects via SSH for Git operations, `git` user receives the connection and forwards it to the Gitea container.

```bash
sudo useradd -mr -s /bin/bash git
```
* `-m` - Creates the user's home directory (`/home/git`)
* `-r` - Creates a system user (typically UID below 1000)
* `-s /bin/bash` - Sets bash as the login shell

Check the user id and group id of the user created

```bash
id git
# You should see something like
# uid=101(git) gid=101(git) groups=101(git)
```

### 2. Update Docker Compose Configuration

To make the forwarding work, the SSH port of the container (`22`) needs to be mapped to the host port 2222.

```yaml
ports:
  - "127.0.0.1:3000:3000"
  - "127.0.0.1:2222:22"
```

Mount `/home/git/.ssh` directory to the container.
This is to ensure `authorized_keys` file is shared between the host and container.

```yaml
volumes:
  - gitea-data:/data
  - /home/git/.ssh/:/data/git/.ssh  # Share SSH keys between host and container
```
This will ensure that any ssh key added to gitea is also added to host's `authorized_keys` file.


Also update `USER_UID` and `USER_GID` environment variables to match the git user you just created.
This ensures file permissions work correctly.

```yaml
environment:
  - GITEA__server__ROOT_URL=https://git.domain.com/
  - USER_UID=101
  - USER_GID=101
```

### 3. Generate SSH Keys on host

The `git` user on your server needs to connect to the Gitea container to perform git operations.
Generate an SSH key that allows this connection.

```bash
sudo -u git ssh-keygen -t ed25519 -f /home/git/.ssh/gitea_key -N ""
```

This creates two files:
* `/home/git/.ssh/gitea_key` - Private key (keep this secret!)
* `/home/git/.ssh/gitea_key.pub` - Public key


Also add the public key to authorized_keys.
This allows the git user to SSH into the container.

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

### 4. Configure SSH Shim Script

Now we'll create a script that intercepts SSH connections meant for Gitea and forwards them to the container.

```bash
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 this script executable
sudo chmod +x /usr/local/bin/gitea
```

After all the changes restart the gitea container
```bash
docker compose restart
```

### 5. Test SSH Access

Now users can add their SSH public keys to their Gitea accounts and use Git over SSH it should work perfectly fine.

Try cloning a repository

```bash
git clone git@git.domain.com:username/repo.git
```