CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Cos'è questo repo

Non è il codice sorgente di Gitea: è lo stack Docker di deploy (Gitea + Caddy) di un server Git self-hosted. Contiene solo docker-compose.yml, Caddyfile, README.md (requisiti, porte, troubleshooting) e SETUP.md (wizard iniziale). Non ci sono build, lint o test. Documentazione in italiano; rispondere all'utente in italiano.

Riferimenti dettagliati in docs/: config-reference, cli, backup-restore, reverse-proxy-caddy, ssh, actions-runner, email, authentication, security-hardening, troubleshooting. Leggere il file pertinente prima di rispondere a domande di configurazione.

Fonti ufficiali per risolvere dubbi di configurazione (consultarle con WebFetch prima di rispondere a memoria): https://docs.gitea.com (sito prodotto: https://about.gitea.com).

Comandi

docker compose up -d                  # avvio
docker compose pull && docker compose up -d   # aggiornamento (image gitea/gitea:latest, non pinned)
docker compose logs -f gitea          # log
docker compose restart gitea          # necessario dopo modifiche a app.ini
docker exec -u git gitea gitea <cmd>  # CLI Gitea nel container (utente git, non root)
ss -tlnp | grep '2222\|3000\|80\|443' # verifica porte occupate

Architettura

Internet ─→ Caddy :80/:443 ─→ gitea:3000 (rete interna compose; sull'host solo 127.0.0.1:3000)
         ─→ host :2222    ─→ gitea:22   (SSH Git, nessun proxy)

Caddy (caddy:2) fa TLS automatico Let's Encrypt e reverse_proxy gitea:3000. Il dominio nel Caddyfile è il placeholder your-domain.com; va allineato a ROOT_URL di Gitea. Lo SSH non passa da Caddy.
Gitea salva tutto in ./gitea-data (→ /data): config in gitea-data/gitea/conf/app.ini, repo in gitea-data/git/repositories, SQLite in gitea-data/gitea/gitea.db. DB scelto al wizard: SQLite3.
gitea-data/, caddy/data/, caddy/config/ sono runtime e in .gitignore: mai committarli (contengono secrets e chiavi host SSH).
Il wizard (SETUP.md) scrive app.ini; la porta SSH mostrata negli URL (SSH_PORT) deve coincidere con la porta sinistra del mapping compose (2222). Cambiando il mapping, aggiornare anche SSH_PORT (e SSH_LISTEN_PORT resta 22).

Schema configurazione Gitea (riferimento rapido)

Qualunque chiave di app.ini si può impostare/sovrascrivere nel servizio gitea di compose con environment: nella forma GITEA__sezione__CHIAVE=valore (applicata a ogni avvio; variante ..._FILE per leggere da file). Per UID/GID: USER_UID/USER_GID (default 1000) devono combaciare col proprietario di ./gitea-data.

Sezioni e chiavi principali (default da docs.gitea.com/administration/config-cheat-sheet):

Sezione	Chiavi chiave (default)
(root)	`APP_NAME`, `RUN_USER`, `RUN_MODE` (`prod`)
`[server]`	`ROOT_URL` (obbligatorio dietro proxy: `https://dominio/`), `DOMAIN`, `HTTP_PORT` (3000), `SSH_DOMAIN`, `SSH_PORT` (22; porta mostrata), `SSH_LISTEN_PORT`, `DISABLE_SSH`, `START_SSH_SERVER` (false), `LFS_START_SERVER` (false), `OFFLINE_MODE`, `APP_DATA_PATH`
`[database]`	`DB_TYPE` (`sqlite3`/`postgres`/`mysql`/`mssql`), `PATH` (sqlite), `HOST`, `NAME`, `USER`, `PASSWD`, `AUTO_MIGRATION` (true)
`[security]`	`INSTALL_LOCK` (true dopo wizard), `SECRET_KEY` (mai cambiare dopo l'install: rende illeggibili 2FA ecc.), `INTERNAL_TOKEN`, `REVERSE_PROXY_TRUSTED_PROXIES`, `PASSWORD_HASH_ALGO` (pbkdf2), `MIN_PASSWORD_LENGTH` (8), `DISABLE_GIT_HOOKS` (true)
`[service]`	`DISABLE_REGISTRATION`, `REQUIRE_SIGNIN_VIEW`, `REGISTER_EMAIL_CONFIRM`, `ENABLE_CAPTCHA`, `DEFAULT_USER_VISIBILITY`, `ENABLE_NOTIFY_MAIL`
`[mailer]`	`ENABLED`, `PROTOCOL` (`smtp`/`smtps`/`smtp+starttls`/`sendmail`), `SMTP_ADDR`, `SMTP_PORT`, `FROM`, `USER`, `PASSWD`
`[repository]`	`ROOT`, `DEFAULT_BRANCH` (main), `DEFAULT_PRIVATE` (last), `DISABLE_HTTP_GIT`, `DISABLED_REPO_UNITS`, `MAX_CREATION_LIMIT` (-1)
`[ssh.minimum_key_sizes]`	`RSA` 3071, `ED25519` 256, `ECDSA` 256, `DSA` -1
`[actions]`	`ENABLED` (true); retention log 365g / artifact 90g; richiede un `act_runner` separato (token: `gitea actions generate-runner-token`) — non presente in questo stack
`[session]`	`PROVIDER` (file), `COOKIE_NAME`, `SESSION_LIFE_TIME` (86400)
`[log]`	`MODE` (console), `LEVEL` (Info)
`[cron]` / `[cron.*]`	task pianificati (mirror `@every 10m`, health check `@midnight`, update checker `@every 168h`)
`[attachment]`	`MAX_SIZE` (100 MB), `MAX_FILES` (5)
`[lfs]` / `[packages]`	storage `local`; limiti pacchetti `-1` (illimitati)
`[oauth2]`, `[cache]`, `[api]`, `[other]`	token lifetime 3600s, adapter `memory`, `MAX_RESPONSE_ITEMS` 50

Per chiavi non elencate (indexer, ui, openid, webhook, storage S3/minio, ecc.) consultare il cheat sheet completo.

CLI utili (dentro il container come utente `git`)

gitea admin user create --username U --password P --email E [--admin] [--must-change-password]
gitea admin user list|delete|change-password|generate-access-token
gitea admin regenerate hooks|keys (obbligatorio dopo restore o spostamenti di directory)
gitea admin auth add-oauth|add-ldap|add-smtp|list
gitea doctor check [--all] [--fix], gitea doctor recreate-table
gitea generate secret SECRET_KEY|INTERNAL_TOKEN|JWT_SECRET
gitea manager shutdown|restart|flush-queues|processes
gitea migrate, gitea dump, gitea actions generate-runner-token
Passare -c /data/gitea/conf/app.ini se la config non viene trovata.

Backup / restore

gitea dump richiede Gitea fermo per essere consistente. In Docker: docker exec -u git -w /tmp gitea /usr/local/bin/gitea dump -c /data/gitea/conf/app.ini (cwd scrivibile per evitare errori di permessi sullo zip; RUN_USER in app.ini deve essere git). Alternativa pragmatica: fermare lo stack e copiare ./gitea-data.
Il dump produce zip con app.ini, custom/, data/, repos/, gitea-db.sql.
Restore manuale: estrarre data/* in /data/gitea, repos/* in /data/git/repositories, importare il DB, chown -R git:git /data, poi gitea admin regenerate hooks.

Note operative

Immagine gitea/gitea:latest non fissata: gli aggiornamenti possono includere migrazioni DB automatiche (AUTO_MIGRATION); fare backup prima di pull.
Modifiche a Caddyfile: docker compose exec caddy caddy reload --config /etc/caddy/Caddyfile.
Se la 2222 è occupata, cambiare solo la porta host nel compose e aggiornare SSH_PORT in Gitea (vedi README).
Cambiare dominio ⇒ aggiornare insieme Caddyfile, ROOT_URL, DOMAIN, SSH_DOMAIN e ~/.ssh/config dei client.

6.6 KiB Raw Blame History