lilJ/self-host-101
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

gitea installation guide

Browse Source
This commit is contained in:
Kulvir Singh
2025-11-03 01:32:56 +05:30
parent af6e365459
commit c781b352cd
2 changed files with 144 additions and 69 deletions
Download Patch File Download Diff File Expand all files Collapse all files

8
gitea/docker-compose.yaml
View File

@@ -4,14 +4,12 @@ services:
container_name: gitea container_name: gitea
restart: unless-stopped restart: unless-stopped
environment: environment:
- GITEA__server__ROOT_URL=https://git.domain-name.com/ - GITEA__server__ROOT_URL=https://git.domain.com/
- USER_UID=100
- USER_GID=100
volumes: volumes:
- gitea-data:/data # Gitea Data (repositories etc...) - gitea-data:/data # Gitea Data (repositories etc...)
ports: 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: volumes:
gitea-data: gitea-data:

205
gitea/readme.md
View File

@@ -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 ## 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 ```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) ```bash
cd ~/gitea
We'll expose it via Caddy reverse proxy at `https://git.domain-name.com` domain. touch docker-compose.yaml
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. 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 ```bash
sudo systemctl reload caddy sudo systemctl reload caddy
``` ```
Now visit `https://git.domain-name.com` to access your own github. Change the `GITEA__server__ROOT_URL` environment variable inside the docker-compose file to the git subdomain.
You must have also noticed this Caddy auto‑provision TLS certificate via LetsEncrypt.
## 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. Gitea is now running on port 3000 and will show an installation wizard.
- **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. ## Installation Setup
To make this happen SSH connections will be forwarded to the gitea container from host via SHIM script.
**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) **Reference:** [Official Gitea Documentation](https://docs.gitea.com/next/installation/install-with-docker#ssh-container-passthrough)
### 1. Create the `git` User on the Host ### 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 ```bash
sudo useradd -mr -s /bin/bash git sudo useradd -mr -s /bin/bash git
``` ```
- `-m`: Creates a system user (UID below the range for regular users, < 1000) * `-m` - Creates the user's home directory (`/home/git`)
- `-r`: Creates user's home directory if it does not exist * `-r` - Creates a system user (typically UID below 1000)
- `-s /bin/bash`: Sets the login shell to bash * `-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 ```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 ```yaml
environment: ports:
- USER_UID=1000 - "127.0.0.1:3000:3000"
- USER_GID=1000 - "127.0.0.1:2222:22"
``` ```
Mount /home/git/.ssh of the host into the container. Mount `/home/git/.ssh` directory to the container.
This is to ensures that the `authorized_keys` file is shared between the host git user and the container. This is to ensure `authorized_keys` file is shared between the host and 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 ```yaml
volumes: 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 ```bash
sudo -u git ssh-keygen -t ed25519 -f ~/.ssh/gitea_key -N "" sudo -u git ssh-keygen -t ed25519 -f /home/git/.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. 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 ```bash
sudo -u git cat /home/git/.ssh/gitea_key.pub | sudo -u git tee -a /home/git/.ssh/authorized_keys 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 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 ```bash
cat <<"EOF" | sudo tee /usr/local/bin/gitea 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 $@" ssh -p 2222 -o StrictHostKeyChecking=no git@127.0.0.1 "SSH_ORIGINAL_COMMAND=\"$SSH_ORIGINAL_COMMAND\" $0 $@"
EOF EOF
# Make it executable # make this script executable
sudo chmod +x /home/git/ssh-shell sudo chmod +x /usr/local/bin/gitea
``` ```
Then restart: `docker compose restart` After all the changes restart the gitea container
User can add their SSH public keys to their Gitea accounts and perform operations via SSH. ```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
```