Desde hace tiempo trabajo con Docker para los entornos de desarrollo y lo valoro mucho la velocidad con la que se crea la infraestructura para los espacios de trabajo, pereo sobretodo por por su capacidad de permitir el trabajo con versiones de tecnologías diferentes, ajustadas a las necesidades de los proyectos.

En este sentido, Laravel Sail ha aportado mucha facilidad a los desarrolladores que no quieren ensuciarse las manos con la configuración de los contenedores, sin embargo no se puede usar en todas las versiones de Laravel. Si tienes que dar mantenimiento a proyectos "Legacy" probablemente no te sirva esta herramienta.

Hace poco publicamos una colección de los mejores servicios para trabajar con contenedores a la hora de crear entornos de desarrollo que se adapten a Laravel. Hoy vamos a ver una guía de trabajo con una de esas alternativas: Laradock.

Por qué usar Laradock

Dentro de todas las alternativas existentes para la creación de contenedores de Docker como entornos de desarrollo, la más conocida actualmente es Laradock, a juzgar por su popularidad en GitHub, que es mayor que cualquier otra y con mucha diferencia.

Si lo comparas con Laravel Sail, Laradok tiene una increíble cantidad de servicios configurados de casa, mientras que Sail solo ofrece media docena de ellos. Es cierto que son los más importantes pero en ocasiones puede que no sean los necesarios para tus proyectos.

Además Laradock potencialmente lo puedes usar para cualquier tipo de proyecto PHP que tengas entre manos y no solo para Laravel.

Cómo configurar Laradock en un proyecto Laravel

Vamos a mostrar los pasos para usar Laradock en un proyecto Laravel existente.

Instalar Docker Desktop

Para poder hacer este tutorial tienes que tener instalado Docker Desktop en tu ordenador.

• Este proceso es inmediato en MacOS, ya que simplemente tienes que instalar el programa en tu sistema operativo host.
• Si estás en Linux, también resulta bastante sencillo también instalando el programa Docker Desktop
• Más complicado resulta para los usuarios de Windows, ya que deben hacer trabajar Docker Desktop dentro de WSL2 (Windows Subsystem Linux 2). En el artículo de Laravel Sail explicamos cómo configurar WSL2 en Windows.

Clonar Laradock dentro de tu proyecto Laravel

Dentro de la carpeta de tu proyecto Laravel, clona el repositorio de Laradock:

git clone https://github.com/Laradock/laradock.git

No te preocupes por el hecho de clonar un repositorio dentro de un proyecto donde probablemente ya estás utilizando git, esto es perfectamente posible y no causará ningún problema. Incluso herramientas como Visual Studio Code, que tienen la gestión de Git integrada dentro del mismo editor ofrecen una perfecta gestión de ambos repositorios en el mismo proyecto.

En la siguiente imagen apreciarás cómo aparecerá la pantalla de control de código con git dentro de Visual Studio Code y cómo se distinguen perfectamente ambos repositorios que se encuentran en la misma carpeta.

Configurar Laradock

Una vez clonado el repo, entra en la carpeta de Laradock y copia el archivo de ejemplo .env:

cd laradock
cp .env.example .env

Ahora abre el archivo .env con tu editor de texto. Encontrarás una cantidad enorme de configuraciones para el proyecto que tendrás que ajustar a tus necesidades.

Por ejemplo, podrías necesitar especificar la versión de PHP que necesitas usar.

PHP_VERSION=7.4

Ten en cuenta que si cambias la versión de PHP después de haber realizado el arranque de los contenedores por primera vez, será necesario que vuelvas a construirlos de nuevo. Más tarde en este artículo vamos a abordar ese caso.

Para ajustar la versión de tu sistema gestor de base de datos tienes que acudir al bloque correspondiente y configurar las variables de entorno disponibles. Por ejemplo podrías necesitar MariaDB en determinada versión, entonces defines la variable de entorno MARIADB_VERSION

MARIADB_VERSION=10.3.36

Configurar la base de datos

Otro asunto importante que debemos configurar es el sistema gestor de base de datos que queremos utilizar, de entre todos los que nos permite Laradock.

Es bien simple esta configuración puesto que simplemente tenemos que hacer coincidir los datos del .env de nuestra aplicación Laravel con los datos del .env que hay en la carpeta de Laradock.

Por ejemplo para MariaDB los datos del .env en el directorio Laradock podrían tener esta pinta:

MARIADB_VERSION=latest
MARIADB_DATABASE=mibase
MARIADB_USER=miusuario
MARIADB_PASSWORD=secret
MARIADB_PORT=3306
MARIADB_ROOT_PASSWORD=root

Mientras que los datos del .env del proyecto Laravel podrían ser así:

DB_CONNECTION=mysql
DB_HOST=127.0.0.1
DB_PORT=3306
DB_DATABASE=mibase
DB_USERNAME=miusuario
DB_PASSWORD=secret

Configurar el archivo docker-compose.yml

Ahora puedes echar un vistazo al archivo docker-compose.yml que hay en la carpeta de Laradock.

En este archivo en realidad probablemente no tengas que hacer nada en especial, simplemente verificar los nombres de los servicios que quieres levantar, que se encuentran presentes.

Si tienes que configurar algún puerto también sería el lugar adecuado para hacerlo.

Arrancar los contenedores

Ahora, desde la carpeta de Laradock debes lanzar el comando de consola que inicia los contenedores. En este punto necesitarás indicar cuáles son los servicios necesarios para tu aplicación.

En una configuración básica, en la que solamente necesites iniciar Nginx con PHP y MariaDB, puedes ejecutar:

docker compose up -d nginx mariadb

En versiones más antiguas de Docker el comando "docker compose" tenía un guión en medio. Si no te va el anterior comando prueba este:

docker-compose up -d nginx mariadb

Esto iniciará los contenedores en modo "detached" y liberará el terminal para que puedas seguir escribiendo comandos. Nota que no es necesario referenciar que queremos PHP porque ya está incluido de manera predeterminada en el servicio de Nginx.

La primera vez que lances este comando para arrancar los contenedores se descargarán las imágenes de Docker necesarias para funcionar. El proceso puede tardar un poco dependiendo de tu conexión a Internet e incluso de la capacidad de procesamiento de tu ordenador.

Ten en cuenta que debes tener los puertos libres para que se puedan arrancar los servicios que has solicitado.

Cuando necesites parar los contenedores, una alternativa es hacerlo desde la interfaz de usuario de Docker Desktop. También se detienen con el comando siguiente.

docker-compose down

Nota sobre la carpeta del proyecto Laravel

Ten en cuenta que tu proyecto Laravel debe estar localizable por Nginx. Si has publicado Laradock como una carpeta directamente dependiente de la raíz del proyecto Laravel no tienes que hacer nada en particular, pero si está en otra ruta debes ajustar la ruta del host.

En el archivo .env de Laradock tendrás que editar esta configuración:

APP_CODE_PATH_HOST=../

Para colocar algo como:

APP_CODE_PATH_HOST=../ruta_proyecto_laravel

No hace falta hacer referencia a la carpeta "public".

Ten en cuenta que si has modificado el archivo .env de Laradock tendrás que arrancar de nuevo los contenedores. Primero nos paramos con el siguiente comando:

docker-compose down

Y luego volvemos a arrancar con el comando que sea necesario según los servicios que necesites.

Ejecutar comandos de Composer

Generalmente querrás usar Composer en tus aplicaciones PHP. Para conseguirlo simplemente necesitas arrancar un terminal para ejecutar comandos dentro del contenedor y luego invocar los comandos de Composer.

Con este comando conseguimos abrir una sesión bash en el contenedor, de modo que tendremos acceso al contenedor desde el terminal.

docker-compose exec workspace bash

Luego podemos ejecutar ya el comando composer:

composer install

Acceder a tu proyecto

Ahora vamos a ver cómo podrás acceder a tu proyecto y ejecutarlo desde el navegador. Para poder realizar este paso tienes que haber cubierto los pasos anteriores, es decir:

• Los contenedores estén levantados
• Los servicios se hayan arrancado
• Hayas instalado las dependencias de Composer
• Hayas realizado otros requisitios de tu proyecto, como por ejemplo construir el .env de la aplicación Laravel.

Entonces podrás acceder ya mismo al proyecto Laravel usando el navegador, escribiendo http://localhost

Si quieres puedes acceder a través de un dominio "falso" si editas las configuraciones de tu archivo de hosts.

Uso de Artisan y otros comandos de Laravel

Otra cosa que vas a necesitar seguro es ejecutar comandos de "artisan". Para ello debes iniciar una sesión bash en el contenedor y luego ejecutar los comandos que necesites.

Primero tienes que entrar en la carpeta donde tienes Laradock instalado, con un cd a la carpeta adecuada, que generalmente será:

cd laradock 

Posteriormente lanzarás en tu terminal el proceso para abrir la sesión bash, con este comando concreto:

docker-compose exec workspace bash

Esto te llevará a un shell dentro del contenedor llamado workspace, donde están los archivos del proyecto con el que estás trabajando. Desde esa misma carpeta puedes ejecutar comandos de artisan.

php artisan migrate

Cambiar la versión de PHP

Voy a dar unas rápidas notas sobre el proceso de cambio de la versión de PHP, si es que lo realizas después de haber creado los contenedores de Laradock, ya que en este caso tendrás que volver a construirlos.

Primero tienes que detener los contenedores con el comando:

docker-compose down

Luego puedes realizar el buildd de los contenedores con la nueva configuración de PHP:

docker-compose build --no-cache workspace php-fpm mariadb

Usando --no-cache te asegurarás que las imágenes se tomen de nuevo, evitando posibles fallos al reconstruir los contenedores.

Por último puedes volver a arrancar los servicios con el comando de siempre.

docker-compose up -d nginx mariadb

Abrir una conexión con el servidor de la base de datos por terminal

Es muy habitual que tengas que realizar conexiones con MySQL o MariaDB para lanzar comandos directamente contra el servidor. Si fuera necesario tan solo tienes que seguir estos pasos.

Primero asegúrate de tener arrancados los contenedores, con los comandos que hemos comentado ya repetidas veces en este artículo.

En el terminal abres una conexión con el contenedor "workspace", desde el directorio donde tienes clonado Laradock, con este comando:

docker-compose exec workspace bash

Suponiendo que has instalado MariaDB lanzarás este comando para conectarte al servidor de la base de datos:

mysql -h mariadb -u root -p'root'

Aquí puede que tengas que cambiar el nombre de host si no has instalado mariadb. Puede que tengas que editar también tu usuario y contraseña de acceso, según los datos que hayas usado en el .env de la carpeta de Laradock.

Instalar el cliente mysql en workspace

Eventualmente puede ocurrir que no tengas instalado en el contenedor "workspace" el cliente de mysql para terminal. En ese caso no estará disponible el comando mysql. Si fuera así te saldría una salida como bash: mysql: command not found.

Para solucionarlo entras en el contenedor workspace:

docker-compose exec workspace bash

Luego instalas el software necesario:

apt-get update
apt-get install -y mysql-client

Configurar un programa de UI para administrar la base de datos

Si lo prefieres puedes usar un programa de interfaz gráfica para administrar tu base de datos. En este caso usarás los datos de conexión:

• Host: 127.0.0.1
• Usuario, contraseña y base de datos: lo que hayas colocado en el .env
• Puerto: generalmente 3306 para MySQL / MariaDB.

Si no te funcioa verifica los datos de autenticación y que el contenedor de la base de datos esté arrancado correctamente.

Restaurar un backup de MySQL en el servidor de base de datos de Laradock

Si deseas restaurar un backup de sentencias SQL que tengas a mano para poblar tu base de datos, lanza los siguientes comandos:

Copiado del respaldo de la base de datos en el contenedor:

docker cp /Users/midesweb/sites/backup_desarrolloweb/backup.sql laradock_workspace_1:/tmp/

Revisa cuál es el nombre real del contenedor de Workspace con el comando docker ps.

Una vez has importado el archivo SQL al contenedor workspace abres sesión en ese sistema:

docker-compose exec workspace bash

Ahora usas el cliente MySQL para restaurar la base de datos, de manera normal, tomando el archivo desde la carpeta donde lo has dejado.

mysql -h mariadb -u user -p'clave' dd_bb < /tmp/backup.sql

Por supuesto, tendrás que adaptar los datos de acceso a lo que hayas configurado en tu .env de Laradock.