🇬🇧 English · 🇮🇹 Italiano · 🇪🇸 Español
🧰 piccoli script che automatizzano il lavoro di setup ripetitivo che faccio ogni volta che metto online una nuova webapp — dns, hosting, e qualsiasi altra cosa si guadagni un posto qui col tempo.
nei cartoni, nei fumetti e nei videogiochi, hammerspace è quel magazzino extradimensionale immaginario da cui un personaggio tira fuori esattamente l'attrezzo che gli serve, dal nulla, nel momento esatto in cui gli serve — wikipedia ne racconta la storia completa, dalle gag dei looney tunes ai fandom anime (lamù, ranma ½) che hanno coniato il termine. tv tropes ha un catalogo più approfondito, se ti va di scendere nella tana del bianconiglio.
l'idea qui è quella: infili la mano, tiri fuori lo script giusto, torni a costruire.
uno script python per lavoro, azionabile dalla tab actions di github — senza installare niente, con le credenziali che restano nei secrets del repo — oppure da terminale, quando vuoi vederlo lavorare.
%%{init: {'theme': 'dark'}}%%
flowchart LR
YOU[tu] -->|tab actions| GHA[github actions]
YOU -->|terminale| CLI[gli script]
GHA --> CLI
CLI -->|sottodominio, .htaccess, autossl, account ftp| UAPI[cpanel uapi]
CLI -->|cancella sottodominio e file| API2[cpanel api2]
CLI -->|branch, secrets, workflow di deploy| GH[api github]
CLI -.->|record a, opzionale| NC[api namecheap]
CLI -.->|authorized urls, opzionale| PH[api posthog]
UAPI --> SRV[(il tuo server)]
API2 --> SRV
GH -->|push| SRV
la divisione fra le due api di cpanel non è una scelta di stile: uapi semplicemente non ha una funzione di cancellazione, né per i sottodomini né per i file — ce l'ha invece per gli account ftp. vedi le note sull'api cpanel e le note sull'api github.
| strumento | cosa fa |
|---|---|
create_subdomain.py |
crea un sottodominio su cpanel, punta la document root a ~/<nome>, forza il redirect https, scrive una pagina iniziale con PostHog già integrato (o senza, con --skip-posthog), aggiunge il sottodominio agli authorized urls di PostHog perché web analytics lo mostri, e avvia autossl. opzionalmente crea un record dns dedicato. lo cancella anche, con o senza i suoi file. |
setup_autodeploy.py |
collega un repo github a quel sottodominio: crea l'account ftp, scrive i tre secret FTP_* sul repo di destinazione e ci committa un workflow di deploy, così ogni push pubblica. smonta anche tutto quanto. |
setup_gitflow.py |
prepara un repo github per il gitflow: un commit iniziale se è vuoto, e un branch develop accanto a master. setup_autodeploy.py lo lancia da solo su un repo vuoto. |
- 🚀 un click dalla tab actions — nessun checkout, nessun python locale, le credenziali non escono mai dai secrets del repo
- 🧯 creazione e cancellazione sono workflow separati — un'operazione distruttiva non è mai a una casella spuntata per sbaglio di distanza da una di routine, e ognuno riceve solo le credenziali che gli servono
- ✍️ per le operazioni distruttive devi riscrivere il nome — verificato prima ancora che venga installato qualcosa
- 🔍
--dry-runovunque — stampa tutte le chiamate che farebbe e non ne fa davvero nessuna, nemmeno in sola lettura - 🛫 controlla prima di scrivere — il run di auto-deploy verifica repo, branch, workflow e nome ftp all'inizio, così un errore a metà non lascia un account ftp orfano
- 🌱 anche i repo vuoti — l'auto-deploy su un repo ancora senza commit gli dà prima un commit iniziale e i branch
master+developdel gitflow, invece di fallire su un branch che non esiste - 🔒 https forzato, ftp cifrato — un blocco
mod_rewriteaggiunto all'.htaccessdel sottodominio, e deploy via ftps invece dell'ftp in chiaro della procedura originale - 🗝 secret sigillati, mai stampati — i secret del repo sono sealed box libsodium, e la password ftp generata resta fuori dai log se non la chiedi
- 🗑 file nel cestino per default — recuperabili dal file manager di cpanel;
--purgequando lo intendi davvero - 🛡 i path si leggono, non si indovinano — la document root arriva da cpanel stesso, e tutto ciò che sta fuori dalla home (o è
public_html) viene rifiutato - 🚫 non sovrascrive ciò che non ha scritto lui — un
.htaccesso un workflow di deploy già presenti fermano il run invece di essere rimpiazzati - 🌐 il dns di solito non serve — un record wildcard creato una volta sola fa risolvere ogni sottodominio nel momento in cui esiste
- 📊 tracciato dal primo minuto — una pagina iniziale noindex con uno snippet PostHog senza cookie finisce nella document root (
--skip-posthogper farne a meno), esetup_autodeploy.pyavvisa se il repo che poi fa deploy non porta anche lui lo snippet. con una personal api key di PostHog impostata, il sottodominio entra anche negli authorized urls del progetto — web analytics filtra su quelli — e ne esce con--delete - 💥 fallisce presto e a voce alta — una credenziale mancante si annuncia per nome, invece di trasformarsi in un errore api incomprensibile più avanti
python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt
cp .env.example .env # metti le tue credenziali, non committare mai questo file
chmod 600 .env # contiene token api veril'elenco completo delle credenziali, e i secrets da configurare su github, in setup.
dalla tab actions, oppure:
python3 create_subdomain.py lab # crea
python3 create_subdomain.py lab --dry-run # provalo a vuoto
python3 create_subdomain.py lab --delete # rimuove, tiene i file
python3 create_subdomain.py lab --delete --with-files # + cartella nel cestino
python3 create_subdomain.py lab --delete --with-files --purge # + cartella cancellata davvero
python3 setup_autodeploy.py lab --repo tu/lab # push e pubblica
python3 setup_autodeploy.py lab --repo tu/lab --branch web # da un altro branch
python3 setup_autodeploy.py lab --repo tu/lab --delete # smonta tutto
python3 setup_gitflow.py --repo tu/lab # master + developtutti i flag, e cosa fa davvero ogni step, in uso.
create_subdomain.py lo strumento per i sottodomini
setup_autodeploy.py lo strumento per il deploy da git
setup_gitflow.py lo strumento per il gitflow
acme/ certificato wildcard: hook dns per acme.sh + setup, girano sul server
test_*.py test sulle funzioni pure
.github/workflows/ un workflow per strumento, più uno separato per ogni cancellazione
docs/ setup, uso, note sull'api, risoluzione problemi
assets/ grafica, e lo snippet PostHog incluso in ogni pagina iniziale
- setup — credenziali, i livelli di token, i secrets github, chi può lanciare cosa
- uso — ogni flag e ogni input dei workflow, e cosa fa davvero un run
- note sull'api cpanel — i buchi e le sorprese che sono costati tempo vero
- note sull'api github — secret sigillati, lo scope che dimenticano tutti, e perché un 404 non è un errore di battitura
- risoluzione problemi — cosa fare quando un run va storto
- certificato wildcard — un certificato vero per il catch-all
*, rinnovato da dentro cpanel, nessun token salvato
si lavora su develop; i workflow girano da master.
pip install -r requirements-dev.txt
pytest -qi test coprono le funzioni pure — validazione del nome, guardia sulla document
root, parsing delle risposte, costruzione dei parametri dns, cifratura dei
secret, workflow generato — quindi girano senza rete e senza credenziali.
tutto ciò che tocca un'api si verifica invece con --dry-run.
una convenzione da sapere prima di leggere il sorgente: commenti e docstring
in italiano, tutto quello che vede un utente in inglese. log, messaggi
d'errore, --help, gli input dei workflow nella tab actions e il workflow di
deploy scritto nel tuo repo sono tutti in inglese. l'italiano è l'autore che
ragiona sulla propria infrastruttura, e resta lì.
