# 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](https://www.noip.com/) o [DuckDNS](https://www.duckdns.org/)

## 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

```bash
docker compose up -d
```

Al primo avvio seguire la [guida all'inizializzazione](SETUP.md) per configurare Gitea tramite browser.

## Aggiornamento Gitea

```bash
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:

```yaml
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:

```bash
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:

```bash
# 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)
```