laravel-tools

CLI interna di JumpGroup per gestire il ciclo di vita dei progetti Laravel: setup locale, dump/import database (locali e remoti via SSH), automazione Laravel Forge, stack media AWS (S3 + CloudFront) e iniezione runtime dei secret tramite @jumpgroup/secret-fetcher.

Versione corrente: 4.0.0

Indice

• Cosa fa
• Concetti chiave
• Prerequisiti
• Installazione
• Quickstart locale (progetto singolo)
• Quickstart locale (monorepo)
• Gruppi di comandi
  • local
  • database
  • cache
  • media
  • forge
• Configurazione remota (laravel-tools.yml)
• Sicurezza
• Troubleshooting

Cosa fa

laravel-tools prende come benchmark @jumpgroup/trellis-tools ma è pensato per progetti Laravel che non usano Trellis. Oggi i gruppi di comandi sono:

| Gruppo | Scopo | |---|---| | local | setup dell'ambiente di sviluppo locale (Docker, Traefik, certificati, Laravel) | | database | export/import dump MySQL, in locale e su server remoti via SSH | | cache | pulizia cache Laravel, in locale e da remoto | | media | provisioning stack media su AWS (bucket S3 privato + CloudFront + IAM) | | forge | automazione Laravel Forge: server, siti, deploy, .env remoto, SSL, DNS |

Concetti chiave

.env.example e .secret-fetcher

Ogni progetto gestito da laravel-tools deve avere, nella root dell'app Laravel:

• .env.example — template con i placeholder {{ nome_secret }} per i valori sensibili.
• .secret-fetcher — file dotenv con le credenziali Passwd Manager (group_key). Non va mai committato (il tool lo aggiunge automaticamente a .gitignore).

In fase di setup-repo, @jumpgroup/secret-fetcher legge .secret-fetcher, recupera i secret da Passwd Manager e sostituisce i placeholder di .env.example generando il .env finale. Se uno dei due file manca, i comandi si fermano con un messaggio chiaro.

Naming deterministico

APP_NAME (letto da .env.example) è la singola fonte di naming locale e pilota:

• URL app/API: https://api.{APP_NAME}.dev
• Mailpit: https://mail.{APP_NAME}.dev
• container: ${APP_NAME}-traefik, ${APP_NAME}-api, ${APP_NAME}-mysql, ${APP_NAME}-mailpit

Supporto monorepo (novità 4.0.0)

In un monorepo l'app Laravel vive in services/laravel/, mentre yarn, yarn repo-setup e yarn start si lanciano dalla root del monorepo.

laravel-tools rileva automaticamente questo layout: se la directory corrente non ha .env.example ma esiste services/laravel/.env.example, il tool entra in services/laravel/ prima di operare (stampa 📂 Monorepo rilevato). Quindi puoi lanciare ogni comando dalla root del monorepo, esattamente come in un progetto singolo.

Per il database, in un monorepo il container MySQL si chiama ${APP_NAME}-laravel-mysql (perché convivono più servizi). Il tool lo rileva da docker ps; se vuoi forzarlo, imposta DB_CONTAINER in .env.

Prerequisiti

Per il flusso locale:

• Node.js >=20
• Docker Desktop con docker compose
• mkcert (il tool esegue mkcert -install durante setup-repo)
• permessi sudo locali (per aggiornare /etc/hosts via hostile)
• .env.example e .secret-fetcher nella root dell'app Laravel target
• Node + un package manager (yarn o npm) sull'host, se il progetto ha asset Vite

Opzionali:

• Google Drive sincronizzato per i dump database (vedi pathUtils)
• laravel-tools.yml nella root del progetto per i comandi remoti
• credenziali AWS per il gruppo media
• token Laravel Forge per il gruppo forge

Installazione

Nel repo di laravel-tools:

npm install
npm link

Questo espone globalmente il comando laravel-tools. Non serve installare nulla nel progetto consumer.

Quickstart locale (progetto singolo)

Dalla root del progetto Laravel:

laravel-tools local setup-project     # definisce identità e APP_NAME
laravel-tools local setup-repo         # genera .env, stub Docker, certificati, hosts
yarn start                             # avvia lo stack Docker
laravel-tools local setup-laravel      # APP_KEY, migration, build asset, (opz.) Filament/seeder

Apri poi https://api.{APP_NAME}.dev e la mail su https://mail.{APP_NAME}.dev.

Per forzare una versione PHP diversa dal default (php8.4):

laravel-tools local setup-repo --phpversion php8.2

Quickstart locale (monorepo)

Dalla root del monorepo (dove stanno docker-compose.yml e services/):

yarn                                   # installa le dipendenze dei services
yarn repo-setup                        # setup laravel + wordpress (script del monorepo)
yarn start                             # avvia l'intero stack Docker
laravel-tools local setup-laravel      # rileva services/laravel/ ed inizializza Laravel

Tutti i comandi laravel-tools (database, cache, media, forge, local) si possono lanciare dalla root: rilevano services/laravel/ automaticamente.

Gruppi di comandi

local

local setup-project

Definisce l'identità del progetto. Controlla .env.example + .secret-fetcher, legge APP_NAME, ne propone uno slug normalizzato (sicuro per host/Docker/Traefik), e aggiorna APP_NAME, APP_URL, ASSETS_URL in .env.example. Opzionalmente avvia il setup media AWS. Non genera .env, non tocca Docker.

local setup-repo [--phpversion <ver>]

Rende eseguibile il checkout locale:

1. verifica prerequisiti e file (.env.example, .secret-fetcher)
2. genera .env con secret-fetcher
3. copia gli stub Docker e Traefik
4. esegue mkcert -install e genera i certificati per api.{APP_NAME}.dev e mail.{APP_NAME}.dev
5. aggiorna /etc/hosts
6. esegue composer install

Versioni PHP supportate: php8.0–php8.4 (default php8.4).

local setup-laravel

Inizializza Laravel dentro lo stack già avviato:

1. (monorepo) entra in services/laravel/
2. verifica che il container ${APP_NAME}-api sia in esecuzione
3. genera APP_KEY se manca
4. Filament (opzionale): se composer.json dichiara già filament/filament ne rispetta il vincolo (composer update), altrimenti installa l'ultima versione compatibile
5. genera la tabella sessioni se assente, poi migrate --graceful
6. build asset Vite sull'host (con yarn/npm, saltata se non c'è uno script build)
7. optimize:clear + health check (artisan about)
8. seeder opzionali

local user add

Crea un utente Filament (make:filament-user) nel container avviato.

local doctor

Diagnostica: file chiave, variabili minime in .env.example, prerequisiti (docker compose, mkcert, composer, sudo) e stato dei container ${APP_NAME}-api / MySQL (rilevato). In un monorepo entra in services/laravel/ prima dei check.

database

I dump seguono la convenzione {app}_{env}_{YYYYMMDD}[_{utente}].sql e vengono letti/scritti nella cartella dump del progetto (tipicamente Google Drive). I nomi file vengono validati (solo A–Z a–z 0–9 . _ -) prima di finire in comandi remoti.

| Comando | Descrizione | Opzioni | |---|---|---| | database local-export | dump del DB locale verso la cartella dump | -n <nome>, --ams, --dry-run | | database local-import | importa un dump nel container locale e pulisce le cache | -e local\|staging\|production, --ams, --dry-run | | database remote-export | mysqldump sul server via SSH e download in locale | -e staging\|production, -n <nome>, --ams, --dry-run | | database remote-import | carica un dump locale su un server e lo importa | -e staging\|production (destinazione), -s local\|staging\|production (sorgente), --dry-run | | database list | elenca i 10 dump più recenti | -e staging\|production |

remote-import distingue sorgente (da quale ambiente proviene il dump) e destinazione (su quale server caricarlo): puoi quindi caricare un dump local su staging/production. Prima dell'import propone un backup pre-import del DB remoto e, in caso di fallimento, stampa il comando di rollback.

Se nessuna opzione viene passata, il comando chiede l'ambiente in modo interattivo.

cache

| Comando | Descrizione | |---|---| | cache flush-local | cache:clear, config:clear, route:clear, view:clear nel container locale | | cache flush-remote -e <env> | le stesse pulizie sul server via SSH | | cache flush-all -e <env> | locale + remoto |

media

Provisioning dello stack media su AWS con modello sicuro: bucket S3 privato, CloudFront con Origin Access Control, bucket policy che consente la lettura solo alla distribuzione del progetto, IAM user dedicato con policy a privilegio minimo.

Naming deterministico: bucket ${APP_NAME}-media, OAC ${APP_NAME}-media-oac, IAM user media-user.${APP_NAME}, tag site=${APP_NAME}.

| Comando | Descrizione | |---|---| | media setup-general [-n <nome>] [--dry-run] | setup completo: bucket + CloudFront + OAC + IAM, aggiorna .env.example, invia credenziali a secret-fetcher | | media setup-iam [-n <nome>] [-c <cfId>] [--dry-run] | crea/ruota solo lo IAM user media | | media s3 list | lista bucket con tag site | | media s3 get -t <tag> | trova bucket per tag site | | media cloudfront list | lista distribuzioni | | media cloudfront get -t <tag> | distribuzione per tag (match esatto) | | media cloudfront setup [-n <nome>] [--dry-run] | crea/riconcilia la distribuzione |

Regioni: S3 = AWS_REGION/AWS_DEFAULT_REGION (fallback eu-central-1); CloudFront/IAM/STS = us-east-1 (override AWS_CLOUDFRONT_REGION). Profilo: AWS_PROFILE (default default). La secret access key non viene mai stampata a terminale: viene salvata in secret-fetcher e mostrata solo come ••••••••.

forge

Automazione Laravel Forge. Il token API viene salvato in ~/.laravel-tools con permessi 0600 e richiesto in modo mascherato.

| Comando | Descrizione | |---|---| | forge token set | salva il token Forge API (input mascherato) | | forge servers | elenca i server dell'account | | forge server create | crea un server AWS Lightsail via Forge e attende il provisioning | | forge server delete | elimina un server (con conferma) | | forge site create | crea un sito + database + utente, collega il repo Git, configura deploy script (staging), DNS Route53, push .env e certificato SSL | | forge deploy | avvia il deploy di un sito | | forge env get | legge il .env remoto di un sito | | forge env set | sovrascrive il .env remoto (con trasformazioni per ambiente e conferma) | | forge logs | mostra il log dell'ultimo deploy |

forge site create e forge env set rilevano il layout monorepo: lanciati dalla root, entrano in services/laravel/ e il subdir remoto viene derivato dal prefisso git.

Configurazione remota (laravel-tools.yml)

I comandi remoti (database remote-*, cache flush-remote) leggono laravel-tools.yml dalla root del progetto:

staging:
  host: 1.2.3.4
  user: deployer
  path: /home/forge/api.miosito.sitointest.it

production:
  host: 5.6.7.8
  user: deployer
  path: /home/forge/api.miosito.it

forge site create scrive/aggiorna automaticamente il blocco dell'ambiente corretto.

Sicurezza

Hardening applicato (audit v3.6.0 + v4.0.0):

• nessun comando usa shell: true; le invocazioni locali passano argomenti come array
• APP_NAME validato (^[a-z0-9-]+$) prima dell'uso in container/hostname/mkcert/hostile
• nomi dei dump validati (^[A-Za-z0-9._-]+$, no path/..) prima di finire in comandi SSH
• token Forge salvato con permessi 0600, prompt mascherato
• secret access key AWS mai stampata (salvata solo in secret-fetcher)
• bucket S3 privati (Public Access Block) + IAM user a privilegio minimo
• .env e .secret-fetcher aggiunti automaticamente a .gitignore

Troubleshooting

| Sintomo | Causa / Soluzione | |---|---| | Il progetto non è ancora stato inizializzato | manca .env.example (o services/laravel/.env.example in monorepo) | | Il file .secret-fetcher non è presente | chiedi le credenziali Passwd Manager a chi gestisce il progetto | | database import fallisce con "no such container" | in monorepo imposta DB_CONTAINER in .env, oppure avvia lo stack così che docker ps lo rilevi | | Vite manifest not found | gli asset non sono stati buildati: setup-laravel ora li builda; in alternativa yarn build nella dir Laravel | | certificato non valido nel browser | esegui mkcert -install e riavvia completamente il browser | | yarn non è disponibile sull'host | installa Node + yarn/npm sull'host (la build Vite gira sull'host) | | conflitto versione Filament | setup-laravel ora rispetta il vincolo in composer.json; verifica i requirement dei plugin |