# Gitea Setup Guide

This document outlines the steps needed to create a Gitea instance on an existing server using a subdomain.

## Setup Steps

### 1. DNS Provider Configuration
Set up a CNAME record for your subdomain (e.g., `gitea.karlbreuer.com`) in your DNS provider's settings.

### 2. NGINX HTTP Configuration
Create an NGINX configuration file for your Gitea subdomain:

```nginx
server {
    listen 80;
    server_name gitea.karlbreuer.com;
    location / {
        proxy_pass http://localhost:3000;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
    # Increase max body size for large Git repositories
    client_max_body_size 50m;
    # Optimize for git requests
    location /api/v1/repos {
        proxy_pass http://localhost:3000;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        # Extended timeout for Git operations
        proxy_read_timeout 300;
        proxy_connect_timeout 300;
        proxy_send_timeout 300;
    }
    # Allow large pushes
    location ~ (/api/v1)?/repos/[^/]+/[^/]+/git-receive-pack {
        proxy_pass http://localhost:3000;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        client_max_body_size 0;
        proxy_request_buffering off;
        proxy_buffering off;
    }
    # Log settings
    access_log /var/log/nginx/gitea.access.log;
    error_log /var/log/nginx/gitea.error.log;
}
```

### 3. Enable HTTPS with Certbot
Run Certbot to convert HTTP to HTTPS with SSL certificate.

### 4. Create Docker Compose File
```bash
mkdir gitea && cd gitea && sudo nano docker-compose.yml
```

Create the following `docker-compose.yml` file:

```yaml
version: "3"
networks:
  gitea:
    external: false
services:
  server:
    image: docker.gitea.com/gitea:1.23.4
    container_name: gitea
    environment:
      - USER_UID=1000
      - USER_GID=1000
    restart: always
    networks:
      - gitea
    volumes:
      - ./gitea:/data
      - /etc/timezone:/etc/timezone:ro
      - /etc/localtime:/etc/localtime:ro
    ports:
      - "3000:3000"
      - "222:22"
```

### 5. Start Gitea with Docker Compose
```bash
sudo docker-compose up -d
```

### 6. Complete Web Setup
Access the web UI and register the first account.

> ⚠️ **Security Warning**: The first registered user automatically receives admin permissions, but registration remains OPEN to anyone afterwards.

### 7. Disable Public Registration
To disable public registration after setting up your admin account, edit the `app.ini` file:

```ini
[service]
DISABLE_REGISTRATION = true
```

Then restart the Docker container:
```bash
docker restart gitea
```

Reference: [Gitea Configuration Cheat Sheet](https://docs.gitea.com/administration/config-cheat-sheet?_highlight=disable&_highlight=self&_highlight=registration#server-server)

### 8. Fix IPv4/IPv6 Issues
If you experience IPv6 connectivity issues, force IPv4 by adding this to your SSH config:

```
# Add to ~/.ssh/config
Host gitea.karlbreuer.com
    HostName gitea.karlbreuer.com
    User git
    Port 222
    IdentityFile ~/.ssh/gitea
    AddressFamily inet  # Force IPv4
```

## References
- [Gitea Docker Installation Guide](https://docs.gitea.com/installation/install-with-docker)