Como desenvolver um site Drupal 9 em sua máquina local usando Docker e DDEV

O autor selecionou a Diversity in Tech Fund​​​​​ para receber uma doação como parte do programa Write for DOnations.

Introdução

O DDEV é uma ferramenta de código aberto que usa o Docker para criar ambientes de desenvolvimento locais para muitos frameworks PHP diferentes. Usando o poder da conteinerização, o DDEV pode simplificar muito como você trabalha em vários projetos que usam várias pilhas de tecnologia e servidores em nuvem. O DDEV inclui modelos para o WordPress, Laravel, Magento, TYPO3, Drupal e muito mais.

O Drupal 9 foi lançado em 3 de junho de 2020 para o Drupal CMS. Conhecido pela facilidade de uso e por uma grande biblioteca de módulos e temas, o Drupal é um framework PHP popular para construir e manter vários sites e aplicações de todos os tamanhos.

Neste tutorial, você começará a desenvolver um site Drupal 9 em sua máquina local usando o DDEV. Isso permitirá que você construa seu site primeiro e, depois, quando tudo estiver pronto, implantar o projeto em um servidor de produção.

Pré-requisitos

Para completar este tutorial, você precisará de:

• Uma máquina local executando o Linux ou o macOS

• Para o macOS: o gerenciador de pacotes Homebrew, que você usará para instalar o DDEV. Para instalar o Homebrew em sua máquina local, siga o Passo 3 — Instalando e configurando o Homebrew neste tutorial do Ruby.

• Docker e Docker Compose instalados em sua máquina local.

  • Para o Linux: você pode instalar o Docker e o Docker Compose seguindo esses dois tutoriais: How to Install and Use Docker e How to Install Docker Compose. Escolha sua distribuição Linux na lista e siga as instruções incluídas.
  • Para o macOS: o Docker Compose estava disponível anteriormente como parte do Docker Toolbox, mas o Docker Toolbox é agora uma solução legada. Hoje, a Docker recomenda oficialmente que você instale o Docker Desktop, que inclui o Docker Compose, o Docker Engine, e muito mais. Siga o guia oficial da Docker para instalar o Docker Desktop no macOS. Para mais informações, você pode ler o guia de primeiros passos oficial do Docker Desktop. Se você usou anteriormente o Docker Toolbox para instalar várias ferramentas do Docker, leia este artigo oficial sobre as diferenças entre o Docker Toolbox e o Docker Desktop e como eles podem coexistir.

Passo 1 — Instalando o DDEV

Neste passo, você irá instalar o DDEV em sua máquina local. A Opção 1 inclui instruções para o macOS enquanto a Opção 2 fornece instruções para o Linux. Este tutorial foi testado no DDEV versão 1.15.0.

Opção 1 — Instalando o DDEV no macOS

O DDEV aconselha que os usuários do macOS instalem sua ferramenta usando o gerenciador de pacotes Homebrew. Use o comando brew a seguir para instalar a versão estável mais recente:

brew tap drud/ddev && brew install drud/ddev/ddev

Se você preferir a versão mais recente absoluta, você pode usar o brew para instalar o ddev-edge:

brew tap drud/ddev-edge && brew install drud/ddev-edge/ddev

Se você já tiver uma versão do DDEV instalada, ou se quiser atualizar sua versão, desligue o DDEV e use o brew para atualizar sua instalação:

ddev poweroff
brew upgrade ddev

Depois de instalar ou atualizar o DDEV, execute ddev version para verificar o software:

ddev version

Você verá uma saída como esta:

Output
DDEV-Local version	v1.15.0
commit            	v1.15.0
db                	drud/ddev-dbserver-mariadb-10.2:v1.15.0
dba               	phpmyadmin/phpmyadmin:5
ddev-ssh-agent    	drud/ddev-ssh-agent:v1.15.0
docker            	19.03.8
docker-compose    	1.25.5
os                	darwin
router            	drud/ddev-router:v1.15.0
web               	drud/ddev-webserver:v1.15.0

O DDEV inclui uma poderosa interface de linha de comando ou CLI. Execute ddev para aprender sobre alguns comandos comuns:

ddev

Você verá o seguinte resultado:

Output
Create and maintain a local web development environment.
Docs: https://ddev.readthedocs.io
Support: https://ddev.readthedocs.io/en/stable/#support

Usage:
  ddev [command]

Available Commands:
  auth             A collection of authentication commands
  composer         Executes a composer command within the web container
  config           Create or modify a ddev project configuration in the current directory
  debug            A collection of debugging commands
  delete           Remove all project information (including database) for an existing project
  describe         Get a detailed description of a running ddev project.
  exec             Execute a shell command in the container for a service. Uses the web service by default.
  export-db        Dump a database to a file or to stdout
  help             Help about any command
  hostname         Manage your hostfile entries.
  import-db        Import a sql file into the project.
  import-files     Pull the uploaded files directory of an existing project to the default public upload directory of your project.
  list             List projects
  logs             Get the logs from your running services.
  pause            uses 'docker stop' to pause/stop the containers belonging to a project.
  poweroff         Completely stop all projects and containers
  pull             Pull files and database using a configured provider plugin.
  restart          Restart a project or several projects.
  restore-snapshot Restore a project's database to the provided snapshot version.
  sequelpro        This command is not available since sequel pro.app is not installed
  share            Share project on the internet via ngrok.
  snapshot         Create a database snapshot for one or more projects.
  ssh              Starts a shell session in the container for a service. Uses web service by default.
  start            Start a ddev project.
  stop             Stop and remove the containers of a project. Does not lose or harm anything unless you add --remove-data.
  version          print ddev version and component versions

Flags:
  -h, --help          help for ddev
  -j, --json-output   If true, user-oriented output will be in JSON format.
  -v, --version       version for ddev

Use "ddev [command] --help" for more information about a command.

Para mais informações sobre o uso do DDEV CLI, visite a documentação oficial do DDEV.

Com o DDEV instalado em sua máquina local, agora você poderá instalar o Drupal 9 e começar a desenvolver um site.

Opção 2 — Instalando o DDEV no Linux

Em um sistema operacional Linux, você pode instalar o DDEV usando o Homebrew para Linux ou usando o script de instalação oficial. No Ubuntu, comece atualizando sua lista de pacotes no gerenciador de pacotes apt (você pode usar apt no Debian, caso contrário, use o gerenciador de pacotes equivalente associado à sua distribuição Linux):

sudo apt update

Agora, instale alguns pacotes de pré-requisito do repositório oficial do Ubuntu:

sudo apt install build-essential apt-transport-https ca-certificates software-properties-common curl

Esses pacotes lhe permitirão baixar o script de instalação do DDEV a partir do repositório oficial do GitHub.

Agora, baixe o script:

curl -O https://raw.githubusercontent.com/drud/ddev/master/scripts/install_ddev.sh

Antes de executar o script, abra-o no nano ou no seu editor de texto preferido e inspecione o conteúdo:

nano install_ddev.sh

Depois de revisar o conteúdo do script e você estiver satisfeito, salve e feche o arquivo. Agora você poderá executar o script de instalação.

Use o comando chmod para tornar o script executável:

chmod +x install_ddev.sh

Agora, execute o script.

./install_ddev.sh

O processo de instalação pode lhe pedir para confirmar algumas configurações ou inserir sua senha sudo. Depois que a instalação terminar, você terá o DDEV disponível no sistema operacional Linux.

Execute ddev version para verificar seu software:

ddev version

Você verá uma saída como esta:

Output
DDEV-Local version	v1.15.0
commit            	v1.15.0
db                	drud/ddev-dbserver-mariadb-10.2:v1.15.0
dba               	phpmyadmin/phpmyadmin:5
ddev-ssh-agent    	drud/ddev-ssh-agent:v1.15.0
docker            	19.03.8
docker-compose    	1.25.5
os                	linux
router            	drud/ddev-router:v1.15.0
web               	drud/ddev-webserver:v1.15.0

O DDEV é uma poderosa CLI ou interface de linha de comando. Execute somente ddev para aprender sobre alguns comandos comuns:

ddev

Você verá o seguinte resultado:

Output
Create and maintain a local web development environment.
Docs: https://ddev.readthedocs.io
Support: https://ddev.readthedocs.io/en/stable/#support

Usage:
  ddev [command]

Available Commands:
  auth             A collection of authentication commands
  composer         Executes a composer command within the web container
  config           Create or modify a ddev project configuration in the current directory
  debug            A collection of debugging commands
  delete           Remove all project information (including database) for an existing project
  describe         Get a detailed description of a running ddev project.
  exec             Execute a shell command in the container for a service. Uses the web service by default.
  export-db        Dump a database to a file or to stdout
  help             Help about any command
  hostname         Manage your hostfile entries.
  import-db        Import a sql file into the project.
  import-files     Pull the uploaded files directory of an existing project to the default public upload directory of your project.
  list             List projects
  logs             Get the logs from your running services.
  pause            uses 'docker stop' to pause/stop the containers belonging to a project.
  poweroff         Completely stop all projects and containers
  pull             Pull files and database using a configured provider plugin.
  restart          Restart a project or several projects.
  restore-snapshot Restore a project's database to the provided snapshot version.
  sequelpro        This command is not available since sequel pro.app is not installed
  share            Share project on the internet via ngrok.
  snapshot         Create a database snapshot for one or more projects.
  ssh              Starts a shell session in the container for a service. Uses web service by default.
  start            Start a ddev project.
  stop             Stop and remove the containers of a project. Does not lose or harm anything unless you add --remove-data.
  version          print ddev version and component versions

Flags:
  -h, --help          help for ddev
  -j, --json-output   If true, user-oriented output will be in JSON format.
  -v, --version       version for ddev

Use "ddev [command] --help" for more information about a command.

Para mais informações sobre o uso do DDEV CLI, visite a documentação oficial do DDEV.

Com o DDEV instalado em sua máquina local, é possível implantar o Drupal 9 e começar a desenvolver um site.

Passo 2 — Implantando um novo site Drupal 9 usando o DDEV

Com o DDEV em execução, agora você o usará para criar um sistema de arquivos específico do Drupal, instalar o Drupal 9 e depois iniciar um projeto de site padrão.

Primeiro, você criará um diretório raiz do projeto e então mover-se para dentro dele. Você executará todos os comandos restantes a partir desta localização. Este tutorial usará d9test, mas você está livre para nomear o diretório como quiser. Observe, entretanto, que o DDEV não lida bem com nomes com hifenização. Considera-se uma boa prática evitar nomes de diretório como my-project ou drupal-site-1.

Crie o diretório raiz do projeto e mova-se para ele:

mkdir d9test
cd d9test

O DDEV se destaca na criação de árvores de diretório que correspondam a plataformas CMS específicas. Use o comando ddev config para criar uma estrutura de diretório específica para o Drupal 9:

ddev config --project-type=drupal9 --docroot=web --create-docroot

Você verá uma saída como esta:

Output
Creating a new ddev project config in the current directory (/Users/sammy/d9test)
Once completed, your configuration will be written to /Users/sammy/d9test/.ddev/config.yaml

Created docroot at /Users/sammy/d9test/web
You have specified a project type of drupal9 but no project of that type is found in /Users/sammy/d9test/web
Ensuring write permissions for d9new
No settings.php file exists, creating one
Existing settings.php file includes settings.ddev.php
Configuration complete. You may now run 'ddev start'.

Como você passou --project-type=drupal9 para o comando ddev config , o DDEV criou vários subdiretórios e arquivos que representam a organização padrão para um site do Drupal. A árvore do diretório do projeto agora ficará assim:

.
├── .ddev
│   ├── .gitignore
│   ├── config.yaml
│   ├── db-build
│   │   └── Dockerfile.example
│   └── web-build
│       └── Dockerfile.example
└── web
    └── sites
        └── default
            ├── .gitignore
            ├── settings.ddev.php
            └── settings.php

6 directories, 7 files

.ddev/ será a pasta principal para a configuração ddev. web/ será o docroot para o novo projeto; ele irá conter vários arquivos settings específicos. Agora, você tem o esqueleto inicial para o novo projeto Drupal.

O próximo passo é inicializar a plataforma, que irá compilar os contêineres e configurações de rede necessárias. O DDEV vincula-se às portas 80 e 443, portanto, se estiver executando um servidor Web como o Apache em sua máquina, ou qualquer outra coisa que use essas portas, pare esses serviços antes de continuar.

Use o comando ddev start para inicializar a plataforma:

ddev start

Isso irá compilar todos os contêineres baseados em Docker para o projeto, que incluem um contêiner Web, um contêiner de banco de dados e o phpmyadmin. Quando a inicialização terminar, você verá uma saída como esta (o número de porta pode diferir):

...
[secondary_label Output]
Successfully started d9test
Project can be reached at http://d9test.ddev.site http://127.0.0.1:32773

docker ps

O ddev start compilou seus contêineres com sucesso e entregou duas URLs como saída. Embora esta saída diga que seu projeto “pode ser acessado em http://d9test.ddev.site e http://127.0.0.1:32773,” visitar essas URLs agora irá gerar um erro. A partir do Drupal 8, o Drupal core e os módulos contrib funcionam como dependências. Portanto, primeiro você precisará terminar de instalar o Drupal usando o Composer, o gerenciador de pacotes para projetos PHP, antes que tudo seja carregado em seu navegador Web

Uma das características mais úteis e elegantes do DDEV é que você pode passar comandos do Composer através do DDEV CLI e dentro do seu ambiente conteinerizado. Isso significa que você pode separar a configuração específica da sua máquina do seu ambiente de desenvolvimento. Você não precisa mais gerenciar os vários problemas de caminho de arquivo, dependência e versão que geralmente acompanham o desenvolvimento local em PHP. Além disso, você pode alternar rapidamente o contexto entre vários projetos usando diferentes frameworks e pilhas de tecnologia sem esforço.

Use o comando ddev composer para baixar drupal/recommended-project. Isso irá baixar o Drupal core, suas bibliotecas e outros recursos relacionados e então criar um projeto padrão:

ddev composer create "drupal/recommended-project"

Agora, baixe um componente final chamado Drush, ou Drupal Shell. Este tutorial usará apenas um comando drush, e ele fornece uma alternativa, mas o drush é uma CLI poderosa para o desenvolvimento Drupal que pode melhorar sua eficiência.

Use ddev composer para instalar o drush:

ddev composer require "drush/drush"

Agora, você construiu um projeto padrão do Drupal 9 e instalou o drush. Agora, você verá seu projeto em um navegador e configurará as definições do site.

Passo 3 — Configurando seu projeto Drupal 9

Agora que você instalou o Drupal 9, visite o novo projeto em seu navegador. Para fazer isso, execute novamente ddev start e copie uma das duas URLs que ele gera, ou você pode usar o seguinte comando, que irá automaticamente abrir seu site em uma nova janela do navegador:

ddev launch

Você encontrará o assistente de instalação padrão do Drupal.

Aqui você tem duas opções. Você pode usar esta UI e seguir o assistente através da instalação, ou poderá retornar ao terminal e passar um comando drush através do ddev. A última opção irá automatizar o processo de instalação e definir admin como o nome de usuário e senha.

Opção 1 — Usando o assistente

Volte para o assistente em seu navegador. Sob Choose language selecione um idioma no menu suspenso e clique em Save and continue. Agora, selecione um perfil de instalação. Você pode escolher entre Standard, Minimal e Demo. Faça sua escolha e clique em Save and continue. O Drupal irá verificar automaticamente seus requisitos, configurar um banco de dados e instalar seu site. O último passo é personalizar algumas configurações. Adicione um nome e um endereço de e-mail para o site que termine com seu domínio. Em seguida, escolha um nome de usuário e senha. Escolha uma senha forte e mantenha suas credenciais em algum lugar seguro. Por fim, adicione um endereço de e-mail privado que você verifique regularmente, preencha as configurações regionais e pressione Save and continue.

Seu novo site irá carregar com uma mensagem de boas-vindas.

Opção 2 — Usando a linha de comando

A partir do diretório raiz do projeto, execute este comando ddev exec para instalar um site padrão do Drupal usando drush:

ddev exec drush site:install --account-name=admin --account-pass=admin

Isso criará seu site da mesma forma que o assistente, mas com algumas configurações padrão. O nome de usuário e a senha serão admin.

Agora, inicie o site para exibi-lo em seu navegador:

ddev launch

Agora, você começará a construir o site, mas considera-se uma boa prática verificar se as permissões estão corretas para o diretório /sites/web/default. Enquanto você está trabalhando localmente, isso não é uma preocupação significativa, mas se você transferir essas permissões para um servidor de produção, elas representarão um risco de segurança.

Passo 4 — Verificando as permissões

Durante a instalação do assistente, ou quando sua página de boas-vindas carregar pela primeira vez, você verá um aviso sobre as configurações de permissões no diretório /sites/web/default e um arquivo dentro desse diretório: settings.php.

Depois que o script de instalação for executado, o Drupal irá tentar definir as permissões do diretório web/sites/default para leitura e execução para todos os grupos: esta é uma configuração de permissões 555. Ele também tentará definir permissões do arquivo default/settings.php para somente leitura, ou 444. Se você encontrar este aviso, execute esses dois comandos chmod a partir do diretório raiz do projeto. Não fazer isso representa um risco de segurança:

chmod 555 web/sites/default
chmod 444 web/sites/default/settings.php

Para verificar se você tem as permissões corretas, execute este comando ls com as chaves a, l, h, e d:

ls -alhd web/sites/default web/sites/default/settings.php

Verifique se suas permissões correspondem à seguinte saída:

Output
dr-xr-xr-x 8 sammy staff 256 Jul 21 12:56 web/sites/default
-r--r--r-- 1 sammy staff 249 Jul 21 12:12 web/sites/default/settings.php

Agora, você está pronto para desenvolver um site Drupal 9 em sua máquina local.

Passo 5 — Criando seu primeiro post no Drupal

Para testar algumas das funcionalidades do Drupal, você criará agora um post usando a interface Web.

A partir da página inicial do site, clique no botão Content na borda esquerda do menu superior. Agora, clique no botão azul add content. Uma nova página aparecerá. Clique em Article e outra página aparecerá.

Adicione qualquer título e conteúdo que você quiser. Adicione uma imagem, como um dos papéis de parede da DigitalOcean. Ao terminar, clique no botão azul. save.

Seu primeiro post aparecerá em seu site.

Agora, você está desenvolvendo um site Drupal 9 em sua máquina local sem nunca interagir com um servidor, graças ao Docker e ao DDEV. No próximo passo, você gerenciará o contêiner DDEV para acomodar o fluxo de trabalho.

Passo 6 — Gerenciando o contêiner DDEV

Quando você terminar de desenvolver seu projeto, ou quando quiser fazer uma pausa, você pode parar seu contêiner DDEV sem se preocupar com a perda de dados. O DDEV pode gerenciar a troca rápida de contexto entre muitos projetos; este é um de seus recursos mais úteis. Seu código e dados são sempre preservados em seu diretório de projeto, mesmo depois de parar ou excluir o contêiner DDEV.

Para liberar recursos, pare o DDEV a qualquer momento. A partir do diretório raiz do projeto, execute o seguinte comando:

ddev stop

O DDEV está disponível globalmente, assim você pode executar comandos ddev a partir de qualquer lugar, desde que você especifique o projeto DDEV:

ddev stop d9test

Visualize também todos os projetos usando ddev list:

ddev list

O DDEV inclui muitos outros comandos úteis.

Você pode reiniciar o DDEV e continuar desenvolvendo localmente a qualquer momento.

Conclusão

Neste tutorial, você usou o Docker e o poder da conteinerização para desenvolver um site Drupal localmente, com a ajuda do DDEV. O DDEV também se integra bem com vários IDEs, e ele fornece depuração de PHP embutida para o Atom, PHPStorm e Visual Studio Code (vscode). A partir daqui, você também pode aprender mais sobre a criação de ambientes de desenvolvimento para o Drupal com DDEV ou desenvolver outros frameworks PHP como o Wordpress.