Mage-OS è il fork community-driven di Magento che sta guadagnando sempre più popolarità tra gli sviluppatori e-commerce. Se stai cercando un modo rapido ed efficiente per configurare un ambiente di sviluppo locale per Mage-OS, DDEV è la soluzione ideale. In questa guida ti mostrerò passo dopo passo come installare e configurare Mage-OS su DDEV.
Cos’è Mage-OS?
Mage-OS è una distribuzione di Magento gestita dalla community, nata con l’obiettivo di garantire stabilità, sicurezza e longevità alla piattaforma. Mantiene la piena compatibilità con Magento Open Source mentre offre maggiore trasparenza e coinvolgimento della community nelle decisioni di sviluppo.
Prerequisiti
Prima di iniziare, assicurati di avere installato sul tuo sistema:
- Docker Desktop (Windows/Mac) o Docker Engine (Linux)
- DDEV (versione 1.21 o superiore)
- Composer (versione 2.x)
- Almeno 4GB di RAM disponibile per Docker
Passo 1: Creare il progetto DDEV
Iniziamo creando una nuova directory per il nostro progetto e configurando DDEV:
mkdir mage-os-project cd mage-os-project ddev config --project-type=magento2 --php-version=8.2 --docroot=pub --create-docroot
Questo comando configura DDEV specificamente per Magento 2/Mage-OS con PHP 8.2.
Passo 2: Avviare DDEV
Avviamo l’ambiente DDEV:
ddev start
DDEV creerà automaticamente i container Docker necessari, inclusi web server, database MySQL e servizi aggiuntivi.
Passo 3: Configurare le credenziali Composer
Per scaricare Mage-OS, dobbiamo configurare le credenziali del repository Magento. Puoi ottenere le tue credenziali dal Magento Marketplace.
ddev composer config --global http-basic.repo.magento.com <public-key> <private-key>
Passo 4: Installare Mage-OS via Composer
Ora possiamo installare Mage-OS. Utilizziamo il meta-package ufficiale:
ddev composer create-project --repository-url=https://repo.mage-os.org/ mage-os/project-community-edition .
Passo 5: Configurare il database
DDEV ha già creato un database per noi. Le credenziali di default sono:
- Database Name: db
- Username: db
- Password: db
- Host: db
Passo 6: Configurare OpenSearch
Prima di configurare OpenSearch, dobbiamo installarlo in DDEV:
ddev get ddev/ddev-opensearch ddev restart
Ora configuriamo Mage-OS per utilizzare OpenSearch:
ddev exec bin/magento config:set catalog/search/engine opensearch ddev exec bin/magento config:set catalog/search/opensearch_server_hostname opensearch ddev exec bin/magento config:set catalog/search/opensearch_server_port 9200 ddev exec bin/magento config:set catalog/search/opensearch_enable_auth 0 ddev exec bin/magento config:set catalog/search/opensearch_index_prefix magento2 ddev exec bin/magento cache:clean
Passo 7: Installare Mage-OS
Eseguiamo il comando di installazione di Magento/Mage-OS:
ddev exec bin/magento setup:install \ --base-url=https://mage-os-project.ddev.site/ \ --db-host=db \ --db-name=db \ --db-user=db \ --db-password=db \ --admin-firstname=Admin \ --admin-lastname=User \ --admin-email=admin@example.com \ --admin-user=admin \ --admin-password=admin123 \ --language=it_IT \ --currency=EUR \ --timezone=Europe/Rome \ --use-rewrites=1 \ --backend-frontname=admin \ --search-engine=opensearch \ --opensearch-host=opensearch \ --opensearch-port=9200
Passo 8: Configurazioni post-installazione
Dopo l’installazione, eseguiamo alcuni comandi essenziali:
# Imposta la modalità developer ddev exec bin/magento deploy:mode:set developer # Disabilita la cache per lo sviluppo ddev exec bin/magento cache:disable # Compila le dipendenze ddev exec bin/magento setup:di:compile # Deploya i contenuti statici ddev exec bin/magento setup:static-content:deploy -f it_IT en_US # Reindex ddev exec bin/magento indexer:reindex
Ottimizzazioni per lo sviluppo
1. Disabilitare il two-factor authentication per l’ambiente locale
ddev exec bin/magento module:disable Magento_TwoFactorAuth ddev exec bin/magento setup:upgrade
2. Installare i dati di esempio (opzionale)
Se vuoi lavorare con dati di esempio:
ddev composer require magento/module-sample-data ddev exec bin/magento sampledata:deploy ddev exec bin/magento setup:upgrade
3. Configurare XDebug
DDEV supporta XDebug nativamente. Per abilitarlo:
ddev xdebug on
Comandi utili DDEV per Mage-OS
Ecco alcuni comandi DDEV che userai frequentemente:
# Accedere alla CLI di Magento ddev exec bin/magento # Pulire la cache ddev exec bin/magento cache:clean # Vedere i log ddev logs -f # Accedere al database ddev mysql # Importare un database ddev import-db < dump.sql # Esportare il database ddev export-db > backup.sql # Riavviare i servizi ddev restart
In alternativa, potrete utilizzare un utile strumento CLI (interfaccia a riga di comando) per Magento 2 chiamato n98-magerun2 (GitHubnetz98/n98-magerun2 ), che ha rappresentato una vera svolta per gli sviluppatori Magento 2, migliorando significativamente i loro flussi di lavoro di sviluppo.
Accesso al sito
Una volta completata l’installazione, puoi accedere a:
- Frontend: https://mage-os-project.ddev.site/
- Admin Panel: https://mage-os-project.ddev.site/admin/
- Username: admin
- Password: admin123
Risoluzione problemi comuni
Errore di memoria insufficiente
Se riscontri errori di memoria durante l’installazione, aumenta il limite di memoria PHP:
ddev config --php-memory-limit=4G ddev restart
Problemi con OpenSearch
Se OpenSearch non funziona correttamente:
# Verifica che OpenSearch sia in esecuzione ddev logs -s opensearch # Riavvia il servizio OpenSearch ddev restart # Verifica la connessione ddev exec curl -X GET "opensearch:9200"
Se continui ad avere problemi, prova a reinstallare il componente:
ddev get --remove ddev/ddev-opensearch ddev get ddev/ddev-opensearch ddev restart
Errori di permessi
Per risolvere problemi di permessi sui file:
ddev exec chmod -R 777 var/ generated/ pub/static/ pub/media/
Conclusione
DDEV semplifica enormemente la configurazione di un ambiente di sviluppo locale per Mage-OS. Con questa guida, dovresti essere in grado di avere un’installazione funzionante in meno di 30 minuti. L’ambiente DDEV è perfetto per lo sviluppo quotidiano, offrendo performance elevate, facilità d’uso e tutti gli strumenti necessari per lavorare efficacemente con Mage-OS.
Ricorda che DDEV offre molte altre funzionalità avanzate come la gestione di multipli progetti, integrazione con servizi esterni, e supporto per diversi CMS e framework. Consulta la documentazione ufficiale di DDEV per scoprire tutte le possibilità.
Buono sviluppo con Mage-OS e DDEV!