GDRCD > Stack

Lo scopo di questo strumento è di fornire un basilare ambiente di sviluppo per GDRCD, lo Script per la creazione di Giochi di Ruolo "Play by Chat" su browser, e dotare l'utilizzatore di tutti gli strumenti necessari per la sua realizzazione.

Questa soluzione è stata pensata prevalentemente per lo sviluppo in locale, si sconsiglia l'uso in ambienti di produzione se non si hanno le capacità necessarie per comprenderne il funzionamento.

Requisiti

Per utilizzare lo stack presente in questa repository, occorre aver installato sul proprio terminale Docker.

Di seguito, l'indirizzo con i riferimenti per l'installazione:

• Docker Desktop (o Docker Toolbox)

Su macOS occorre inoltre installare le GNU coreutils, da cui lo stack prende greadlink:

brew install coreutils

Occorre avere un minimo di dimestichezza con il terminale per poter utilizzare lo stack.

N.B.: Su sistemi Linux e macOS si può utilizzare qualsiasi shell, ma occorre eseguire lo stack come Bash, mentre su Windows è necessario utilizzare WSL (Windows Subsystem for Linux), poiché lo stack non è compatibile con PowerShell.

Installazione

Il modo più rapido è lo script di bootstrap, che scarica l'ultima release e la scompatta. Non serve GIT:

curl -fsSL https://raw.githubusercontent.com/GDRCD/stack/master/boot.sh | bash

Lo stack finisce in una cartella stack nella directory corrente. Per scegliere un'altra destinazione, passala come argomento:

curl -fsSL https://raw.githubusercontent.com/GDRCD/stack/master/boot.sh | bash -s -- ~/Progetti/mio-gdrcd

Opzioni disponibili (dopo --): -v <tag> per installare una versione specifica invece dell'ultima, -f per scompattare in una cartella non vuota.

N.B.: è possibile anche clonare il repository con GIT, ma in questo caso occorre avere GIT installato sul proprio terminale. La repository potrebbe subire aggiornamenti con maggiore frequenza e quindi è consigliata per chi vuole contribuire allo sviluppo dello stack.

Una volta terminato il salvataggio dei file dello stack, occorre inserire il proprio progetto dentro la cartella www. Può essere fatto manualmente, così come attraverso git. Per chi sta iniziando con un nuovo progetto di GDRCD, sarà sufficiente eseguire i seguenti comandi:

cd www
git clone https://github.com/GDRCD/GDRCD.git

N.B.: potrebbe accadere che questo passaggio dia errore per via della presenza del file .gitkeep. Nel caso si può tranquillamente rimuovere quest'ultimo e ritentare lo scarico del progetto.

A questo punto, è necessario configurare le variabili di ambiente, che vengono lette dallo stack per la creazione dei container e dei servizi. Queste sono contenute nel file .env. Se non è presente, occorre crearlo copiando il file sample.env e modificandone i valori secondo le proprie necessità. È molto importante specificare quale versione di PHP si desidera utilizzare, popolando la variabile PHP_VERSION con il numero di versione desiderato tra quelle disponibili.

Di seguito le versioni attualmente supportate, con i relativi riferimenti:

• PHP 5.6 (php56)
• PHP 7.3 (php73)
• PHP 8.0 (php80)
• PHP 8.4 (php84)
• PHP 8.5 (php85)

N.B.: Puoi cambiare la versione PHP utilizzata in qualsiasi momento, cambiando la variabile nel file .env e ricostruendo lo stack.

Per proseguire con l'installazione, esegui il comando di installazione. Puoi farlo in due modi, a seconda che tu voglia il comando disponibile solo per il tuo utente o per tutti:

./stack install       # solo per il tuo utente, in $HOME/.local/bin
sudo ./stack install  # per tutti gli utenti, in /usr/local/bin

Nel primo caso, se la cartella non è già nel tuo PATH, viene aggiunta automaticamente al tuo .bashrc o .zshrc. Nel secondo caso non viene toccato alcun file di configurazione, perché /usr/local/bin è già nel PATH di sistema.

N.B.: è possibile forzare il percorso di installazione con l'opzione -t, seguita dal percorso desiderato: ./stack install -t /percorso/scelto.

Il comando di installazione configura l'ambiente di sviluppo e crea un alias di sistema per il progetto. L'alias sarà uguale al nome specificato nella variabile PROJECT del file .env.

Ad esempio, se nel file .env è stato impostato:

PROJECT=mygdrcd

Una volta completata l'installazione, sarà possibile utilizzare il comando:

mygdrcd <comando>

al posto di:

./stack <comando>

Ora il tuo stack è pronto e funzionante!

Configurazione GDRCD

Affinché GDRCD possa funzionare correttamente con lo stack occorre modificare il file di configurazione dell'engine affinchè possa utilizzare i servizi forniti da questo strumento.

Ad esempio, per la connessione al database vanno utilizzati i seguenti parametri di connessione:

Variabile	Descrizione	Valore
host o url	Nome o url dell'host che fornisce il servizio database	${PROJECT}_database, quindi ad esempio: gdrcd_database
username	Nome dell'utente con cui si effettua la connessione al database	root o $MYSQL_USER, quindi ad esempio: gdrcd
password	Password dell'utente	$MYSQL_ROOT_PASSWORD se si è scelto root o $MYSQL_PASSWORD
database	Nome del database	$MYSQL_DATABASE, quindi ad esempio: gdrcd

Molti di questi esempi fanno riferimento ai valori associati alle variabili presenti nel file .env e che verranno spiegate nel prossimo paragrafo.

Variabili

Le seguenti variabili possono essere configurate nel file .env:

Configurazione Progetto

Variabile	Descrizione	Valore Esempio
PROJECT	Nome del progetto usato per identificare il comando globale e i container	gdrcd

Configurazione Servizi

Variabile	Descrizione	Valore Esempio
SERVICE_PORT	Porta per il server web	80
PMA_PORT	Porta per accedere a phpMyAdmin	8080
MAILHOG_PORT	Porta per accedere al pannello di MailHog	8025
DB_PORT	Porta per il server MySQL	3306

Configurazione PHP

Variabile	Descrizione	Valore Esempio
PHP_VERSION	Versione di PHP da utilizzare	php73
PHP_UID	ID utente per i processi PHP (www-data)	1000

Configurazione Database

Variabile	Descrizione	Valore Esempio
MYSQL_ROOT_PASSWORD	Password utente root MySQL	root
MYSQL_USER	Nome utente applicativo MySQL	gdrcd
MYSQL_PASSWORD	Password utente applicativo MySQL	gdrcd
MYSQL_DATABASE	Nome del database predefinito	gdrcd

Copia il file sample.env in .env e modifica i valori secondo le tue necessità. I valori di esempio sono forniti solo come riferimento.

Utilizzo

Per facilitare l'utilizzo dello strumento, è stato predisposto il comando run che raccoglie una serie di comandi utili all'esecuzione delle funzioni primarie dello stack. Il comando non è altro che un file eseguibile da terminale, motivo per il quale è necessario usare la formula:

./stack <comando>

Per avviare l'esecuzione dei servizi dello stack, sarà sufficiente eseguire il seguente comando:

./stack start

In automatico avverrà la compilazione dello stack, processo che si occuperà di costruire i singoli servizi e di istanziarli in appositi container di docker, e l'avvio dei servizi.

La compilazione dello stack può essere effettuata manualmente in qualsiasi momento, attraverso il comando:

./stack build

Ciò può essere utile qualora vengono apportate modifiche allo stack, come ad esempio una modifica alla versione PHP utilizzata, o se si desidera aggiungere nuovi servizi.

Per fermare i servizi dello stack, è sufficiente eseguire il seguente comando:

./stack stop

Assieme a questi comandi, è stato predisposto anche un comando per rimuovere compleatamente lo stack, in modo da poterne ricominciare da capo:

./stack clean

Comandi Utili

Di seguito i comandi a disposizione:

./stack start # avvia lo stack
./stack stop # ferma lo stack
./stack restart # riavvia lo stack
./stack build # compila lo stack
./stack clean # rimuove tutti tutti i servizi generati dallo stack
./stack help # mostra i comandi a disposizione

Dettaglio dei Comandi

I comandi generici agiscono su tutto lo stack se invocati senza argomenti, oppure solo sui servizi elencati: ./stack restart webserver database.

./stack start [<service>...]

Avvia tutti i container dello stack, o solo quelli indicati.

./stack stop [<service>...]

Ferma tutti i container dello stack, o solo quelli indicati.

./stack restart [<service>...]

Riavvia tutti i container dello stack, o solo quelli indicati.

./stack build [<service>...]

Compila tutti i container dello stack, o solo quelli indicati.

Opzioni disponibili:

• -f, --force: Forza la ricompilazione dei container

./stack attach <service>

Apre una shell dentro il container del servizio indicato. (Solo uno alla volta!)

./stack clean

Rimuove tutti i container dello stack.

Opzioni disponibili:

• -v, --volumes: Rimuove anche i volumi associati ai container

./stack logs [<service>...]

Mostra i log di tutti i container dello stack, o solo di quelli indicati.

Opzioni disponibili:

• -f, --follow: Segue i log in tempo reale

./stack recreate

Ricrea tutti i container e le reti dello stack.

Opzioni disponibili:

• -f, --force: Forza la ricreazione dei container

./stack upgrade

Aggiorna il core dello stack all'ultima release, lasciando intatti .env, www, services e logs.

Opzioni disponibili:

• -v, --version <tag>: Installa una versione specifica (es. v2.3.1) invece dell'ultima
• -f, --force: Aggiorna anche se la versione installata è già quella richiesta

sudo ./stack install

Installa lo stack e crea un alias di sistema per il progetto.

Opzioni disponibili:

• -t, --target <path>: Specifica il percorso di installazione del comando globale (default: $HOME/.local/bin/, oppure /usr/local/bin/ se eseguito come root)
• -f, --force: Forza la reinstallazione del comando globale

./stack services

Elenca tutti i servizi opzionali disponibili, con il relativo stato.

./stack enable <service>

Abilita un servizio opzionale.

./stack disable <service>

Disabilita un servizio opzionale.

./stack export database <database_name> [file]

Esporta un database in un file di dump.

Opzioni disponibili:

• -c, --compress: Esporta un file di dump compresso

./stack import database <database_name> <file>

Importa un file di dump (.sql, .sql.gz).

Opzioni disponibili:

• -fd, --force-drop: Elimina lo schema prima dell'importazione

./stack refresh database <database_name>

Pulisce tutte le tabelle nel database.

N.B.: Se utilizzi l'installazione, non è necessario eseguire ogni volta il comando da eseguibile, ma direttamente dalla shortcut globale.

N.B.: Ogni comando dispone di un'opzione -h per visualizzare le opzioni disponibili.

Servizi Disponibili

Lo stack mette a disposizione una serie di servizi, che sono:

• Web Server (nginx)
• PHP (php56, php73, php80, php84)
• MySQL (mysql8.0)
• PhpMyAdmin (phpmyadmin)
• Mailhog (mailhog)

N.B.: Il servizio mailhog è un servizio di test che permette di visualizzare le email inviate dal sistema e funziona solo in ambiente dev.

Segnalazione bug e richieste di aiuto

Prima di aprire una segnalazione bug o una richiesta di aiuto, assicurati che il tuo problema non sia già stato trattato tra le varie issues. Se non trovi nulla, puoi aprirne una nuova qui.

Riferimenti

Di seguito le versioni di riferimento dell'engine OS GDRCD:

• GDRCD © GDRCD Organization, licenza CC

Licenza

MIT