Lo sviluppo moderno di WordPress si è evoluto al di là delle configurazioni manuali e dei flussi di lavoro di distribuzione incoerenti. Radicle combina Roots e altri strumenti di sviluppo WordPress, come Bedrock, Sage e Acorn, in un unico stack iniziale.
Questa integrazione permette di avere l’esperienza di sviluppo di Laravel direttamente in WordPress.
Inoltre, l’installazione di Radicle su Kinsta offre un ambiente di hosting che supporta i requisiti tecnici richiesti da questo stack. Potrai ottenere l’accesso SSH, l’integrazione WP-CLI e la possibilità di configurare la root del tuo documento.
Questa guida illustra il processo di configurazione e le fasi di deployment necessarie per far funzionare Radicle sull’infrastruttura di Kinsta.
Radicle e i suoi componenti
Radicle combina tre progetti Roots distinti in un ambiente di sviluppo integrato:
- Bedrock fornisce le fondamenta con la sua struttura di cartelle migliorata e la gestione delle dipendenze basata su Composer.
- Sage gestisce lo sviluppo di temi con l’integrazione di Tailwind CSS e Vite per la creazione di risorse.
- Acorn fa da ponte tra WordPress e Laravel inserendo nei progetti WordPress i template Blade, le migrazioni, il routing e molto altro ancora.
Questo tipo di ambiente di sviluppo permette di lavorare direttamente dalla root del progetto, piuttosto che all’interno delle tipiche directory dei temi. I template si trovano in resources/views/ nella root del progetto, mentre la configurazione avviene tramite file specifici dell’ambiente nella cartella bedrock.
Composer gestisce il core di WordPress, i plugin e le dipendenze personalizzate attraverso un unico file composer.json. Lo stack richiede PHP 8.3 o superiore, insieme a specifiche estensioni. Composer serve anche per la gestione delle dipendenze e di WP-CLI per le operazioni da riga di comando.
Radicle vs WordPress tradizionale
Le installazioni standard di WordPress (cioè quelle con tutto all’interno della directory wp-content) possono complicare il controllo delle versioni e rendere difficile mantenere installazioni coerenti in ambienti diversi.
Tuttavia, Radicle ristruttura questo aspetto in modo da poter controllare la versione del codice dell’applicazione senza tenere traccia dei file principali di WordPress o dei media caricati:
- Il core di WordPress si trova nella directory
public/wp, separata dal codice dell’applicazione. - La cartella
public/contentsostituiscewp-contente il codice del tema personalizzato si trova nella root del progetto.
La configurazione in stile Laravel utilizza un file .env piuttosto che incorporare le credenziali del database e le chiavi di sicurezza nei file di configurazione. Si possono definire impostazioni diverse per gli ambienti di sviluppo, staging e produzione attraverso file di configurazione separati in bedrock/environments/.
La strategia di controllo delle versioni ne beneficia perché si tiene traccia solo del codice dell’applicazione e della configurazione. Gli aggiornamenti del core di WordPress avvengono tramite Composer, i plugin servono come dipendenze e le modifiche ai temi sono archiviate nel repository.
Configurare Radicle per Kinsta
Quando si distribuisce su Kinsta, è necessaria l’autenticazione con chiave SSH, disponibile attraverso la dashboard MyKinsta.
Individua i dettagli di accesso SFTP/SSH nella sezione Info del sito e aggiungi la tua chiave SSH pubblica se non l’hai ancora fatto.
L’infrastruttura di Kinsta è in linea con i requisiti tecnici di Radicle. Esegue PHP 8.3, include Composer per la gestione delle dipendenze e ha WP-CLI preinstallato, in modo da poter gestire WordPress direttamente dalla riga di comando.
A differenza di una configurazione tradizionale di WordPress, Radicle utilizza una struttura di directory basata sulle release. Ogni distribuzione crea una cartella di release con data e ora, mentre un link simbolico a current punta alla versione attiva. La root web dell’applicazione deve essere impostata su public/current/public.
Successivamente, configura le variabili d’ambiente. Copia il file .env.example nella root del progetto Radicle e rinominalo in .env. Poi, aggiungi i dettagli del database e le impostazioni dell’ambiente:
DB_NAME='your_database_name'
DB_USER='your_database_user'
DB_PASSWORD='your_database_password'
DB_HOST='your_database_host'
WP_ENV='staging'
WP_HOME='https://{kinsta-staging-url}'
WP_SITEURL="${WP_HOME}/wp"
Radicle installa il core di WordPress all’interno di una sottodirectory /wp. In questo modo i file del core sono separati dal codice dell’applicazione personalizzata, favorendo una struttura più pulita e controllata dalle versioni.
Configurazione dello staging
La cartella di configurazione si trova nella root del progetto Radicle, accanto alle cartelle public e resources. Apri bedrock/environments/staging.php per definire le impostazioni specifiche dell’ambiente di staging. Questo file sovrascrive i valori di bedrock/application.php ogni volta che il file .env imposta WP_ENV su staging.
Imposta l’URL del sito di staging aggiungendo le seguenti costanti all’inizio di staging.php:
<?php
define('WP_HOME', 'https://staging-url');
define('WP_SITEURL', WP_HOME . '/wp');
L’URL di staging segue lo schema della sezione Ambienti del sito quando selezioni l’ambiente di staging.
Il percorso di distribuzione determina la posizione dei file sul server Kinsta. In MyKinsta, nota il percorso alla voce Dettagli ambiente. Questo percorso è in genere /www/sitename/public e rappresenta la destinazione del deployment. Lo script di distribuzione sincronizza i file in questo percorso, creando una struttura come /www/sitename/public/releases/timestamp per ogni distribuzione, con /www/sitename/public/current che fa da link simbolico alla versione attiva.
È una buona idea abilitare la modalità di debug per l’ambiente di staging all’interno di bedrock/environments/staging.php. Inoltre, copia e imposta le credenziali del database per l’ambiente di staging all’interno del file locale .env (che non dovrebbe essere impegnato nel controllo di versione). In alternativa, configura queste credenziali come variabili d’ambiente sul server di distribuzione. Kinsta genererà credenziali uniche per ogni ambiente.
Configurazione di produzione
Una volta passato all’ambiente live dal menu a tendina della dashboard MyKinsta, il processo di configurazione rispecchierà quello dell’ambiente di staging ma utilizzerà valori specifici per la produzione e impostazioni di sicurezza più rigide.
A tal fine, apri bedrock/environments/production.php nella directory principale del progetto bedrock e modifica l’URL di produzione:
<?php
define('WP_HOME', 'https://yourdomain.com');
define('WP_SITEURL', WP_HOME . '/wp');
La gestione degli errori in produzione sarà diversa da quella in staging. La differenza principale consiste nel disabilitare le visualizzazioni di debug mantenendo attivo il log degli errori:
define('WP_DEBUG', false);
define('WP_DEBUG_LOG', true);
define('WP_DEBUG_DISPLAY', false);
define('SCRIPT_DEBUG', false); Inoltre, copia le credenziali del database di produzione dalla sezione Accesso al database di MyKinsta quando sei nell’ambiente live. Queste credenziali di solito sono diverse da quelle dello staging. Tuttavia, i percorsi di distribuzione in produzione seguono lo stesso schema di quelli di staging, ma puntano alla directory dell’ambiente live. Il percorso all’interno dei dettagli dell’ambiente di MyKinsta avrà probabilmente un URL diverso (ma simile). Il tuo script di distribuzione punterà a questo percorso per i rilasci di produzione.
Modificare le attività di distribuzione
La distribuzione predefinita di Radicle presuppone un controllo del server che Kinsta non fornisce attraverso l’hosting gestito. Per questo motivo, è necessario rimuovere tutti i task di distribuzione che tentano di gestire i servizi del server.
Se stai usando Trellis (lo strumento di distribuzione predefinito di Radicle), modifica trellis/roles/deploy/hooks/finalize-after.yml ed elimina completamente il task Reload php-fpm. Kinsta gestisce il riavvio automatico di PHP-FPM quando rileva delle modifiche ai file.
Inoltre, lo svuotamento della cache avviene tramite l’API di Kinsta anziché tramite i comandi del server, quindi dovrai sostituire qualsiasi cancellazione della cache basata sul server con una richiesta HTTP all’endpoint di cancellazione della cache di Kinsta. Puoi aggiungere questo task all’hook di finalizzazione dell’installazione una volta impostata una chiave API:
- name: Clear Kinsta cache
uri:
url: "{{ site_env.wp_home }}/kinsta-clear-cache-endpoint/"
method: GET
Ogni sito ha un endpoint unico per la sicurezza, che puoi ottenere dal team di supporto di Kinsta.
La compilazione delle risorse viene eseguita prima della distribuzione, non sul server. La tua macchina di sviluppo locale o la pipeline CI/CD esegue npm run build per compilare JavaScript e CSS nella cartella public/build. Queste risorse compilate verranno distribuite insieme ai file PHP.
L’installazione delle dipendenze di Composer avviene dopo la sincronizzazione dei file utilizzando SSH per eseguire quanto segue:
cd /www/sitename/public/current
composer install --no-dev --optimize-autoloader --no-interaction
Il flag --no-dev esclude le dipendenze di sviluppo come i framework di test e gli strumenti di debug. Il flag --optimize-autoloader costruisce mappe di classi per un caricamento automatico più rapido, riducendo l’overhead della localizzazione dei file di classe durante le richieste.
Aggiungere il plugin Kinsta MU a Radicle
Il plugin Kinsta MU consente il caching di tutte le pagine, l’integrazione di CDN e la gestione della cache per il sito attraverso MyKinsta. A causa della struttura di directory non standard di Radicle, dovrai impostare alcune costanti di configurazione specifiche, anche se puoi aggiungere il plugin Kinsta MU a Radicle tramite Composer. Puoi aggiungere queste costanti al file bedrock/application.php dopo aver installato il plugin:
/**
* Kinsta CDN fix for Radicle/Bedrock structure
*/
define('KINSTA_CDN_USERDIRS', 'app');
/**
* Fix Kinsta MU Plugins URL path with Radicle/Bedrock
*/
$mu_plugins_url = Config::get('WP_CONTENT_URL') . '/mu-plugins';
define('KINSTAMU_CUSTOM_MUPLUGIN_URL', "{$mu_plugins_url}/kinsta-mu-plugins");
La prima costante specifica la directory uploads nella struttura app di Bedrock. La seconda corregge i percorsi URL delle risorse del plugin in modo da caricare correttamente i file JavaScript e CSS.
Una volta verificata l’installazione del plugin, puoi testare lo svuotamento della cache attraverso la dashboard di MyKinsta per confermare che il plugin comunica correttamente con l’infrastruttura di Kinsta.
Come impostare le distribuzioni automatiche
GitHub Actions è un modo semplice per automatizzare le distribuzioni di Radicle su Kinsta. Ad esempio, puoi creare un file di workflow nel tuo repository all’indirizzo .github/workflows/deploy.yml. Questo flusso di lavoro si attiva in caso di push a branch specifici, che costruiscono le risorse e distribuiscono il codice nell’ambiente corrispondente.
I segreti SSH memorizzati nel tuo repository GitHub consentiranno connessioni sicure ai server di Kinsta. A tal fine, aggiungi i segreti per la tua chiave privata SSH, l’host Kinsta, la porta SSH e il nome utente in GitHub.
Uno script di distribuzione orchestra il processo di sincronizzazione dei file. In genere questo script utilizza rsync per trasferire i file in modo efficiente, invia solo i file modificati e mantiene i permessi corretti. Tuttavia, dovresti escludere i file di sviluppo come node_modules, .git e .env dalla distribuzione per mantenere pulito l’ambiente di produzione.
Quando la sincronizzazione dei file sarà andata a buon fine, si potranno eseguire le attività di cancellazione e pulizia della cache. Il processo prevede che lo script di distribuzione faccia una richiesta all’endpoint di Kinsta per la cancellazione della cache, attenda la conferma e poi esegua i comandi di pulizia necessari.
Configurazione delle GitHub Actions
Puoi definire l’automazione del deployment all’interno della root del repository creando un file .github/workflows/deploy.yml. Questo file gestirà la compilazione delle risorse, l’installazione delle dipendenze e la sincronizzazione dei file con Kinsta.
Inizia con i trigger specifici per i branch che distribuiscono il branch di staging all’ambiente di staging e il branch main alla produzione:
name: Deploy to Kinsta
on:
push:
branches:
- staging
- main
jobs:
deploy:
runs-on: ubuntu-latest
steps:
- name: Checkout code
uses: actions/checkout@v3
- name: Setup Node.js
uses: actions/setup-node@v3
with:
node-version: '22'
- name: Install dependencies and build assets
run: |
npm ci
npm run build
Le strategie a matrice gestiscono più ambienti senza duplicare il codice del flusso di lavoro. Le variabili specifiche dell’ambiente che aggiungi possono cambiare in base al branch che ha attivato il flusso di lavoro:
strategy:
matrix:
include:
- branch: staging
ssh_host: ${{ secrets.KINSTA_STAGING_HOST }}
ssh_port: ${{ secrets.KINSTA_STAGING_PORT }}
ssh_user: ${{ secrets.KINSTA_STAGING_USER }}
deploy_path: /www/sitename_1/public
- branch: main
ssh_host: ${{ secrets.KINSTA_PRODUCTION_HOST }}
ssh_port: ${{ secrets.KINSTA_PRODUCTION_PORT }}
ssh_user: ${{ secrets.KINSTA_PRODUCTION_USER }}
deploy_path: /www/sitename_2/public
Le fasi di compilazione delle risorse creano file JavaScript e CSS ottimizzati prima della distribuzione. Il flusso di lavoro utilizza npm ci invece di npm install per ottenere build riproducibili basate sul tuo file package-lock.json. Il comando npm run build esegue lo script di compilazione di produzione definito in package.json, in genere eseguendo Vite o un altro bundler per compilare e minificare le risorse.
A questo punto, puoi aggiungere l’installazione di Composer dopo le fasi di Node.js:
- name: Setup PHP
uses: server/setup-php@v2
with:
php-version: '8.3'
- name: Install Composer dependencies
run: composer install --no-dev --optimize-autoloader --no-interaction
Il flusso di lavoro ha ora le risorse compilate e le dipendenze installate pronte per essere distribuite a Kinsta.
Dettagli dello script di distribuzione
La sincronizzazione dei file tramite rsync trasferisce solo i file modificati, riducendo al minimo i tempi di distribuzione. Per risolvere questo problema, aggiungi questo passaggio al workflow GitHub Actions dopo aver creato le risorse:
- name: Deploy to Kinsta via rsync
env:
SSH_PRIVATE_KEY: ${{ secrets.SSH_PRIVATE_KEY }}
run: |
mkdir -p ~/.ssh
echo "$SSH_PRIVATE_KEY" > ~/.ssh/deploy_key
chmod 600 ~/.ssh/deploy_key
rsync -avz --delete
--exclude='.git'
--exclude='node_modules'
--exclude='.env'
--exclude='trellis'
-e "ssh -i ~/.ssh/deploy_key -p ${{ matrix.ssh_port }} -o StrictHostKeyChecking=no"
./ ${{ matrix.ssh_user }}@${{ matrix.ssh_host }}:${{ matrix.deploy_path }}/releases/$(date +%Y%m%d%H%M%S)/I flag di rsync controllano il comportamento del trasferimento:
-aabilita la modalità archivio preservando i permessi e i timestamp.-vfornisce un output verboso per il debug.-zcomprime i dati durante il trasferimento.
Il flag --delete rimuove dal server i file che non esistono più nel repository, in modo da mantenere pulito il tuo deployment.
Gli schemi di esclusione impediscono il trasferimento di file non necessari. Inoltre, i metadati Git, le dipendenze di sviluppo, i file di ambiente e gli strumenti di distribuzione rimangono fuori dal server di produzione. La struttura delle directory di rilascio crea directory con data e ora per ogni distribuzione, in modo da consentire un rollback rapido modificando i symlink, o link simbolici.
La gestione dei link simbolici collega i dati persistenti a ogni nuova release. Dopo aver sincronizzato i file, puoi accedere al server tramite SSH e creare dei symlink:
- name: Create symlinks and update current
run: |
ssh -i ~/.ssh/deploy_key -p ${{ matrix.ssh_port }} -o StrictHostKeyChecking=no
${{ matrix.ssh_user }}@${{ matrix.ssh_host }} << 'EOF'
cd ${{ matrix.deploy_path }}
# Link shared .env file
ln -nfs ${{ matrix.deploy_path }}/shared/.env
${{ matrix.deploy_path }}/releases/$(ls -t releases | head -1)/.env
# Link uploads directory
ln -nfs ${{ matrix.deploy_path }}/shared/public/content/uploads
${{ matrix.deploy_path }}/releases/$(ls -t releases | head -1)/public/content/uploads
# Update current symlink atomically
ln -nfs ${{ matrix.deploy_path }}/releases/$(ls -t releases | head -1)
${{ matrix.deploy_path }}/current
EOFIl file .env contiene la configurazione specifica dell’ambiente che persiste in tutte le distribuzioni. I caricamenti memorizzati al di fuori della directory delle release eviteranno la perdita dei file multimediali quando le vecchie release vengono cancellate. L’aggiornamento atomico dei symlink (ln -nfs) garantisce l’assenza di tempi di inattività poiché le richieste non si fermano mai su una release non ancora distribuita.
Il Cleanup rimuove le vecchie release dopo il successo della distribuzione per mantenere solo le cinque più recenti:
- name: Clean up old releases
run: |
ssh -i ~/.ssh/deploy_key -p ${{ matrix.ssh_port }} -o StrictHostKeyChecking=no
${{ matrix.ssh_user }}@${{ matrix.ssh_host }} << 'EOF'
cd ${{ matrix.deploy_path }}/releases
ls -t | tail -n +6 | xargs rm -rf
EOFQuesta strategia di pulizia permette di raggiungere un equilibrio tra l’utilizzo dello spazio su disco e la possibilità di rollback. Cinque release forniscono diversi punti di rollback evitando una crescita indefinita dello spazio di archiviazione.
Sommario
Radicle trasforma lo sviluppo di WordPress integrando la struttura migliorata di Bedrock, il moderno workflow dei temi di Sage e le funzionalità di Laravel di Acorn in un unico stack.
La distribuzione su Kinsta richiede una configurazione che va oltre l’hosting WordPress standard, ma offre vantaggi in termini di sicurezza, manutenibilità ed esperienza degli sviluppatori che giustificano lo sforzo di configurazione.
Quando sarà il tuo momento per distribuire applicazioni WordPress moderne con fiducia, dai un’occhiata all’hosting WordPress gestito di Kinsta e sperimenta un’infrastruttura di hosting che supporta il flusso di lavoro di sviluppo personalizzato che desideri.
