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:
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
mkdir gitea && cd gitea && sudo nano docker-compose.yml
Create the following docker-compose.yml file:
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
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:
[service]
DISABLE_REGISTRATION = true
Then restart the Docker container:
docker restart gitea
Reference: Gitea Configuration Cheat Sheet
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