Introducció
Lumen és un micro-framework de Laravel. És la solució perfecta per crear microserveis i API. Com que està format pels components de Laravel, Lumen et permet utilitzar totes les teves característiques preferides de Laravel, com ara Eloquent, emmagatzematge en memòria cau, cues, validació, encaminament i middleware.
Deployer és una eina de desplegament escrita en PHP amb suport per a frameworks populars a punt per utilitzar. Tot i que no inclou una recepta específica de Lumen, pots reutilitzar la seva recepta actual de Laravel i ajustar-la a les teves necessitats.
En aquest tutorial, crearem una API Lumen senzilla en una màquina local i la desplegarem al servidor Ubuntu 18.04 amb Deployer.
Requisits previs
El framework Lumen inclou alguns Requisits del servidor. A més d'això, configurarem dues màquines:
- Una màquina local que s'utilitzarà per agrupar el codi de l'API de Lumen i pujar-lo al servidor Ubuntu amb Deployer.
- Una màquina servidor que es convertirà en la destinació del desplegament, on s'executarà l'API de Lumen.
Nota
En lloc de desplegar el codi des de la màquina local, podríem utilitzar una de les solucions de CI existents com ara Travis, Github Actions o Gitlab Runners. Tanmateix, en aquest tutorial, per simplificar, utilitzarem la màquina local tant per al desenvolupament com per al desplegament.
Requisits previs de la màquina servidor
L'únic requisit previ aquí és el servidor Ubuntu 18.04, accessible amb una contrasenya de root a través de SSH. En aquest tutorial, explicarem pas a pas la instal·lació de PHP 7.4 i Apache 2.4 amb mod_php en aquest servidor.
Requisits previs de la màquina local
Aquí hi ha alguns requisits previs, incloent-hi PHP, Composer i Deployer. Algunes maneres d'aconseguir que s'executin localment són les següents:
- Instal·lar un servidor web PHP al sistema operatiu, és a dir: MAMP
- Utilitzar un hipervisor allotjat com ara VirtualBox amb Vagrant. O encara millor, utilitzar una màquina Vagrant oficial, preempaquetada Laravel Homestead.
- Utilitzar una tecnologia de contenidors com ara Docker amb Docker Compose per definir els serveis de l'aplicació en format YAML. O encara millor, utilitzar Laradock, el projecte de la comunitat Laravel.
En aquest tutorial no entrarem en detalls sobre com crear aquest entorn local. En canvi, ens centrarem a crear un projecte amb Composer, instal·lar Deployer i configurar-lo segons les nostres necessitats.
Sense més preàmbuls, comencem amb la configuració de la màquina servidor.
Instal·lació de PHP 7.4 i Apache2
Ubuntu 18.04 inclou la versió PHP 7.2 per defecte, de manera que haurem d'utilitzar els repositoris deb proporcionats per Sury.org per obtenir la versió de PHP més nova.
Per a Ubuntu, Sury manté els Arxius personals de paquets de PHP per a Ubuntu, que instal·larem ara:
apt install software-properties-common -y add-apt-repository ppa:ondrej/php -y apt update -y apt install php7.4
Com que php7.4 depèn de libapache2-mod-php7.4, que al seu torn recomana el paquet apache2 obtindrem PHP i Apache amb mod_php en funcionament d'una sola vegada.
Configuració d'Apache2 per servir l'API Lumen
cd /etc/apache2/sites-available/ cat > 001-lumen-api.conf <<EOF
<VirtualHost *:80> ServerName lumen_api DocumentRoot /var/www/lumen_api/current/public DirectoryIndex /index.php <Directory /var/www/lumen_api/current/public> AllowOverride None Require all granted FallbackResource /index.php </Directory> ErrorLog /var/log/apache2/lumen_api_error.log CustomLog /var/log/apache2/lumen_api_access.log combined </VirtualHost> EOF
Fem una pausa aquí un moment i intentem entendre per què DocumentRoot i Directory apunten a /var/www/lumen_api/current/public i no a /var/www/lumen_api/public, com recomana la documentació de Lumen.
Com que hem decidit utilitzar l'eina Deployer per al desplegament, crearà els directoris següents:
- releases que conté directoris de versions publicades.
- current que és un enllaç simbòlic al directori de la versió actual - aquest és el directori que Apache2 hauria de conèixer i llegir.
- shared que conté fitxers i directoris compartits.
Sabent això, passem a l'últim pas, és a dir, deshabilitar la configuració predeterminada d'Apache2 i habilitar la nostra:
a2dissite 000-default.conf a2ensite 001-lumen-api.conf
Amb tot això, ja tenim el nostre servidor Ubuntu en funcionament. Ara ens centrarem en la base de codi de l'API Lumen.
Base de codi de l'API Lumen a la màquina local
composer create-project --prefer-dist laravel/lumen lumen-api
Després d'haver executat l'ordre Composer, hauríem de tenir el directori lumen-api amb el projecte Lumen estructurat, com es mostra més avall:
.
├── README.md
├── app
│ ├── Console
│ │ ├── Commands
│ │ └── Kernel.php
│ ├── Events
│ │ ├── Event.php
│ │ └── ExampleEvent.php
│ ├── Exceptions
│ │ └── Handler.php
│ ├── Http
│ │ ├── Controllers
│ │ └── Middleware
│ ├── Jobs
│ │ ├── ExampleJob.php
│ │ └── Job.php
│ ├── Listeners
│ │ └── ExampleListener.php
│ ├── Providers
│ │ ├── AppServiceProvider.php
│ │ ├── AuthServiceProvider.php
│ │ └── EventServiceProvider.php
│ └── User.php
├── artisan
├── bootstrap
│ └── app.php
├── composer.json
├── composer.lock
├── database
│ ├── factories
│ │ └── ModelFactory.php
│ ├── migrations
│ └── seeds
│ └── DatabaseSeeder.php
├── deploy.php
├── phpunit.xml
├── public
│ └── index.php
├── resources
│ └── views
├── routes
│ └── web.php
├── storage
│ ├── app
│ ├── framework
│ │ ├── cache
│ │ └── views
│ └── logs
│ └── lumen-2020-04-11.log
├── tests
│ ├── ExampleTest.php
│ └── TestCase.php
└── vendor
├── autoload.php
├── bin
/// ...
Per simplificar les coses, afegirem una ruta GET /timezones dins del fitxer routes/web.php, com es mostra més avall:
<?php
$router->get('/', function () use ($router) {
return $router->app->version();
});
// Ruta GET senzilla per llistar tots els identificadors de zones horàries.
$router->get('/timezones', function () {
return DateTimeZone::listIdentifiers();
});La nostra API Lumen funciona en local, però encara ens falta el pas final: agrupar i carregar el codi al servidor Ubuntu 18.04 amb Deployer. Per fer-ho, hem d'instal·lar i configurar l'eina Deployer.
Deployer a la màquina local
Hi ha tres maneres d'instal·lar Deployer:
- Fitxer PHAR
- Instal·lació del codi font amb Composer
- Instal·lació de substitució amb Composer
Per a aquest tutorial, hem triat la segona manera: instal·lació del codi font amb Composer
Instal·lació de Deployer amb Composer com a dependència dev
composer require deployer/deployer --dev
Després d'haver requerit la dependència de Deployer, el nostre fitxer composer.json hauria de ser semblant al fragment següent:
{
"name": "laravel/lumen",
"description": "The Laravel Lumen Framework.",
"keywords": ["framework", "laravel", "lumen"],
"license": "MIT",
"type": "project",
"require": {
"php": "^7.2.5",
"laravel/lumen-framework": "^7.0"
},
"require-dev": {
"deployer/deployer": "^6.7",
"fzaninotto/faker": "^1.9.1",
"mockery/mockery": "^1.3.1",
"phpunit/phpunit": "^8.5"
},
...
}A més, hauríem d'obtenir el nou executable dep dins del directori vendor/bin:./vendor/bin/dep --version
Creació de la recepta de Deployer
dep init --template=Laravel
Aquesta ordre ha creat el fitxer bàsic deploy.php i l'ha inicialitzat amb la plantilla de recepta de Laravel.
Nota
Si vols ampliar la informació sobre què aporta la recepta de Laravel, pots fer-ho tu mateix a GitHub.
Ajust de la recepta de Deployer
php
<?php
namespace Deployer;
require 'recipe/laravel.php';
// Amfitrions
host('IP_OR_DOMAIN_OF_YOUR_UBUNTU_SERVER')
->user('root')
->port(22)
->set('deploy_path', '/var/www/lumen_api');
// Tasca principal de desplegament que consta de 4 passos més
task('deploy', [
'build',
'release',
'cleanup',
'success'
]);
// Instal·la totes les dependències de l'API Lumen a la màquina local
task('build', function () {
run('composer install');
})->local();
task('release', [
'deploy:prepare',
'deploy:release',
'upload',
'deploy:shared',
'deploy:writable',
'deploy:symlink',
]);
// Puja el directori actual de la màquina local al camí de la versió publicada a la màquina servidor ubuntu
task('upload', function () {
upload(__DIR__ . "/", '{{release_path}}');
});Abans de continuar, examinem junts què acaba de passar:
- Hem definit només un amfitrió amb contrasenya root dins de la nostra recepta. Tanmateix, en lloc d'això podríem utilitzar el Fitxer d'inventari i les claus SSH.
- Hem utilitzat l'estratègia de servidor de compilació i hem fet que Composer s'executi localment per simplificar el nombre de passos. Tanmateix, podríem utilitzar l'estratègia de servidor únic i executar tots els passos al servidor, inclòs el repositori GIT.
- Hem sobreescrit la tasca deploy per defecte i l'hem ajustat a les nostres necessitats. Però hi ha molt més per aprendre sobre el flux de Deployer per als qui tingueu set de coneixement.
Desplegament
Abans de procedir al desplegament, vegem què hem aconseguit fins ara:
- Hem configurat amb èxit el servidor Ubuntu 18.04 amb PHP 7.4 i Apache 2.4 executant-se en mode mod_php.
- Hem estructurat l'API Lumen senzilla a la nostra màquina local
- Hem instal·lat Deployer i l'hem configurat per construir la nostra API Lumen amb totes les seves dependències a la nostra màquina local.
És hora del pas final: el desplegament. Per sort, és força senzill
dep deploy
El procés de desplegament hauria de trigar 1-2 minuts i assemblar-se força a aquest extracte:
✔ Executing task build
➤ Executing task deploy:prepare
✔ root@85.208.21.90's password:
✔ Executing task deploy:release
➤ Executing task upload
✔ root@85.208.21.90's password:
✔ Executing task deploy:shared
✔ Executing task deploy:writable
✔ Executing task deploy:symlink
✔ Executing task cleanup
Successfully deployed!
Nota
Com veus, Deployer et demanarà dues vegades la contrasenya del teu servidor Ubuntu. La primera vegada per a la tasca deploy:prepare i la segona vegada per a la tasca upload. Si això et molesta, la manera més fàcil d'evitar-ho és utilitzar la configuració i les claus SSH. Pots llegir-ne més informació a la documentació d'amfitrions de Deployer.
Tan bon punt el nostre desplegament finalitzi amb èxit, podem obrir el navegador web i escriure l'URL http://tu-servidor-ip - això hauria de mostrar la ruta per defecte de l'API Lumen. També podem utilitzar l'URL http://TU-servidor-ip/timezones, que hem creat abans de manera addicional.
A més, si iniciem sessió al servidor Ubuntu a través de SSH, podem investigar l'estructura del directori creat per Developer.
/var/www/lumen_api/
├── current -> releases/2
├── releases
│ ├── 1
│ │ ├── app
│ │ ├── artisan
│ │ ├── bootstrap
│ │ ├── composer.json
│ │ ├── composer.lock
│ │ ├── composer.phar
│ │ ├── database
│ │ ├── deploy.php
│ │ ├── phpunit.xml
│ │ ├── public
│ │ ├── README.md
│ │ ├── resources
│ │ ├── routes
│ │ ├── storage -> ../../shared/storage
│ │ ├── tests
│ │ └── vendor
│ └── 2
│ ├── app
│ ├── artisan
│ ├── bootstrap
│ ├── composer.json
│ ├── composer.lock
│ ├── database
│ ├── deploy.php
│ ├── phpunit.xml
│ ├── public
│ ├── README.md
│ ├── resources
│ ├── routes
│ ├── storage -> ../../shared/storage
│ ├── tests
│ └── vendor
└── shared
└── storage
├── app
├── framework
└── logs
Aquí podem veure, com hem esmentat breument abans, que Deployer ha creat l'enllaç simbòlic current, que ara mateix apunta al directori releases/2.
Cada vegada que executem dep deploy amb èxit, hauríem de veure que l'enllaç simbòlic current es redirigeix a l'últim directori publicat.
En cas que tinguis algun problema de codi després del desplegament, pots utilitzar l'ordre dep rollback, que indica a Deployer que redirigeixi automàticament l'enllaç simbòlic current a la versió publicada anterior.
Conclusió
- Hem iniciat junts un projecte d'API Lumen senzill.
- A més d'això, hem instal·lat i configurat Deployer, una eina PHP molt pràctica, que ens ha ajudat amb el desplegament.
- També hem mostrat com configurar un servidor Ubuntu senzill.
Si vols, no cal que ho deixis aquí. Pots configurar tota una granja de servidors i comprovar com Deployer pot ajudar-te a desplegar el teu codi en tots alhora.
No està bé tenir finalment una eina de desplegament que s'ajusti a l'ecosistema PHP, semblant a Ruby i el seu Capistrano? Deixa un comentari!