# 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](./docker-compose.yaml) and paste in file named `docker-compose.yaml` in that directory.
- Start the container by running
```bash
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

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

[Gitea caddyfile](./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:
```bash
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.
<!-- # TODO: complete all these options lmaoo -->

## 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](https://docs.gitea.com/next/installation/install-with-docker#ssh-container-passthrough)

### 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`:
```bash
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.

```bash
id git # uid=101(git) gid=101(git) groups=101(git)
```
Set  it via environment variables in `docker-compose.yaml`

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

```yaml
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.

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

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

### 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.

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