Set up environment for Drupal development on various operating systems.
Select your operating system from below, and follow the instructions to setup your development environment and prepare to install the City of Boston Drupal 8 website.
Tip
You can (re)use an existing key on your development computer, so long as it meets the requirements of GitHub.
How to create SSH keys for github
Be sure you load the public keys you create into GitHub.
Tip
You can (re)use an existing key on your development computer, so long as it meets the requirements of Acquia.
City of Boston recommend the Ubuntu 16.04 or later distribution. While other Linux distributions will operate well, the instructions below assume the use of Ubuntu and, in particular, the apt
package manager.
Check Docker pre-requisites.
If using PHPStorm, install Docker-machine
At their core, Mac operating systems are similar to Linux and therefore the same basic steps apply to Macs as they do for Linux.
Git is usually installed, and on most operating systems verifying is achieved by typing the command below at a terminal prompt. This process has the advantage of prompting to install git if its not there.
Enter the command below. This will install a brew-community version of Lando, including docker as explained here.
Using brew is quick and simple and will definitely get you started. If you later find that you have issues with Lando and/or Docker versions, then follow the instructions on this page under the title "Install DMG via direct download" to get the latest versions.
Because Drupal is most commonly installed on Linux servers, City of Boston DoIT does not recommend using Windows® as a developer machine due to the increased difficulty in emulating the most common Drupal production web server.
However, if you have no alternative, or harbor an unquenchable desire to use Windows® then the following best practices and instructions should get you headed in the right direction.
There are many IDE's capable of being used to write, verify and deploy PHP code. City of Boston do not endorse any particular platform, but have successfully used the following:
Notepad++ (basic text editor)
Sublime Text (improved text editor)
VIM (Linux-based advanced text editor)
Visual Studio Code (full IDE)
Eclipse (full IDE)
PHPStorm (full IDE)
Run phpcs on your custom modules
PHP CodeSniffer (https://github.com/squizlabs/PHP_CodeSniffer) is already included with our D8 project with composer. If you run a lando composer install
you should have it available at ./vendor/bin/phpcs
1. You need to specifically download the Drupal coding standards using the coder module. You can do this globally for your computer by running:
2. You need to make sure phpcs knows about your newly installed coding standard (note the path below assumes you're using Ubuntu, yours might be different on a mac):
3. Now you can run this manually against your custom modules:
If you're looking for more info, here's a good place to get started: https://www.drupal.org/docs/8/modules/code-review-module/installing-coder-sniffer
Contact the AWS administrator to get credentials for logging into the AWS console and (if necessary) interacting with AWS via the command line.
Once you have a login to the AWS console: if you wish to use the AWS-CLI, or use any other command line program which connects to AWS (e.g. git for CodeCommit) you will need to register/add an SSH key on your AWS-CLI account.
You can use an existing ssh key, or create a new one.
You need to install the AWS CLI if you, or a tool you use, needa to interact with AWS from the command line - for example:
To use terraform to maintain AWS
To deploy webapps to AWS
To modify AWS objects from the command line
Follow the instructions here.
You want to install the AWS-CLI on you local machine, not inside a container. Follow the Mac, Windows or Linux instructions accroding to the OS you are using.
Verify AWS is installed using LINUX console:
You should see an output something like:
If not then return to the "Install AWS-CLI" section above.
Obtain your secret access keys for AWS from the AWS administrator, and then create the AWS credentials file using the LINUX console:
Alternatively, you could create and edit the ~/.aws/credentials
file using any text editor.
Three options for setting up a development environment on Windows.
Because Drupal is most commonly installed on Linux servers, City of Boston DoIT does not recommend using Windows® as a developer machine due to the increased difficulty in emulating the most common Drupal production web server. However, if you have no alternative, or harbor an unquenchable desire to use Windows® then the following best practices and instructions should get you headed in the right direction. There are 3 strategies to choose from:
This is the most complicated solution to setup, but allows the developer to use any windows-based tools desired to manage the Drupal codebase and databases.
The git repo is cloned to a local Windows folder on the Windows host. This repo folder is mounted into a Linux (Ubuntu) Docker Container (like a VM). Docker manages the virtualization and the container contains all the apps and resources required to host and manage the website locally for development purposes. Git commands are run either from the Windows host, or from the container. Lando (a container manager tool) provides a “wrapper” whereby commands (e.g. Docker, Lando, Git, Phing, Drush, Composer, SSH etc) are typed into a console on the Windows host, and Lando executes them inside the container. To be clear, with this strategy:
The container hosts the website
The developer normally changes/adds/removes Drupal files in the Windows folder on the Windows host
Changes to custom Drupal files (i.e. to files in the mounted folder) either on the host or in the container are immediately available to both the host and container without restarting docker or VMs
The developer normally runs dev tools such as Git, Drush, Phing and Composer in the container, using Lando commands
The Windows host does not require to have tools other than Docker, Lando and VBox or Hyper-V installed on it
Some developers still like to have git installed on the Windows host so their IDE tools (e.g. PHPStorm) can manipulate the repos directly
Developers’ need to interact directly with the container (i.e. via ssh) is minimized, and
This installation creates a developer environment suitable for a Linux-based production deployment.
Due to Lando requirements to use Docker CE (not Docker Toolkit), which in turn requires Hyper-V, you: NEED to have a Windows 10 64bit Professional or Enterprise version CANNOT use Windows 7 or earlier CANNOT use Windows Home or Home Pro as Hyper-V is required by Lando and does not ship with home versions.
These 6 steps are all performed on the host (i.e your Windows®) PC.
This is required to supply a Linux core which is needed by Docker to generate the necessary containers.
Install Windows Subsystem for Linux (preferred method)
These instructions also depend on having a current version of Windows® 10 (version later than Fall Creators Update
and pref build 16215 or later).
To install WSL support, do the following:
Open Windows Powershell as Administrator
Run:
Enable-WindowsOptionalFeature -Online -FeatureName Microsoft-Windows-Subsystem-Linux
Restart Windows when prompted
Taken from here
Install Linux Distro
DoIt suggests you install the Linux distribution from the Microsoft Store which most closely matches the Linux distro you will use on your production webservers. If you are unsure, install Ubuntu or Debian.
Install Hyper-V
If Hyper-V is not enabled when the Linux subsystem was installed (check by typing “Hyper-V” in the start menu), then follow these instructions.
If you are not using WSL, then Git for Windows provides a bash terminal for the Windows host. Installing Git for Windows is a convenient way to get this, and also gives the developer the option to directly execute git commands (against the repo) from the Windows host. This step is optional if you use WSL, or if you are confident with some other tool to provide a bash style console. Use Git for Windows from here. This is a good tutorial to step thru installation.
If you are using WSL and have enabled Hyper-V for your virtualization, then use the Docker “community version” from here - this link also guides you through an install.
Download the latest Windows .exe installer from here.
On Windows®, DoIT recommends:
In order to use VS Code for Drupal development, use this guide as a starting point. The editor is highly configurable with many extensions available. You will likely want to customize it further based on your needs.
Pickup from step 3 on the quick install guide.
This solution may be a quick and viable option if you have a powerful Windows machine to use as the host, and are not doing much development which required extensive use of an IDE. Depending on your setup, there may be issues with IPAddress routing, requiring complex configurations.
This method is not used by City of Boston DoIT, the preferred solutions on Windows machines are A or B.
For Windows® versions before 10 Fall Creators Update, we recommend that VirtualBox (free from Oracle) is used
For later versions you should use enable and use Hyper-V within Windows.
In the VM, install a Linux distro as close as possible to the production distro you will use, and unless you are very comfortable with the Linux CLI, be sure to install a distro with a GUI.
Once the Linux distro is installed, then follow the setup instructions for Linux.
Setting up the Visual Studio Code editor to work well with Drupal
Edit .vscode/launch.json
Add the following configuration:
Click in top navbar navigate to file > preferences > settings
Under Workspace Settings
expand the Extensions
option
Locate PHP CodeSniffer configuration
and scroll down to the Standard
section and click the "Edit in settings.json" link
Add the following configuration to your Workspace Settings
:
Under Extensions in the left sidebar, search for "PHP Debug" and click "Install"
Under Extensions in the left sidebar, search for "phpcs" and click "Install"