> Manuales > Manual de Laravel 5

Procedimiento de instalación del entorno de desarrollo ideal para la creación de aplicaciones usando el framework PHP Laravel y la virtualización de una máquina con Vagrant y Homestead.

En este artículo vamos a ofrecer las pautas para contar con el mejor entorno de desarrollo posible para Laravel 5, el más profesional, fácil de instalar y de mayor versatilidad, ayudándonos de la virtualización de la máquina de desarrollo y Vagrant.

La fórmula tiene el nombre de Homestead, una herramienta oficial creada por el equipo de Laravel para facilitar la vida a los desarrolladores que quieran usar este framework PHP para comenzar un proyecto rápidamente.

La idea es que los desarrolladores tengamos que implementar el menor número de configuraciones en nuestras máquinas y que con dos o tres comandos podamos conseguir todo lo que necesitaría el entorno de desarrollo más exigente.

Nota: Con este texto damos inicio al Manual de Laravel 5, en el que pretendemos enseñar a los lectores a trabajar con este importante framework PHP. Así que siéntate cómodo y aprovecha para comenzar con nosotros esta zambullida en profundidad a Laravel 5.1.

Qué es exactamente Homestead

Es una "Box de Vagrant". Por si no lo sabes, Vagrant es una capa por encima de Virtualbox (o de otros sistemas de virtualización como VMWare) que nos sirve para crear entornos de desarrollo y las Box en su terminología son imágenes de sistemas operativos ya instalados. Generalmente vienen "peladas", tal como tendríamos el ordenador si hubiéramos acabado de instalar el sistema operativo en ese momento. O en algunos casos, como Laravel Homestead, ya configurados con distintos paquetes de software.

Homestead te instala software como: Ubuntu, PHP, HHVM, Nginx, MySQL, PostgreSQL, NodeJS, Redis y algunas librerías como Memcached, Laravel Envoy, Beanstalkd...

Por qué Homestead

Porque la comunidad de creadores de Laravel quieren acercarte al framework. Facilitarte no solo la entrada como desarrollador de Laravel, sino también proporcionarte el entorno de desarrollo más adecuado para acometer cualquier tipo de proyecto.

Realmente puedes contar con Laravel funcionando en un Xampp, Mamp o similares, pero si virtualizas tendrás varias ventajas como contar con un entorno mucho más parecido al de producción, independiente de otros proyectos con los que estés desarrollando y además el mismo sistema, con los mismos paquetes de software. No tiene sentido extenderse mucho en las ventajas de los entornos virtualizados, porque ya hemos hablado de ellos en otras ocasiones. Pero piensa además que puedes conseguir todo eso con la facilidad de lanzar unos pocos comandos para generar automáticamente toda la infraestructura perfectamente configurada.

Qué necesitas

Instalar VirtualBox como sistema de virtualización, o VMware si lo prefieres (aunque en ese caso tendrías que instalar un plugin adicional). Luego instalas Vagrant. Ambos programas son gratuitos y multiplataforma.

Una vez instalados ambos programas (Primero se recomienda instalar Virtualbox y luego Vagrant) se debe descargar la caja "Box" de Homestead, para lo que lanzarás el siguiente comando de consola.

vagrant box add laravel/homestead

Ese comando lo podrás lanzar desde cualquier carpeta, desde el terminal de línea de comandos, claro está.

Nota: Si tienes una versión antigua de Vagrant quizás tengas que darle la URL completa de la localización de la Box.
vagrant box add laravel/homestead https://atlas.hashicorp.com/laravel/boxes/homestead

Instalar Homestead

El tercer paso sería instalar el propio Homestead. Para ello usaremos la box que acabamos de descargar y Vagrant. Pero necesitamos un archivo de configuración que se encuentra en Github que contiene toda la información de configuración que Vagrant necesitaría para generar y aprovisionar la máquina virtual para desarrollar con Laravel.

Para ello abrimos un terminal y nos situamos en nuestra carpeta de proyectos habitual y desde allí clonaremos el repositorio de Homestead con Git.

git clone https://github.com/laravel/homestead.git Homestead

Nota: Ese comando clona un repositorio. El repositorio está en Github en la ruta https://github.com/laravel/homestead.git. El parámetro final del comando anterior git clone que está definido como "Homestead" es la carpeta donde va a colocar los archivos del repositorio que estás clonando. Si quisieras podrías cambiarle el nombre a la carpeta de destino, por ejemplo, "proyecto-prueba" en vez de "Homestead", para lo que el comando sería el siguiente:
git clone https://github.com/laravel/homestead.git proyecto-prueba
La estructura de carpetas que tengas tú en tu ordenador de momento es indiferente y responderá a tus propias preferencias. Lo que te interesa es todo lo que tiene el repositorio, que te vas a descargar con el comando "git clone". El lugar donde esté localizada la carpeta donde te descargas el repo de Homestead es lo de menos, por ejemplo muchas personas prefieren colocarla en la carpeta "Dropbox" para que cuando se realicen cambios en el proyecto se realicen copias de seguridad automáticas en la nube.

Dentro de ese repositorio clonado tenemos en un archivo bash con el nombre "init.sh" que tiene el código con los comandos para crear el archivo de configuración Homestead.yaml. Simplemente lo tienes que ejecutar, con el comando:

bash init.sh

Obviamente el comando "bash init.sh" lo debes ejecutar desde la ruta donde se encuentra el archivo init.sh, en la carpeta del repositorio que acabas de clonar. Verás que simplemente te da un mensaje de respuesta "Homestead initialized!". Eso quiere decir que ha ido bien y ha podido crear los archivos de configuración necesarios para los siguientes pasos.

Entre los arhivos de configuración que se crean al ejecutar el init.sh hay uno que necesitarás editar, llamado "Homestead.yaml". Este archivo de configuración lo encontrarás en tu carpeta personal (la de tu usuario dentro de tu sistema operativo) y dentro de ella en la carpeta oculta ".homestead". Si lo abres podrás encontrar los datos de configuración de la máquina virtual Homestead, el servidor de desarrollo virtualizado que vamos a crear, que incluye datos como la IP del servidor, las CPUs, memoria asignada, carpetas que se compartirán entre la máquina de desarrollo y el ordenador anfitrión (nuestro ordenador físico) y cosas así.

Nota: Por ejemplo en Mac mi directorio del usuario personal es /Users/midesweb y la carpeta .homestead estará por tanto en /Users/midesweb/.homestead

En un principio necesitamos tocar pocas cosas del Homestead.yaml, porque la mayoría ya se ha configurado automáticamente, acorde con nuestro sistema operativo gracias al archivo init.sh, pero podrás desear cambiar los siguientes item:

Crear la llave de SSH

Esta es la llave para la conexión con el servidor virtual por línea de comandos. Si no tienes una la puedes crear. Desde Mac o Linux es tan sencillo como lanzar el siguiente comando:

ssh-keygen -t rsa -C "you@homestead"

Desde Windows la recomendación es usar el "Bash de Git" (el programa de terminal que te viene incorporado cuando instalas Git) y lanzar el mismo comando anterior. Aunque también podrías usar el popular software PuTTY y PuTTYgen.

En el anterior comando no necesitas editar nada, lo pones tal cual. Enseguida verás que el programa que te genera la clave te pide la ruta donde va a colocar esta key generada. El propio programa te muestra una ruta predeterminada donde sugiere se coloquen las llaves. Podemos pulsar enter sin escribir nada para aceptar esa ruta o bien escribir cualquier otra ruta donde se generará la clave. Puedes poner lo que quieras, con tal que te acuerdes de la ruta que has seleccionado.

Nota: en cuanto a la ruta donde se van a colocar las claves es totalmente personalizable. Pon la que quieras, simplemente acuérdate donde están los archivos. Para ser más específicos y por si alguien se pierde, pueden darse tres casos:
  • Que te parezca bien la ruta donde te sugiere que va a crear las claves. En ese caso puedes apretar enter y listo. En mi caso la ruta donde se colocarían las claves de manera predeterminada es /Users/midesweb/.ssh/id_rsa. Por tanto se crearán los archivos id_rsa e id_rsa.pub en la carpeta /Users/midesweb/.ssh.
  • Que escribas el nombre de un archivo simplemente, algo como "homesteadkey". En ese caso te creará las claves en el directorio donde estás situado cuando hiciste el comando ssh-keygen, archivos homesteadkey y homesteadkey.pub.
  • Que que escribas una ruta absoluta, algo como /Users/midesweb/.ssh/nuevaclave, en cuyo caso te colocará la clave en esa ruta absoluta, tanto la clave privada /Users/midesweb/.ssh/nuevaclave como la pública /Users/midesweb/.ssh/nuevaclave.pub

El programa de generar las key te pedirá también insertar una frase como clave, que puedes poner la que desees. O bien una cadena vacía si quieres ahorrarte indicar una frase que te puedas olvidar. Como es solo para trabajar en local sería suficiente.

Como decíamos, una vez generada la clave lo que te interesa es saber la ruta donde se ha colocado, que tendrás que usar para configurar el archivo Homestead.yaml.

El lugar donde vas a tener que introducir la ruta de la clave será algo como esto:


authorize: ~/.ssh/id_rsa.pub

keys:
    - ~/.ssh/id_rsa

Esa ruta es la que tienes que configurar según la localización de las llaves creadas. Generalmente si seleccionaste la carpeta predeterminada que sugería el comando ssh-keygen ni siquiera tendrías que editar nada. Si las claves las guardaste en otro lugar, entonces tendrás que indicarlo aquí. De todos modos, no tiene ninguna complicación, es saber la ruta donde está tu clave e indicarla en el Homestead.yaml.

Nota: Recuerda que ~/ es un alias de tu ruta personal (ver otra nota más abajo donde se habla sobre este tema). Pero si te lía lo puedes cambiar por una ruta absoluta y punto.

Carpetas del servidor virtual y mapeo a las carpetas locales

Una de las características de los entornos con Vagrant es que hay determinadas carpetas del servidor virtual (invitado) que están mapeadas a directorios locales de tu máquina real (anfitrión). Esto te permite editar archivos de tu proyecto como los editarías en cualquier otra situación, con tus editores de código preferidos, trabajando en local como si lo hicieras con un sistema más tradicional tipo Xampp o Mamp, Wamp, etc. Las carpetas locales están enlazadas con las carpetas del servidor, por lo que no tienes que subir los archivos por FTP, SCP ni nada parecido. Cuando modifiques algún archivo, o crees archivos nuevos en tu carpeta local, automáticamente esos cambios serán producidos en las carpetas enlazadas del servidor virtualizado. Podrías configurar tantas carpetas compartidas como necesites en tu proyecto.

Ahora en el archivo Homestead.yaml tendrás que definir esa estructura de carpetas, que se adaptará a tus costumbres habituales. Como hemos comentado antes, tendrás una carpeta de tu ordenador donde guardas tus proyectos y seguirá siendo así. Por tanto, es simplemente guardar este proyecto en una carpeta en una ruta habitual para ti.

folders:
    - map: ~/carpeta_de_proyectos/proyecto_x/codigo
      to: /home/projects

En este lugar colocamos en "map" el valor de nuestra carpeta en el ordenador anfitrión y en "to" la ruta de la carpeta del ordenador virtualizado que vamos a crear con Vagrant y Homestead. La carpeta que estás indicando en "map", que corresponde con tu ordenador real, debería existir.

Ten en cuenta que en una máquina virtual de Homestead podrías mantener varios proyectos Laravel, por tanto no sería descabellado que usases una declaración Folders abierta a esa posibilidad, donde mapeas una carpeta de proyectos en el anfitrión a otra de proyectos en la máquina virtual.

folders:
    - map: ~/carpeta_instalacion_homestead/proyectos/
      to: /home/vagrant/proyectos/
Nota: Una aclaración acerca de las rutas para los de Windows. "~/" corresponde con la carpeta raíz de tu usuario. Por ejemplo, si tu usuario (con el que entras en Windows es ·micromante" esa ruta correspondería con una carpeta como "C:/Users/micromante". La carpeta "~/.homestead" correspondería físicamente con "C:/Users/micromante/.homestead". Si usas el terminal básico del Windows no reconocerá la ruta ~/, así que tendrás que usar la ruta real de tu carpeta de usuario, la física o ruta real. Si usas un terminal un poco mejor, por ejemplo el Git Bash sí que te reconocerá ese nombre lógico ~/ y te llevará a tu carpeta de usuario, sea cual sea tu nombre de usuario, igual que ocurre en el terminal de Linux o Mac.

De nuevo, no hay necesidad de colocar algo específico en la sección folders, sino que será tal como tú desees organizar las carpetas, tanto en el servidor Homestead como en tu ordenador local.

Definir la configuración de los sitios que vamos a albergar en esta máquina Homestead

Nos queda un valor que configurar, que es el nombre del host virtual que nos va a configurar Homestead en esta máquina virtual que estamos a punto de crear. Este host virtual o "virtualhost" lo usaremos para entrar en el proyecto desde un navegador, con un nombre de dominio, como si fuera un servidor remoto. Lógicamente ese dominio solo estará disponible desde tu ordenador y tendrás que configurar el conocido archivo "hosts" para asociar la IP del servidor al nombre de dominio virtual.

sites:
    - map: homestead.dw
      to: /home/projects/mi_proyecto/public

En este caso en "map" colocamos el nombre de dominio para el virtualhost y en "to" indicamos la carpeta del servidor virtual donde va a estar el "document root". Si te fijas, ese document root debe colgar de la carpeta que tienes en la máquina virtual que has enlazado con tu carpeta real, de ese modo podrás editar en local los archivos de tu proyecto que se servirá desde el ordenador virtual.

Nota: En una instalación de Homestead serías capaz de albergar varios proyectos si así lo deseas, con diversos host virtuales. Insistimos en que cada uno de los host virtuales tendrás que configurarlo en el archivo de hosts de tu ordenador, asociando la IP que hayas configurado para esta máquina virtual con el nombre de dominio de tus virtualhost.

Tu archivo hosts tendrás que editarlo agregando esta líneas, que quedará más o menos de esta forma:

192.168.10.10	homestead.dw

Aunque lógicamente, tendrás que poner la IP que hayas definido en el campo IP de Homestead.yaml y el nombre de dominio que hayas definido en los "sites", en el campo "map".

Nota: La configuración del archivo Hosts está explicada en el artículo: Modificar el archivo de Hosts en Windows, Linux y Mac

Lanzar la máquina virtual

Una vez configurado el Homestead.yaml tienes que lanzar la máquina virtual, es decir, tendrás que ponerla en marcha, con el conocido comando de Vagrant:

vagrant up

Ese comando lo tienes que lanzar desde la carpeta donde has puesto el repositorio de Homestead, que clonaste con Git. La primera vez que se ejecute va a tardar un poco, porque tiene que instanciar y configurar toda la máquina, pero luego iniciar la máquina virtual será muy rápido, también con el comando "vagrant up".

Nota: En los comentarios del artículo nos han preguntado en qué momento hacer el "vagrant init". Ese comando no lo necesitas hacer tú mismo. Sirve para que se cree el Vagrantfile y configurar una carpeta para que albergue una máquina virtual que vas a crear con Vagrant. Pero básicamente el Vagrantfile es lo que te descargas al clonar el repositorio y las configuraciones que necesita Vagrant y que realizas predeterminadamente al hacer al "Vagrant init" son las que has aprendido a definir en el archivo Homestead.yaml.

Por tanto, si en algún momento haces un "vagrant up" y te pide hacer un "vagrant init" es que estás haciendo el "vagrant up" desde una carpeta incorrecta. En ese caso fíjate que estés situado en el repositorio de Homestead que has clonado. En esa carpeta debería haber un Vagrantfile, ya que es uno de los archivos del repositorio clonado.

Una vez lanzada la máquina virtual podríamos hacer una primera prueba accediendo a la IP del servidor virtual con tu navegador.

http://192.168.10.10/

(Ojo, la URL podría ser otra si tocaste en el Homestead.yaml el dato ip: "192.168.10.10". Si no es esa, será la IP que hayas configurado en tu caso)

De momento no veremos nada, pero al menos el navegador no deberías recibir tampoco el típico error del navegador para informar que el host no ha sido encontrado. En mi caso aparece el mensaje "No input file specified.". Esto es porque no tenemos todavía ningún archivo en el servidor, como código del proyecto, así como tampoco se ha creado la carpeta "public" que es "document root", o aquella carpeta raíz que hayas configurado en el yaml.

Ahora se trataría de colocar un archivo dentro de la carpeta que has definido como raíz de tu dominio en el campo "to:" de la configuración "sites". Recuerda que esa carpeta está enlazada desde el servidor virtual con una ruta en tu directorio de los proyectos, tal como se ha configurado.

Puedes colocar un index.php con un "Hola mundo" para probar. Lo colocarás en una ruta tal como lo hayas configurado en tu caso, siguiendo los valores definidos en este artículo nos quedaría una como esta:

Ordenador vitualizado:

/home/projects/mi_proyecto/public

Equivalente en el host anfitrión (ordenador real):

~/carpeta_de_proyectos/codigo/mi_proyecto/public

Ahora accediendo a la IP del servidor podrías encontrar tu index.php. Además, si has podido configurar correctamente tu virtualhost, podrás acceder a partir del nombre del dominio creado en tu máquina.

http://homestead.dw/

Con esto es todo, de momento tenemos nuestra máquina funcionando, lista para instalar Laravel, pero aún nos queda toda la instalación del framework PHP Laravel y algún trabajo más para comenzar a desarrollar. Lo veremos en próximos artículos.

Antes de acabar sería solo comentar que tenemos un #programadorIO sobre Laravel Homestead que amplía la información relatada en este artículo. Recuerda también que puedes encontrar la documentación oficial de Homestead para Laravel 5 en este enlace.

Código completo del Homestead.yaml

En los comentarios del artículo nos han pedido reproducir el código completo de un archivo Homestead.yaml. La verdad es que no lo habíamos hecho porque las configuraciones dependen mucho de las preferencias, costumbres, sistemas operativos y rutas de cada uno, por lo que no sería adecuado hacer un "copia-pega" del archivo. Para evitar confusiones y posibles copias literales lo habíamos dejado pasar. No obstante, para que sirva de referencia para comparar vuestros archivos con los nuestros, dejo aquí el código completo.

---
ip: "192.168.10.10"
memory: 2048
cpus: 1
provider: virtualbox

authorize: ~/.ssh/id_rsa.pub

keys:
    - ~/.ssh/id_rsa

folders:
    - map: ~/html/Homestead/codigo
      to: /home/projects

sites:
    - map: homestead.dw
      to: /home/projects/homestead/public
    - map: testlaravel.com
      to: /home/projects/testlaravel/public

databases:
    - homestead

variables:
    - key: APP_ENV
      value: local

# blackfire:
#     - id: foo
#       token: bar
#       client-id: foo
#       client-token: bar

# ports:
#     - send: 93000
#       to: 9300
#     - send: 7777
#       to: 777
#       protocol: udp

Carlos Ruiz Ruso

Consultor tecnológico para el desarrollo de proyectos online especializado en Wo...

Manual