upd: aggiunta documentazione stack v4

apps/docs/docs/it/stack/01-panoramica.md

@@ -0,0 +1,39 @@
+# Stack di sviluppo
+
+GDRCD Stack è l'ambiente Docker locale per sviluppare e provare
+[GDRCD](https://github.com/GDRCD/GDRCD). Fornisce i servizi necessari senza
+vincolare il codice applicativo alla configurazione Docker.
+
+Lo stack risiede nella directory principale; il progetto GDRCD viene montato
+da `www`. Configurazione, log e dati persistenti rimangono separati dal codice.
+
+> Non destinato alla produzione.
+
+## Requisiti
+
+- Docker con Docker Compose
+- Bash 3.2 o successivo
+- `wget`, `curl` e `tar`
+- WSL su Windows; PowerShell non è supportato
+
+Git è richiesto solo per clonare i repository.
+
+## Servizi
+
+| Servizio     | Stato     | Funzione              |
+| ------------ | --------- | --------------------- |
+| `webserver`  | core      | Nginx e PHP           |
+| `database`   | core      | MySQL 8               |
+| `phpmyadmin` | opzionale | Gestione web di MySQL |
+| `mailhog`    | opzionale | Test delle email      |
+
+Container, immagini e rete usano il prefisso `PROJECT`. Questo permette di
+mantenere più stack sullo stesso host senza sovrapporre le risorse Docker.
+
+## Percorso consigliato
+
+1. [Installazione](./installazione)
+2. [Configurazione](./configurazione)
+3. [Comandi](./comandi)
+
+[Repository e segnalazioni](https://github.com/GDRCD/stack)

apps/docs/docs/it/stack/02-installazione.md

@@ -0,0 +1,91 @@
+# Installazione
+
+Sono disponibili due modalità: installer rapido per l'uso ordinario e clone
+Git per lo sviluppo dello stack. Entrambe producono la stessa struttura.
+
+## Installer rapido
+
+Esegui nella directory di destinazione:
+
+```bash
+eval "$(wget -qO- https://gdrcd.org/stack)"
+cd stack
+```
+
+L'ultima release viene estratta in `stack`. Il bootstrap non richiede Git, ma
+usa `curl` e `tar` per scaricare ed estrarre l'archivio.
+
+Directory o versione specifica:
+
+```bash
+curl -fsSL https://raw.githubusercontent.com/GDRCD/stack/master/boot.sh \
+  | bash -s -- --version v4.0.0 ~/Progetti/gdrcd
+```
+
+`--force` consente l'estrazione in una directory non vuota.
+
+## Installazione con Git
+
+```bash
+git clone https://github.com/GDRCD/stack.git
+cd stack
+```
+
+Il clone consente di seguire branch e tag del repository. `stack upgrade`
+richiede un working tree pulito e rifiuta l'aggiornamento in presenza di
+modifiche locali.
+
+## Configurazione iniziale
+
+```bash
+cp sample.env .env
+rm -f www/.gitkeep
+git clone https://github.com/GDRCD/GDRCD.git www
+```
+
+Completa `.env` seguendo la pagina [Configurazione](./configurazione).
+
+La directory `www` può contenere GDRCD oppure un progetto derivato che mantenga
+la stessa struttura applicativa.
+
+## Comando globale
+
+Installazione per l'utente corrente:
+
+```bash
+./stack install
+```
+
+- link in `$HOME/.local/bin`;
+- nome uguale a `PROJECT`, oppure `stack` se vuoto;
+- hook e completion per Bash o Zsh.
+
+Installazione di sistema:
+
+```bash
+sudo ./stack install
+```
+
+Usa `/usr/local/bin` e non modifica i file personali della shell.
+
+Opzioni:
+
+- `--target PATH`: directory del link
+- `--force`: reinstalla lo stesso stack
+- `--shell bash|zsh`: seleziona la shell
+- `--no-shell-hook`: installa solo il link
+
+Apri una nuova shell dopo l'installazione.
+
+Il link punta all'eseguibile dello stack corrente: non copia file e non crea
+una seconda installazione.
+
+## Primo avvio
+
+```bash
+./stack build
+./stack start
+```
+
+`build` crea immagini e container. Gli avvii successivi richiedono soltanto
+`start`, salvo modifiche alle immagini o alla versione PHP.

apps/docs/docs/it/stack/03-configurazione.md

@@ -0,0 +1,72 @@
+# Configurazione
+
+Lo stack legge le variabili da `.env` nella propria directory. Parti dal file
+di esempio e assegna valori compatibili con le porte disponibili sull'host.
+
+```bash
+cp sample.env .env
+```
+
+## Progetto e porte
+
+| Variabile      | Uso                                 | Esempio |
+| -------------- | ----------------------------------- | ------- |
+| `PROJECT`      | Comando, container, immagini e rete | `gdrcd` |
+| `SERVICE_PORT` | Applicazione                        | `80`    |
+| `PMA_PORT`     | phpMyAdmin                          | `8080`  |
+| `MAILHOG_PORT` | MailHog                             | `8025`  |
+| `DB_PORT`      | MySQL esposto sull'host             | `3306`  |
+
+`PROJECT` deve essere valido come nome di comando. Il fallback è `stack`.
+Lo stesso valore identifica anche le risorse Docker dello stack.
+
+## PHP
+
+| Variabile     | Uso                  | Esempio |
+| ------------- | -------------------- | ------- |
+| `PHP_VERSION` | Versione PHP         | `php84` |
+| `PHP_UID`     | UID del processo PHP | `1000`  |
+
+Versioni: `php56`, `php73`, `php80`, `php84`, `php85`.
+
+`PHP_UID` dovrebbe corrispondere all'utente che modifica i file in `www`, per
+evitare file generati dal container non scrivibili dall'host.
+
+Dopo una modifica a `PHP_VERSION`:
+
+```bash
+./stack build webserver
+```
+
+## MySQL
+
+| Variabile             | Uso                  | Esempio |
+| --------------------- | -------------------- | ------- |
+| `MYSQL_ROOT_PASSWORD` | Password di `root`   | `root`  |
+| `MYSQL_USER`          | Utente applicativo   | `gdrcd` |
+| `MYSQL_PASSWORD`      | Password applicativa | `gdrcd` |
+| `MYSQL_DATABASE`      | Database iniziale    | `gdrcd` |
+
+Configurazione GDRCD:
+
+| Parametro | Valore                                         |
+| --------- | ---------------------------------------------- |
+| host      | `database`                                     |
+| username  | `MYSQL_USER`, oppure `root`                    |
+| password  | `MYSQL_PASSWORD`, oppure `MYSQL_ROOT_PASSWORD` |
+| database  | `MYSQL_DATABASE`                               |
+
+`DB_PORT` serve solo per l'accesso dall'host.
+Tra i container il database è sempre raggiungibile come `database:3306`.
+
+## Persistenza
+
+- `www`: codice
+- `logs`: log
+- `database-data`: volume MySQL
+- `services`: servizi opzionali abilitati
+
+`clean` conserva il database. `clean --volumes` lo elimina.
+
+Le credenziali in `.env` sono destinate allo sviluppo locale e non devono
+essere riutilizzate in produzione.

apps/docs/docs/it/stack/04-comandi.md

@@ -0,0 +1,88 @@
+# Comandi
+
+Gli esempi usano il comando globale `stack`. In alternativa usa `./stack`
+dalla directory principale. Ogni comando espone il proprio help senza caricare
+l'ambiente Docker.
+
+```bash
+stack help
+stack <comando> --help
+```
+
+## Ciclo di vita
+
+| Comando                      | Azione                          |
+| ---------------------------- | ------------------------------- |
+| `stack build [SERVICE...]`   | Costruisce immagini e container |
+| `stack start [SERVICE...]`   | Avvia                           |
+| `stack stop [SERVICE...]`    | Ferma                           |
+| `stack restart [SERVICE...]` | Riavvia                         |
+| `stack recreate`             | Ricrea i container              |
+| `stack clean`                | Rimuove container e rete        |
+
+Opzioni rilevanti:
+
+- `build --force`: ignora la cache Docker
+- `clean --volumes`: elimina anche il volume MySQL
+
+Più servizi possono essere indicati nello stesso comando:
+
+```bash
+stack restart webserver database
+```
+
+Senza servizi espliciti, il comando agisce sull'intero stack abilitato.
+
+## Diagnostica
+
+```bash
+stack logs [SERVICE...]
+stack attach SERVICE
+```
+
+`logs` accetta più servizi; `attach` apre una shell in un solo container.
+
+## Servizi opzionali
+
+```bash
+stack services
+stack enable phpmyadmin mailhog
+stack disable mailhog
+```
+
+`enable` e `disable` applicano subito il nuovo stato.
+
+## Directory
+
+```bash
+stack cd          # www
+stack cd --root   # root dello stack
+```
+
+Richiede l'hook della shell. Senza hook:
+
+```bash
+cd "$(stack cd)"
+```
+
+L'eseguibile senza hook stampa il percorso perché un processo figlio non può
+cambiare la directory della shell chiamante.
+
+## Gestione CLI
+
+| Comando           | Azione                  |
+| ----------------- | ----------------------- |
+| `stack install`   | Installa comando e hook |
+| `stack uninstall` | Rimuove i file gestiti  |
+| `stack upgrade`   | Aggiorna il core        |
+
+Completion e hook manuali:
+
+```bash
+stack completion bash
+stack shell-init bash
+```
+
+Per Zsh sostituisci `bash` con `zsh`.
+
+Vedi anche [Database](./database).

apps/docs/docs/it/stack/05-database.md

@@ -0,0 +1,52 @@
+# Database
+
+I comandi operano sul container MySQL dello stack e richiedono sempre il nome
+del database. Non usano implicitamente `MYSQL_DATABASE`.
+
+## Export
+
+```bash
+stack export DATABASE [FILE]
+stack export --compress DATABASE [FILE]
+```
+
+`FILE` deve terminare con `.sql`; `--compress` aggiunge `.gz`.
+
+```bash
+stack export gdrcd backup.sql
+stack export --compress gdrcd backup.sql
+```
+
+Il dump viene preparato in un file temporaneo. La destinazione viene sostituita
+solo a export completato, così un errore non elimina un backup valido.
+
+## Import
+
+```bash
+stack import DATABASE FILE
+stack import --force-drop DATABASE FILE
+```
+
+Formati: `.sql`, `.sql.gz`. Il file sorgente non viene modificato.
+`--force-drop` elimina e ricrea il database.
+
+I file compressi vengono letti in streaming e non sono decompressi su disco.
+
+## Reset
+
+```bash
+stack refresh DATABASE
+stack refresh --yes DATABASE
+```
+
+`refresh` elimina e ricrea un database vuoto. `--yes` salta la conferma.
+
+Usa `--yes` soltanto in procedure non interattive che hanno già verificato il
+database di destinazione.
+
+> `import --force-drop`, `refresh` e `clean --volumes` eliminano dati.
+
+## Connessione
+
+- dai container: `database:3306`
+- dall'host: `localhost:${DB_PORT}`