Scotty: un bellissimo task runner SSH

Abbiamo appena rilasciato Scotty, un bellissimo task runner SSH. Ti permette di definire script di deploy e altre attività remote, eseguirli dal tuo terminale e osservare ogni fase mentre accade. Supporta sia il formato Blade di Laravel Envoy sia un nuovo formato bash puro.

Perché abbiamo creato Scotty

Anche se servizi come Laravel Cloud rendono possibile non pensare mai più ai server, per alcuni progetti preferisco comunque fare il deploy sui miei server. Li conosco bene, posso scegliere il provider di server che voglio e ho il pieno controllo sull'ambiente.

Strumenti come Laravel Forge hanno funzionalità di deploy integrate, e funzionano bene. Ma ho sempre preferito eseguire gli script di deploy manualmente dal mio terminale. Voglio vedere esattamente cosa succede durante l'esecuzione e, quando qualcosa va storto, voglio avere sott'occhio l'output nel momento stesso in cui accade, non dover navigare in una web UI per trovare un log.

Per anni ho usato Laravel Envoy per questo. Fa il suo lavoro, ma volevo un output più bello mentre i task sono in esecuzione e la possibilità di mettere in pausa l'esecuzione a metà deploy. Envoy usa un formato di file basato su Blade, che per noi va benissimo. Ma non tutti vogliono scrivere sintassi Blade per i propri script di deploy. Così Scotty offre anche un formato bash puro per chi lo preferisce.

Scotty è stato creato con l'aiuto dell'IA, usando il codice sorgente di Envoy come riferimento. Anche se Scotty è una riscrittura da zero, nello spirito è un fork di Envoy. Un ringraziamento a Laravel per aver fornito le fondamenta. Puoi leggere il ringraziamento completo nel repository di Scotty.

Usare Scotty

Definire i task ed eseguire il deploy

Definisci i tuoi task in un file Scotty.sh. È semplice bash con alcuni commenti di annotazione. Il tuo editor lo evidenzia correttamente e hai il pieno supporto della shell fin da subito. Ecco come appare:

#!/usr/bin/env scotty
# @servers [email protected]
# @task on:remote
deploy() {
    cd /var/www/my-app
    git pull origin main
    php artisan migrate --force
}

Esegui il deploy con un unico comando:

scotty run deploy

Scotty si connette al tuo server, esegue ogni task in ordine e ti mostra cosa sta succedendo in tempo reale. Ogni task mostra il suo nome, un contatore dei passaggi, il tempo trascorso e il comando attualmente in esecuzione. Quando tutto termina, ottieni una tabella riepilogativa con i tempi di ogni fase.

Questi screenshot provengono dal deploy di questo stesso blog. Puoi trovare il file di deploy su GitHub.

Se un task fallisce, il suo output viene mostrato e l'esecuzione si ferma lì, così puoi indagare.

Scrivere bash puro invece di Blade

Oltre a saper leggere i file Envoy.blade.php, Scotty introduce un nuovo formato Scotty.sh. Ogni riga è vero bash. I task sono semplicemente funzioni bash con un'annotazione # @task che indica a Scotty su quale server eseguirli. Le macro raggruppano i task in una sequenza. Le variabili sono normali variabili bash, disponibili ovunque.

Dato che è tutto bash valido, puoi usare funzioni di supporto, valori calcolati come $(date +%Y%m%d-%H%M%S) e qualsiasi costrutto della shell useresti normalmente. Niente direttive Blade, niente blocchi @setup di PHP, niente interpolazione {{ $variable }}.

Puoi anche passare variabili dalla riga di comando. Eseguendo scotty run deploy --branch=develop, $BRANCH diventa disponibile nei tuoi task. La chiave viene automaticamente convertita in maiuscolo.

Puoi elencare tutti i task e le macro disponibili con scotty tasks:

Mettere in pausa, riprendere e simulare

Puoi premere p in qualsiasi momento durante l'esecuzione per mettere in pausa dopo che il task corrente è terminato. Premi Enter per riprendere, oppure Ctrl+C per annullare. È comodo quando vuoi controllare qualcosa sul server a metà deploy prima di continuare.

C'è anche una modalità simulazione (scotty run deploy --pretend) che ti mostra esattamente quali comandi SSH verrebbero eseguiti senza eseguirli davvero. E una modalità riepilogo (scotty run deploy --summary) che nasconde l'output dei task e mostra solo i risultati.

Validare la configurazione con doctor

Prima del tuo primo deploy su un nuovo server, puoi eseguire scotty doctor per validare la configurazione. Verifica che il file venga analizzato correttamente, controlla la connettività SSH verso ogni server e conferma che strumenti come php, composer, node e git siano disponibili sulla macchina remota.

Migrare da Envoy

Se stai già usando Laravel Envoy, Scotty può leggere direttamente il tuo file Envoy.blade.php. Non serve alcuna modifica. Basta eseguire scotty run deploy e funziona. Da lì puoi migrare gradualmente al formato Scotty.sh se vuoi, oppure continuare a usare Blade.

Se sei nuovo a tutto questo, la pagina Il tuo primo script di deploy nella documentazione ti guida passo dopo passo.

In conclusione

Scotty ti offre un modo pulito e moderno per eseguire script di deploy e altre attività SSH dal tuo terminale. Bash puro, output elegante e pieno controllo su ogni fase.

Puoi trovare la documentazione completa sul nostro sito di documentazione e il codice sorgente su GitHub. Questo è uno dei tanti strumenti e pacchetti che abbiamo creato in Spatie. Se vuoi sostenere il nostro lavoro open source, valuta l'acquisto di uno dei nostri prodotti a pagamento.