Laradock, instalação e configuração

Aprenda agora como instalar e configurar o Laradock, que é, como apresentado no artigo introdutório, um projeto para configuração rápida e simples de ambientes de desenvolvimento de sistemas PHP para web, usando Docker.

Neste artigo tutorial, veremos mais detalhadamente como instalar e configurar um ambiente Laradock ~~para trabalhar por projeto PHP, isto é, uma instalação para cada projeto~~. Ou como usar uma instalação para múltiplos projetos.

~~Ainda é mostrado como configurar instalações para executar diferentes versões do PHP para múltiplos projetos.~~

Requisitos

Os aplicativos e requisitos para instalar, configurar e executar um ambiente Laradock são:

GIT
- O que é Git
- Download no site oficial
Docker: v >= 17.12
- Como instalar Docker
- Site oficial

Instalando Laradock para múltiplos projetos

Esta instalação é destinada a configurar uma instalação do Laradock para que múltiplos projetos possam utilizar a mesma configuração dos contêiners.

Clonar o repositório do Laradoc

Inicie clonando o repositório do Laradock em qualquer lugar de sua máquina - eu aconselho a clonar na pasta onde mantém seus projetos, no mesmo nível deles:

cd my-workspace
git clone https://github.com/laradock/laradock.git

A estrutura de suas pastas deve ficar parecida com a seguinte:

- my-workspace
  - laradock
  - projeto-a
  - projeto-b
    ...
  - demais-projetos

Editar o arquivo de ambiente

Edite o arquivo de configuração de seu ambiente Docker Laradock. Copie o arquivo .env.example para .env

cd laradock
cp .env.example .env

Abra o arquivo .env e certifique-se de que a variável APP_CODE_PATH_HOST, no início do arquivo, está apontando para o caminho de path anterior:

APP_CODE_PATH_HOST=../

Esta configuração define o caminho das suas aplicações na máquina local, isto significa que estão em um nível anterior de pasta em relação à pasta do Laradock. Por isso você deve fazer o clone como explicado no passo 1.

Configure o arquivo .env com as demais definições que deseja para esta instalação. Como servidor web a utilizar e extensões do interpretador php-fpm e workspace.

Configurar os caminhos dos sites / projetos

Navegue nas pastas da sua instalação Laradock, onde cada subdiretório corresponde contém arquivos de configuração ou Dockerfiles do aplicativo correspondente ao nome da pasta.

Vá para o servidor web que escolheu utilizar: Apache ou NGinx, e crie arquivos de configuração para apontar para diferentes diretórios de projetos da sua máquina que deseja servir com a instalação do Laradock:

Para Nginx vá para nginx/sites, para Apache2 apache2/sites.

O Laradock por padrão inclui alguns arquivos de amostra para você copiar app.conf.example, laravel.conf.example e symfony.conf.example.

Altere os nomes padrão *.conf:

Você pode renomear os arquivos de configuração, pastas de projeto e domínios como desejar, apenas certifique-se de que a raiz nos arquivos de configuração esteja apontando para o nome da pasta de projeto correto.

6.1. Por exemplo: você irá utilizar Apache2 e o nome de uma das aplicações é clientes e está sendo desenvolvido em Laravel:

6.1.1. acesse a pasta apache2/sites da instalação Laradock

6.1.2. copie o arquivo sample.conf.example para clientes.conf

6.1.3. altere o conteúdo da configuração no novo arquivo:

<VirtualHost *:80>
  ServerName clientes.test
  DocumentRoot /var/www/clientes/public/
  Options Indexes FollowSymLinks

  <Directory "/var/www/clientes/public/">
    AllowOverride All
    <IfVersion < 2.4>
      Allow from all
    </IfVersion>
    <IfVersion >= 2.4>
      Require all granted
    </IfVersion>
  </Directory>

</VirtualHost>

Veja como definimos o DocumentRoot e Directory baseados na configuração de arquivos rais de nosso Apache para a instalação Laradock, e apontamos para o subdiretório public pois é uma aplicação Laravel que deve ter seu ponto de acesso neste diretório e não no raiz da aplicação.

Adicione os domínios aos arquivos de hosts.

No arquivo hosts de sua máquina, configure o ip de localhost para apontar para cada projeto configurado em seus arquivos *.conf do servidor web na instalação Laradock.

127.0.0.1  clientes.test
127.0.0.1  outro_projeto.localhost
...

Note que você pode usar extensões para o domínio local como: .localhost, .invalid, .test, or .example. Mas não pode utilizar a extensão .dev.

Leia Extensões de domínio para usar em desenvolvimento local para compreender por quê.

Usando o Laradock

Antes de começar a usar sua recente instalação do Laradock, fique atento ao seguinte:

Se você estiver usando o Docker Toolbox (VM), aconselho usar o Laradock v.4, para isso, atualize para Docker Native para Mac/Windows (recomendado). Se necessário, confira na documentação como atualizar o Laradock.
Recomendo usar de uma versão do Docker mais recente que 1.13.
Se você usou uma versão mais antiga do Laradock, é altamente recomendável reconstruir os contêineres que você precisa. Veja como reconstruir um contêiner na documentação.

Configurar o arquivo de ambiente .env

Após a instalação e configuração base você deve compreender como configurar seu ambiente e os passos para subir os contêineres Docker no dia a dia.

Se ainda não fez, copie o arquivo .env.example para .env e configure as instalações que deseja para os seus serviços Docker, bem como a versão do PHP.

cd laradock
cp .env.example .env

Edite o arquivo .env para escolher qual software deseja instalar em seu ambiente. Você sempre pode consultar o arquivo docker-compose.yml para ver como essas variáveis estão sendo usadas.

Dependendo do sistema operacional do host, pode ser necessário alterar o valor fornecido para COMPOSE_FILE. Quando você está executando o Laradock no Mac OS, o separador de arquivo correto a ser usado é :. Ao executar o Laradock a partir de um ambiente Windows, vários arquivos devem ser separados com ;.

Por padrão, os contêineres que serão criados têm o nome do diretório atual como sufixo (por exemplo, laradock_workspace_1).

Isso pode causar “mistura de dados” dentro dos volumes do contêiner se você usar o laradock em vários projetos. Para evitar isso altere a variável COMPOSE_PROJECT_NAME para algo único, como o nome do seu projeto.

Eu mantenho o valor laradock mesmo para todos os meus projetos em uma instalação compartilhada de Laradock.

# Define the prefix of container names. 
# This is useful if you have multiple projects that use laradock 
# to have separate containers per project.
COMPOSE_PROJECT_NAME=laradock

Isto por quê não utilizo sobreposição de caminhos ou nome de databases nos bancos de dados. Outro motivo para usar o mesmo nome neste caso é o de compartilhar contêineres de serviço, como o mysql, entre versões diferentes de php-fpm.

Iniciar os contêineres Docker

Crie o ambiente e execute-o usando docker-compose

Neste exemplo, veremos como executar NGINX (servidor da web), MySQL (mecanismo de banco de dados) para hospedar scripts da Web em PHP e REDIS (banco de dados em memória para cache):

docker-compose up -d nginx mysql redis

Deseja trabalhar com APACHE (servidor web), MONGODB (mecanismo de banco de dados não relacional) e REDIS ?

docker-compose up -d apache mongodb redis

Nota: Todos os contêineres de servidores web nginx, apache ..etc dependem do php-fpm, o que significa que se você executar qualquer um deles, eles irão iniciar automaticamente o contêiner php-fpm. Desta forma não é necessário chamar explicitamente no comando up o php-fpm.

Se você tiver que fazer isso, pode ser necessário executá-los da seguinte maneira:

docker-compose up -d nginx php-fpm mysql

Minha configuração mais comum para uso dos contêineres é com apache e mariadb ou apache e postgresql. Sem esquecer que sempre utilizo Redis também:

docker-compose up -d apache2 workspace redis mariadb

No exemplo acima você pode alterar mariadb por postgresql ou ainda usar a extensão postgis (com esse nome mesmo).

Você pode selecionar sua própria combinação de containers existentes, listados aqui.

Atenção: nem sempre esta lista está atualizada, portanto, verifique o arquivo docker-compose.yml para conferir a listagem completa de todos os contêineres disponíveis.

Executando composer e php artisan

Entre no container do Workspace, usando um terminal shell, onde poderá executar comandos como: Artisan, Composer, PHPUnit, Gulp, Node, Npm, etc.

Você pode escolher usar Bash:

docker-compose exec workspace bash

Eu prefiro usar um terminal Zsh:

docker-compose exec workspace zsh

Como alternativa, para usuários do Windows PowerShell: execute o seguinte comando para acessar o terminal de qualquer contêiner em execução:

docker exec -it {workspace-container-id} bash

DICA: Oriento você a acessar os contêineres com o usuário padrão, laradock, a fim de que os arquivos criados tenham o nível de permissão adequado. Se acessar sem definir o usuário, root é usado.

Para acessar como usuário laradock, adicione --user = laradock. Exemplo:

docker-compose exec --user=laradock workspace bash

Porém, se necessitar acessar um contêiner com acesso privilegiado, não informe o usuário.

Configure o seu projeto

Atualize a configuração do seu projeto para usar o servidor do banco de dados, o serviço Redis, e outros que instalou e subiu.

Abra o arquivo .env do seu projeto PHP ou qualquer arquivo de configuração que seu projeto usa, e defina o host do banco de dados DB_HOST como mysql.

Você precisa usar as credenciais de banco de dados padrão do Laradock, que podem ser encontradas no arquivo .env (ex: MYSQL_USER =). Ou você pode alterá-los e reconstruir o contêiner.

Um exemplo de .env de um projeto Laravel configurado para acessar Mysql de um contêiner Laradock:

DB_CONNECTION=mysql
DB_HOST=127.0.0.1
DB_PORT=3306
DB_DATABASE=meubd
DB_USERNAME=default
DB_PASSWORD=secret

Acesse seu projeto

Acesse seu projeto em seu navegador, visite o endereço de seu host local de acordo com a configuração de site que você definiu.

No exemplo deste artigo o caminho do projeto no navegador seria http://clientes.test.

A seguir veja como configurar algumas das opções o .env

Configurações do arquivo .env

Algumas configurações que valem a penas ser mencionadas e devem ser verificadas por você, ajustadas se necessário, no arquivo de ambiente.

Note que as configurações específicas para habilitar ou não o uso de cada aplicação deve ser realizado para que você possa usar seus contêineres.

Por exemplo, para habilitar o uso do XDEBUG no Workspace, deve ir até a seção WORKSPACE e alterar a variável WORKSPACE_INSTALL_XDEBUG para true.

O mesmo vale para extensões que devem estar disponíveis para o PHP-CLI no WORKSPACE.

Para habilitar as extensões no PHP-FPM, navegue até a sua seção e habilite as extensões que deseja para o contêiner do PHP-FPM.

APP_CODE_PATH_HOST

Ela define o caminho do código do seu(s) aplicativo(s) em seu host (sua máquina e não o contêiner).

Você deverá alterar ela de acordo com a estratégia de instalação do Laradock, veja as seções anteriores para entender que valores utilizar.

A lista está organizada em ordem alfabética, porém as variáveis estão dispostas em ordem diferente no arquivo .env.

DATA_PATH_HOST

Define o caminho de armazenamento em sua máquina.

Para todos os sistemas de armazenamento. Isto significa que os arquivos bancos de dados, caches, e outros arquivos de uso nos aplicativos instalados em seus contêineres serão armazenados neste path.

As aplicações usarão seus subdiretórios a partir desta configuração, por padrão ela é ~/.laradock/data. Isto é, a partir de sua pasta /home/seuusuario/ é criado o diretório oculto para configurações e dados.

Caso esteja utilizando a estratégia de uma instalação Laradock por versão PHP, ou mesmo uma instalação por projeto, pode manter a mesma configuração de caminho de dados para todas as instalações. Desta maneira poderá compartilhar arquivos de banco de dados e outros.

COMPOSE_PROJECT_NAME

Define o prefixo dos nomes dos contêineres. Isso é útil se você tiver vários projetos que usam Laradock para ter contêineres separados por projeto. Ou mesmo se usa uma instalação por versão PHP.

PHP_INTERPRETER

O interepretador PHP que deseja usar, podendo ser hhvm ou php-fm. Confesso que somente utilizei o php-fpm.

PHP_VERSION

Define a versão PHP do espaço de trabalho (workspace) e contêineres PHP-FPM (não se aplica a HHVM).

Para cada instalação Laradock, quando usando uma por versão, você pode configurar uma versão diferente para o PHP, porém manter a mesma versão para, por exemplo, o sistema gerenciador de banco de dados MySQL.

Esta estratégia permite subir contêineres em versões PHP diferentes porém que compartilham os mesmos contêineres para os demais aplicativos. Esta é a beleza do Docker.