Tutorial

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

PHPDrupalDockerPHP FrameworksOpen Source

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:

Nota: é possível desenvolver com o Drupal 9 usando o DDEV em um servidor remoto, mas você precisará de uma solução para acessar o localhost em um navegador Web. O comando DDEV ddev share funciona com ngrok, que cria um túnel seguro em seu servidor para que você e outras partes interessadas visualizem seu site de desenvolvimento. Para uso pessoal, você também pode instalar uma GUI no servidor remoto e acessar o site de desenvolvimento através de um navegador Web dentro dessa interface. Para fazer isso, você pode seguir nosso guia how to install and configure VNC on Ubuntu 20.04. Para uma solução GUI ainda mais rápida, você pode seguir nosso guia how to set up a remote desktop with X2Go on Ubuntu 20.04.

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:

A Drupal 9 directory tree
.
├── .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):

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

Nota: lembre-se que o DDEV está iniciando contêineres do Docker nos bastidores aqui. Se você quiser ver esses contêineres ou verificar se eles estão em execução, você sempre pode usar o comando docker ps:

  • docker ps

Juntamente com quaisquer outros contêineres que você esteja executando atualmente, você encontrará quatro contêineres novos, cada um executando uma imagem diferente: php-myadmin, ddev-webserver, ddev-router e ddev-dbserver-mariadb.

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.

Drupal 9 installer from browser

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.

Drupal 9 welcome message with a warning about permissions

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á.

Drupal 9 Create Article Prompt

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.

Drupal 9 Created Post

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.

Creative Commons License