gitea installation guide

2025-11-03 01:32:56 +05:30
parent af6e365459
commit c781b352cd
2 changed files with 144 additions and 69 deletions
--- a/gitea/docker-compose.yaml
+++ b/gitea/docker-compose.yaml
@@ -4,14 +4,12 @@ services:
    container_name: gitea
    restart: unless-stopped
    environment:
-      - GITEA__server__ROOT_URL=https://git.domain-name.com/
-
-      - USER_UID=100
-      - USER_GID=100
+      - GITEA__server__ROOT_URL=https://git.domain.com/
    volumes:
      - gitea-data:/data # Gitea Data (repositories etc...)
    ports:
-      - "3000:3000"     # We do not need to expose this port, Caddy will reverse proxy
+      - "127.0.0.1:3000:3000"     # We do not need to expose this port, Caddy will reverse proxy
+      - "127.0.0.1:2222:22"

 volumes:
  gitea-data:
--- a/gitea/readme.md
+++ b/gitea/readme.md
@@ -1,119 +1,184 @@
-# Gitea - **Self hosted GITHUB**
+# 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

-Installing Gitea via docker just requires a volume for SQLite database and start the `docker.gitea.com/gitea:latest` image.
+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

- 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
+mkdir -p ~/gitea
+cd ~/gitea
 ```

-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.
+Create a `docker-compose.yaml` file inside the gitea directory

-## 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}
-}
+```bash
+cd ~/gitea
+touch docker-compose.yaml
 ```

-[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.
+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

-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.
+Change the `GITEA__server__ROOT_URL` environment variable inside the docker-compose file to the git subdomain.

-## Initial setup
+Start the GITEA docker container

-Open `git.domain-name.com`, Gitea will open up with a installation guide.
+```bash
+docker compose up -d
+```

- **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 -->
+Gitea is now running on port 3000 and will show an installation wizard.

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

 **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.
+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.

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

-Set the container `UID/GID` same as the new git user created.
+Check the user id and group id of the user created

 ```bash
-id git # uid=101(git) gid=101(git) groups=101(git)
+id git
+# You should see something like
+# uid=101(git) gid=101(git) groups=101(git)
 ```
-Set  it via environment variables in `docker-compose.yaml`
+
+### 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
-environment:
-  - USER_UID=1000
-  - USER_GID=1000
+ports:
+  - "127.0.0.1:3000:3000"
+  - "127.0.0.1:2222:22"
 ```

-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.
+Mount `/home/git/.ssh` directory to the container.
+This is to ensure `authorized_keys` file is shared between the host and container.

 ```yaml
 volumes:
-  - /home/git/.ssh/:/data/git/.ssh
+  - 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
 ```

-### 2. Generate SSH Key Pair for Host `git` User
+### 3. Generate SSH Keys on host

-This key pair will be used to authenticate the git user on the host to the container.
+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 ~/.ssh/gitea_key -N ""
-# This creates two files:
-# - ~/.ssh/gitea_key (private key)
-# - ~/.ssh/gitea_key.pub (public key)
+sudo -u git ssh-keygen -t ed25519 -f /home/git/.ssh/gitea_key -N ""
 ```

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

-### 3: Configure SSH Shim Script
+### 4. Configure SSH Shim Script

-Now we'll create a shell script that forwards SSH connections from the host `git` user to the Gitea container.
+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
@@ -121,9 +186,21 @@ cat <<"EOF" | sudo tee /usr/local/bin/gitea
 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
+# make this script executable
+sudo chmod +x /usr/local/bin/gitea
 ```

-Then restart: `docker compose restart`
-User can add their SSH public keys to their Gitea accounts and perform operations via SSH.
+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
+```