From f878a520aecd54c330a20480e95b8d5aac3a5306 Mon Sep 17 00:00:00 2001
From: Karl Breuer <mail@karlbreuer.com>
Date: Tue, 4 Mar 2025 07:08:15 +0100
Subject: [PATCH] first

---
 README.md | 128 ++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 128 insertions(+)
 create mode 100644 README.md

diff --git a/README.md b/README.md
new file mode 100644
index 0000000..52aba2a
--- /dev/null
+++ b/README.md
@@ -0,0 +1,128 @@
+# 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)
\ No newline at end of file