Getting Started with Roots Sage, Trellis, and Bedrock on Windows (WSL)

Trellis, Bedrock, and Sage development on Windows is supported by several libraries and software packages.

Note: All commands must be run from WSL (Windows Subsystem for Linux).

Global Dependencies

Git

Configure Git with your user information:

$ git config --global user.name "Your Name"
$ git config --global user.email "yourname@example.com"

PHP

Install PHP 7.4:

$ sudo add-apt-repository ppa:ondrej/php
$ sudo apt-get update
$ sudo apt-get install php7.4 php7.4-mbstring php7.4-xml php7.4-zip

Composer

Install Composer:

$ curl -sS https://getcomposer.org/installer | sudo php -- --install-dir=/usr/local/bin --filename=composer

WP-CLI

Install WP-CLI:

$ cd ~ && curl -O https://raw.githubusercontent.com/wp-cli/builds/gh-pages/phar/wp-cli.phar
$ chmod +x wp-cli.phar
$ sudo mv wp-cli.phar /usr/local/bin/wp

SSH keys

Creating an SSH key

Trellis and GitHub both use SSH keys to communicate securely without the need to type a username and password each time. Create your SSH key:

$ ssh-keygen -t ed25519 -C "your_email@example.com"

For more details on generating SSH keys, see GitHub's excellent documentation.

Add your new public SSH key to your GitHub account. To copy your public key from the terminal to the clipboard:

$ cat ~/.ssh/id_ed25519.pub | clip.exe

Add your SSH key to the ssh-agent

Modify your ~/.ssh/config file to automatically load keys into the ssh-agent and store passphrases in your keychain.

Edit your ~/.ssh/config file and add the following lines:

Host *
  AddKeysToAgent yes
  IgnoreUnknown UseKeychain
  UseKeychain yes
  IdentityFile ~/.ssh/id_ed25519

Working with Sage

Sage relies on a few build tools to manage dependencies and build assets.

nvm

Install nvm from the instructions at https://github.com/creationix/nvm, or with the following command:

$ curl -o- https://raw.githubusercontent.com/creationix/nvm/v0.34.0/install.sh | bash

Node.js

Install the latest Node.js LTS release from nvm:

$ nvm install --lts

yarn

Install yarn:

$ npm install --global yarn

Working with Trellis

Trellis relies on a few other software tools. Install these tools:

VirtualBox

Download and install the latest version of VirtualBox for Windows.

Vagrant

Install the latest version of Vagrant in WSL, and in Windows. The WSL version will depend on the Linux distribution you're using; for instance if you're using Ubuntu, you'll want the Debian package. It is imperative that you install the same version of Vagrant in both Windows and WSL; even a single patch number difference will prevent it from working. You have to install both versions because VMs cannot exist "within" WSL; they must be created "outside," in Windows. To do this, Vagrant-in-WSL needs to communicate with Vagrant-in-Windows.

Follow the instructions on the Vagrant site to configure Vagrant to communicate correctly with Windows and VirtualBox. This will likely involve adding something like the following to .bashrc or a similar file executed when your WSL shell boots up:

export PATH="$PATH:/mnt/c/Program Files/Oracle/VirtualBox"
export VAGRANT_WSL_ENABLE_WINDOWS_ACCESS="1"

The above should be taken as examples and not just copied and pasted into your configuration. Read the linked document and make sure you're configuring your system correctly.

Ansible

Note: The following commands must be run from WSL (Windows Subsystem for Linux).

Install pip (Python package manager) if you don't already have it:

$ sudo apt-get install python3-pip

Install Ansible with pip:

$ pip install ansible

# Install a specific Ansible version:
$ pip install ansible==2.4.0.0

Troubleshooting

Maximum recursion depth exceeded

If you run into a "maximum recursion depth exceeded" error while provisioning, try downgrading Ansible to 2.5.1 (pip install ansible==2.5.1) and then re-provisioning.

You'll also need to update your vagrant.default.yml so that vagrant_ansible_version references 2.5.1:

-vagrant_ansible_version: '2.9.10'
+vagrant_ansible_version: '2.5.1'

vagrant ssh doesn't work

Try to install virtualbox_WSL2 plugin if you are not able to connect:

vagrant plugin install virtualbox_WSL2

Also check if there is any firewall on Windows with is blocking connection to port 2222

You can also try:

$ echo 'alias vssh="ssh -o UserKnownHostsFile=/dev/null -o StrictHostKeyChecking=no vagrant@127.0.0.1 -i ./.vagrant/machines/default/virtualbox/private_key -p"' >> ~/.bashrc
$ source ~/.bashrc

Slow site

If your site loads extremely slowly, try installing the vagrant-winnfsd plugin. In some cases this plugin can cause problems, so you may need to uninstall it if things get worse.

Note: The following commands must be run from WSL (Windows Subsystem for Linux).**

$ vagrant plugin install vagrant-winnfsd
$ vagrant reload # if Vagrant was already running

If vagrant-winnfsd causes problems, before uninstalling it you can try forcing it to mount using TCP instead of UDP by adding nfs_udp: false to the NFS mount point configuration lines in your Vagrantfile.

Ansible or Vagrant complains about permissions

Windows and Linux use different permission models, and mapping Windows permissions to Linux is imperfect. In some cases, Vagrant or Ansible will refuse to run if your permissions inside WSL are too...permissive. WSL offers a way to apply Linux permissions to files stored in the Windows filesystem through the use of metadata. I encourage you to read more about it in Microsoft's WSL docs, but the short version is that adding the following to /etc/wsl.conf in your WSL instance and then restarting it will allow you to apply Linux permissions:

[automount]
options = "metadata,umask=22,fmask=11"

Once you've done that, you can then use chmod to apply the correct permissions. For instance, Ansible may complain that it will ignore Trellis's ansible.cfg becuase it is in a world-writable directory; You can fix this by running chmod -R 744 trellis. Vagrant may complain that the ssh keys generated for it to log into the VM are too permissive: chmod 600 on the key file should fix that issue.