130 lines
4.6 KiB
Markdown
130 lines
4.6 KiB
Markdown
# 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.
|