Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Using Lando in City of Boston.
For our purposes, Lando is a PHP-based tool-set which does 3 main things:
Provides a pre-packaged local docker-based development environment,
Provides a wrapper for common docker container management processes,
Provides a means to execute development commands inside the container from the host.
Lando curates an appropriate LAMP stack for Drupal development, largely removing the need for this skill in the local development team. The stack is contained within:
Docker images that are maintained by Lando.
A configuration file (landofile) which Lando parses into the necessary dockerfiles and utility scripts
COB uses a landofile which can be found at /[reporoot]/.lando.yml
Lando provides a CLI for tasks developers commonly need to perform on the container.
A full list of defined Lando commands can be obtained by executing:
lando
Lando provides a CLI for tasks developers commonly need to perform in the container.
A full list of defined Lando commands can be obtained by executing:
lando
lando drupal-pull-repo
lando drupal-sync-db
lando drupal-pull-repo --no-sync &&
lando drupal-sync-db
lando rebuild
or to be completely sure, run these commands from the
lando destroy &&
rm -rf <repo-path>
git clone -b develop git@github.com:CityOfBoston/boston.gov-d8.git <repo-path>
lando start
Command
Explanation
Starts all 3 lando containers, building them if they don't already exist.
Stops all 3 containers, but does not delete or destroy them. They can simply be restarted later.
Will rebuild the container using the values in the .lando.yml
and .config.yml
files.
If the containers have persistent images, these will be reused.
Any content in the database will be lost,
Project files cloned/managed by git will be left intact.
Will destroy the container.
If the containers have persistent images, these will be retained.
Any content in the database will be lost,
Project files cloned/managed by git will be left intact.
Command
Explanation
Opens a bash terminal on the appserver docker container.
If the -c switch is used,
lando ssh -c "<command>"
then a terminal will be opened, the command provided will be run in the container and then the session will be closed.
eg: lando ssh -c "ls -la /app/docroot/modules/custom"
lando drush
Executes a drush cli command in the appserver container:
lando drush <command>
eg lando drush status
Note: a drush alias can be passed like this:
lando drush @alias <command>
eg: lando drush @bostond8.prod en dblog
lando drupal
Executes a Drupal cli command in the appserver container:
lando drupal <command>
lando composer
Executes a Composer command on the appserver container:
eg: lando composer require drupal/paragraphs:^1.3
lando drupal-sync-db
Executes a cob script which copies the database from the stage environment to the local development environment, and sync's all the configurations etc.
lando drupal-sync-db
lando drupal-pull-repo
Executes a cob script which pulls the latest project repository from gitHub and then clones and merges the private -repository. Finally it runs sync tasks to update the DB with any new configurations.
lando drupal-pull-repo
To update the repo's without sync'ing the content, execute:
lando drupal-pull-repo --no-sync
lando validate
Locally runs the linting and PHPCode sniffing checks that are run by Travis.
lando switch-patterns
Allows you to switch between patterns CDN hosts.
lando switch-patterns 2
switches to the local CDN in the patterns container
lando switch-patterns 3
switches to the production CDN
lando switch-patterns 4
switches to the stage patterns CDN.
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)
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.
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
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.
For developers using PhpStorm IDE how and where to update your settings/preferences to make debugging and developing in Drupal easier.
That's a tough question but thankfully, our team is on it. Please bear with us while we're investigating.
Yes, after a few months we finally found the answer. Sadly, Mike is on vacations right now so I'm afraid we are not able to provide the answer at this point.
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
:
Creates a drupal 8 container, mysql container and node container, and connects them all up.
For more detailed install and usage instructions for various platforms, see "More Help" below.
Ensure you have set up your development environment as described here:
Clone the public boston.gov-d8 repo into a local folder
git clone -b <branchname> git@github.com:CityOfBoston/boston.gov-d8.git
(City of Boston DoIT recommends that the develop branch be used)
On host computer, change directory to the repository root and use lando to create and start containers:
lando start
Depending on the power of the host machine, the Drupal 8 build process for boston.gov can take more than 15-20 minutes. The composer install and site install (esp. config import) tasks can take 5-10 minutes each - with no updates being directed to the console.
-> You can follow the process by inspecting the log files in docroot/setup/
there are links to these files in the console.
From the repository root (on host):
to view a list of available lando commands:lando
to view phing tasks: lando phing -l
to run drush commands:lando drush <command>
lando ssh
to login to docker container as www-data
lando ssh -user=root
to ssh and login as root
lando ssh <servicename>
servicename = appserver / database / node
To reduce typing at the console, you can add the following aliases to your ~/bashrc
, ~/.bash_aliases
or ~/.bash_profile
files on your development (host) OS.
With these aliases, typing (in a console) lls <folder>
will use lando to run ls -la <folder>
in the default container (in our case appserver) and list files there. Whereas, ls <folder>
will list the folder locally (i.e. on the host) as usual.
For more information on installation, usage and administration of the development area, go to the next section.
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"
For some people working within lando containers slows down and crashes their environment. To fix this they can work outside lando containers (patterns.lndo.site) and directly with localhost:3030
The local development version of the CDN is hosted by Fleet at http://localhost:3030. This local CDN is served (by Node/Fractal) from your local environment.
Super-powers are granted randomly so please submit an issue if you're not happy with yours.
Once you're strong enough, save the world:
Steps 1 - 7 must be completed while the computer is connected to the city network.
Using Windows POWERSHELL (as Administrator):
Launch POWERSHELL as administrator: search powershell
from Windows search
Alternative strategy
This may work without Windows requesting a restart at the end.
Using CMD (console):
To open a CMD console search for cmd
in the Windows search
Alternative strategy:
This may provide a more fault tolerant WSL environment when we are switching from City network to external network (because we are controlling where the distro is installed, and its not on the user's profile).
Using LINUX (WSL) console:
To get the Linux console, open a CMD console, type: wsl
@see https://docs.microsoft.com/en-us/windows/wsl/wsl-config
These configuration files tweak the WSL environments to enable a better developer experience based on a standard CoB laptop configuration (i.e. minimum i7 chip, 32GB RAM and SSD harddisk).
Using a POWERSHELL console from the windows host:
Using a LINUX console (WSL):
Using LINUX console
If you have accessing the internet from WSL first try RESTARTING the computer.
If that does not work, using a LINUX console try:
=> then restart the computer.
Mount your development folders into WSL using the LINUX console:
Replace c:/Users/xxxx/sources
with the location in the windows host where you plan to keep all development source files.
This is the folder where you will be cloning the CoB repos.
If in doubt, create a sources
folder in your windows home folder, and for the command above just replace xxxx
with your CoB supplied EmployeeID/User Account.
Replace yyyy
with the accountname you used when you installed WSL (you can find this in the LINUX console by running cd ~ && pwd
- the path displayed be in the format /home/accountname
Download installer from https://docs.docker.com/desktop/windows/install/
Double click the installer to launch: + Click OK to accept non-windows app, + Select WSL2 as the backend (rather than Hyper-V)
Docker desktop does not automatically start after the install, you need to start it the first time from the Start menu.
Restart your computer after this step.
If you do not, and subsequently restart the computer while off the city network, your installation will be broken, and you will have to remove Docker and WSL, and start over.
(see "Docker Fails to Restart" notes below to fix broken/non-functional WSL installs)
Verify AWS is installed using LINUX console:
You should see an output something like:
aws-cli/2.7.4 Python/3.9.11 Linux/5.10.102.1
.....
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 also create and edit the credentials file using vim
which is installed in the WSL instance (from step 5 above).
Add your ssh keys to into your windows account (typically into a windows folder on you home drive) and then from a LINUX console:
Replace xxxx with your EmployeeID/User Account from CoB.
Microsoft Visual Studio Code (VSC)
PHP Storm
Using POWERSHELL:
Using POWERSHELL:
Using LINUX console:
Replace xxxx
with your CoB supplied EmployeeID/User Account.
Replace yyyy
with the accountname you used when you installed WSL.
Using LINUX console:
Replace yyyy
with the accountname you used when you installed WSL.
Using LINUX console:
Using Powershell (as Administrator):
From Powershell console reinitialize WSL:
From LINUX (WSL) console reset the nameserver so you can access the internet:
Where X.X.X.X is the IPAddress: 8.8.8.8 (confirm if there should be a different address) when in the office and 10.241.241.70 when not on the city network but using a VPN.
If, when restarting the computer, Docker fails to start and/or you get the following error when starting WSL:
The service cannot be started, either because it is disabled or because it has no enabled devices associated with it.
To fix this, perform the following steps.
Step 1: Using Powershell (ps) as Admin:
Step 2: Then using a CMD shell (as Admin)
Step 3: Restart Docker for Windows from the start menu.
The following is a printout of the console from a typical build following the instructions on Installation Instructions page.
Specifically this output is from the command:
The log above was generated using lando start
with this.lando.yml
landofile.
The log above was generated using lando start
with thisconfig.yml
project file.
If the installation has completed without errors, then you should be able to check the following:
The production/public website is hosted by Acquia and can be accessed at https://www.boston.gov.
The local development version of the public website can be viewed at: https://boston.lndo.site. This local copy of the Drupal website is served (by Apache) from the appserver
docker container, and its content is stored and retrieved from a MySQL database in the database
docker container.
You will find the CityOfBoston/patterns repo cloned into the root/patterns
folder on your host dev computer.
The production/public patterns library is hosted by City of Boston from our AWS/S3 infrastructure and can be accessed at https://patterns.boston.gov.
The local development version of the patterns library is hosted by Fleet and can be viewed at https://patterns.lndo.site. This local copy of the Fleet website is served (by Node/Fractal) from the patterns
docker container.
You will find the CityOfBoston/patterns repo cloned into the root/patterns
folder on your host dev computer.
The gulp, stencil, fractal and other services running in thepatterns
docker container will automatically build the local fleet static website into root/patterns/public
from the underlying files in real-time as they are changed.
The production/public patterns CDN is hosted by City of Boston from our AWS/S3 infrastructure at https://patterns.boston.gov.
The local development version of the CDN is hosted by Fleet at https://patterns.lndo.site. This local CDN is served (by Node/Fractal) from the patterns
docker container.
You will find the CityOfBoston/patterns repo cloned into the root/patterns
folder on your host dev computer.
The gulp, stencil, fractal and other services running in thepatterns
docker container will automatically build the local fleet static website into root/patterns/public
from the underlying files in real-time as they are changed.
The repo that was checked out in Step 1 of the is hosted on your dev computer, and is mounted into each of the docker containers. As you make changes to the files on your dev computer, they are instantly updated in all of your local docker containers.