gitea/README.md

Gitea self-hosted

Stack Docker per un server Git self-hosted con interfaccia web HTTPS e accesso SSH.

Requisiti

Host

• Sistema operativo: Linux (qualsiasi distribuzione moderna)
• Docker (v20.10+) e Docker Compose (v2+) installati
• Spazio su disco sufficiente per i dati di Gitea (repository, DB)

Porte

Le seguenti porte devono essere libere sull'host (non in uso da altri servizi) e raggiungibili dall'esterno (aperte sul firewall e, se dietro NAT, con port forwarding sul router):

Porta	Uso
80	HTTP (Caddy, redirect a HTTPS)
443	HTTPS (Caddy + Let's Encrypt)
2222	SSH Git (Gitea)

La porta 3000 viene usata internamente da Gitea ed è esposta solo su localhost — non deve essere raggiungibile dall'esterno, ma deve essere libera sull'host.

Dominio

È necessario un dominio puntato all'IP pubblico della macchina host. Caddy lo usa per ottenere automaticamente il certificato TLS tramite Let's Encrypt. Può essere:

• un dominio acquistato o un sottodominio
• un servizio DDNS gratuito come NoIP o DuckDNS

Architettura

• Gitea – server Git (interfaccia web + accesso SSH)
• Caddy – reverse proxy con HTTPS automatico via Let's Encrypt

Internet ──→ Caddy (80/443) ──→ Gitea (3000, interno)
         ──→ SSH (2222)     ──→ Gitea (22, interno)

Configurazione iniziale

Prima di avviare, sostituire your-domain.com nel file Caddyfile con il proprio dominio:

your-domain.com {
    reverse_proxy gitea:3000
}

Porte (configurazione di default)

Servizio	Porta esterna	Porta interna	Note
HTTP	80	80	Redirect automatico a HTTPS gestito da Caddy
HTTPS	443	443	Caddy ottiene e rinnova il certificato da Let's Encrypt
SSH Git	2222	22	Porta standard alternativa per SSH Gitea
Web UI	(interno)	3000	Esposta solo su 127.0.0.1, proxata da Caddy

Avvio

docker compose up -d

Al primo avvio seguire la guida all'inizializzazione per configurare Gitea tramite browser.

Aggiornamento Gitea

docker compose pull
docker compose up -d

Clone via SSH

Gitea mostra automaticamente l'URL SSH corretto per ogni repository nell'interfaccia web — basta copiarlo e usarlo direttamente.

Se si vuole evitare di specificare la porta ogni volta da terminale, si può aggiungere a ~/.ssh/config:

Host your-domain.com
    Port 2222
    User git

---

Risoluzione problemi

La porta 2222 è già occupata

Se sulla macchina host la porta 2222 è già in uso da un altro servizio, cambiare la porta esterna SSH nel docker-compose.yml con una libera, ad esempio 2223:

ports:
  - "2223:22"   # prima era "2222:22"

Gitea mostrerà automaticamente la porta corretta negli URL SSH della sua interfaccia web.

Per verificare quali porte sono già in uso:

ss -tlnp | grep '2222\|2223'

Caddy non ottiene il certificato TLS

Caddy richiede che il dominio configurato nel Caddyfile punti all'IP pubblico della macchina e che le porte 80 e 443 siano raggiungibili dall'esterno (non bloccate dal firewall o dal router). Verificare:

# Controllare che le porte siano aperte
curl -v http://your-domain.com

---

Struttura directory

.
├── docker-compose.yml   # Definizione dei servizi Docker
├── Caddyfile            # Configurazione del reverse proxy
├── caddy/               # Dati runtime Caddy (non versionati: certificati TLS, config generata)
└── gitea-data/          # Dati Gitea (non versionati: repository, DB, secrets, chiavi SSH host)