1 of 7

Installation instructions

Creates a drupal 8 container, mysql container and node container, and connects them all up.

Quick install guide

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 sshto login to docker container as www-data
lando ssh -user=root to ssh and login as root
lando ssh <servicename> servicename = appserver / database / node

Pro-tips

Linux aliases

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.

alias ldrush='lando drush'
alias lssh='lando ssh'
alias lsshroot='lando ssh --user=root'
alias lphing='lando phing'
alias lcomposer='lando composer'
alias lnpm='lando npm'
alias ldrupal='lando drupal'
function lls() {
  lando ssh -c "ls -la $1"
}

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.

More help

For more information on installation, usage and administration of the development area, go to the next section.

Development environment

Windows install

Basic WSL set up

Steps 1 - 7 must be completed while the computer is connected to the city network.

Step 1: Enable WSL

Using Windows POWERSHELL (as Administrator):

Launch POWERSHELL as administrator: search powershell from Windows search

Enable-WindowsOptionalFeature -Online -FeatureName $("VirtualMachinePlatform", "Microsoft-Windows-Subsystem-Linux")

Alternative strategy

This may work without Windows requesting a restart at the end.

dism.exe /online /enable-feature /featurename:Microsoft-Windows-Subsystem-Linux /all /norestart
dism.exe /online /enable-feature /featurename:VirtualMachinePlatform /all /norestart
Invoke-WebRequest -Uri https://wslstorestorage.blob.core.windows.net/wslblob/wsl_update_x64.msi -OutFile $env:TMP\wsl_update_x64.msi -UseBasicParsing
msiexec.exe /i $env:TMP\wsl_update_x64.msi /passive

Step 2: Install Debian

Using CMD (console):

To open a CMD console search for cmd in the Windows search

wsl --set-default-version 2
wsl --install -d Debian

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

mkdir %USERPROFILE%\WSLDistros
# Download the cobdistro.tar file into the users home folder (c:\Users\xxxx\)
wsl --set-default-version 2
wsl --import CoB-Debian %USERPROFILE%\WSLDistros %USERPROFILE%\cobdistro.tar
wsl --set-default CoB-Debian

# to create an image
# wsl --export CoB-Debian %USERPROFILE%\WSLDistros

Step 3: Configure WSL to access the internet

Using LINUX (WSL) console:

To get the Linux console, open a CMD console, type: wsl

sudo -s
rm -rf /etc/resolv.conf
bash -c 'echo "nameserver 10.241.241.70" > /etc/resolv.conf'
bash -c 'echo "[network]" > /etc/wsl.conf'
bash -c 'echo "generateResolvConf = false" >> /etc/wsl.conf'
chattr +i /etc/resolv.conf
exit

Step 4: Custom WSL configurations

@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:

echo '[wsl2]' > $env:USERPROFILE/.wslconfig
echo 'memory=16GB' >> $env:USERPROFILE/.wslconfig

Using a LINUX console (WSL):

cat << EOF > /etc/wsl.conf
[automount]
# Stops the entire hard disk(s) from being mounted into WSL
enabled = false
# Causes the /etc/fstab file to be processed as WSL starts
mountFsTab = true
options = "metadata,uid=1000,gid=1000
# Set whether WSL supports interop process like launching Windows apps and adding path variables. Setting these to false will block the launch of Windows processes and block adding $PATH environment variables.
[interop]
enabled = false
appendWindowsPath = false
# Network host settings that enable the DNS server used by WSL 2. This example changes the hostname, sets generateHosts to false, preventing WSL from the default behavior of auto-generating /etc/hosts, and sets generateResolvConf to false, preventing WSL from auto-generating /etc/resolv.conf, so that you can create your own (ie. nameserver 1.1.1.1).
[network]
hostname = DoITWSL
generateHosts = false
generateResolvConf = false
EOF

wsl --shutdown
[Wait 30 seconds]
wsl

Step 5: install packages needed in WSL

Using LINUX console

sudo apt-get update
sudo apt-get install -y gzip unzip vim git curl groff

# optional for network diagnostics
sudo apt-get install -y net-tools dnsutils

curl "https://awscli.amazonaws.com/awscli-exe-linux-x86_64.zip" -o "awscliv2.zip"
unzip awscliv2.zip
sudo ./aws/install
sudo rm -f awscliv2.zip

Troubleshooting:

If you have accessing the internet from WSL first try RESTARTING the computer.
If that does not work, using a LINUX console try:

netsh winsock reset 
netsh int ip reset all
netsh winhttp reset proxy
ipconfig /flushdns

=> then restart the computer.

Step 6: Mount local folders into WSL.

Mount your development folders into WSL using the LINUX console:

sudo -s
rm -rf /etc/fstab
echo "c:/Users/xxxx/sources /home/yyyy/sources drvfs default,metadata,uid=1000,gid=1000 0 0" > /etc/fstab
mkdir /home/yyyy/sources
mount -a
exit

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

Step 7: Install Docker Desktop for Windows

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)

Setup other developer tooling

Add AWS-CLI credentials

Verify AWS is installed using LINUX console:

/usr/local/bin/aws --version

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:

echo "[cityofboston]" > ~/.aws/credentials
echo "aws_access_key_id = xxxxxx" >> ~/.aws/credentials
echo "aws_secret_access_key = xxxxx" >> ~/.aws/credentials

Alternatively. you could also create and edit the credentials file using vim which is installed in the WSL instance (from step 5 above).

Add SSH keys

Add your ssh keys to into your windows account (typically into a windows folder on you home drive) and then from a LINUX console:

mkdir ~/.ssh
cp -r /mnt/c/Users/xxxx/.ssh  ~/.ssh
sudo chmod -R 600 ~/.ssh/*
sudo chmod -R 644 ~/.ssh/*.pub
sudo chmod 700 ~/.ssh

Replace xxxx with your EmployeeID/User Account from CoB.

Install IDE:

Microsoft Visual Studio Code (VSC)
PHP Storm

Install Dashlane password manager

Knowledgebase

Restart the WSL service on Windows host

Using POWERSHELL:

Get-Service LxssManager | Restart-Service

Ensure windows has profile/policies loaded properly

Using POWERSHELL:

dmesg | grep 9p

Mount the sources folder manually

Using LINUX console:

sudo mount -t drvfs c:/Users/xxxx/sources /home/yyyy/sources -o metadata,uid=1000,gid=1000

Replace xxxx with your CoB supplied EmployeeID/User Account.

Replace yyyy with the accountname you used when you installed WSL.

Un-mount the sources folder

Using LINUX console:

sudo umount /home/yyyy/sources/

Replace yyyy with the accountname you used when you installed WSL.

Remount the sources folder

Using LINUX console:

sudo umount -a

Uninstall WSL:

Using Powershell (as Administrator):

wsl --disconnect
wsl --terminate -s debian
dism.exe /online /disable-feature /featurename:Microsoft-Windows-Subsystem-Linux /all /norestart

Moving Home=>Office or Office=>Home

From Powershell console reinitialize WSL:

dism.exe /online /enable-feature /featurename:Microsoft-Windows-Subsystem-Linux /all /norestart
dism.exe /online /enable-feature /featurename:VirtualMachinePlatform /all /norestart

From LINUX (WSL) console reset the nameserver so you can access the internet:

bash -c 'echo "nameserver X.X.X.X" > /etc/resolv.conf'

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.

Docker Fails to start

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:

dism.exe /online /enable-feature /featurename:Microsoft-Windows-Subsystem-Linux /all /norestart
dism.exe /online /enable-feature /featurename:VirtualMachinePlatform /all /norestart

Step 2: Then using a CMD shell (as Admin)

sc config LxssManager start=auto
wsl --set-default-version 2

Step 3: Restart Docker for Windows from the start menu.

PhpStorm settings configurations

For developers using PhpStorm IDE how and where to update your settings/preferences to make debugging and developing in Drupal easier.

Can I become who I want to be?

That's a tough question but thankfully, our team is on it. Please bear with us while we're investigating.

Have you had a chance to answer the previous question?

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.