# Windows (WSL)

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


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"


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


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 rsa -b 4096 -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_rsa.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_rsa

# Working with Sage

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

  • nvm
  • Node.js
  • yarn

# 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 >= 4.3.10 (install on Windows)
  • Vagrant >= 1.8.5 (install on Windows and WSL)
  • Ansible >= 2.7, < 2.8 (install in WSL)

# 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"

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


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 python-pip

Install Ansible with pip:

$ pip install ansible

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

# 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


$ echo 'alias vssh="ssh -o UserKnownHostsFile=/dev/null -o StrictHostKeyChecking=no vagrant@ -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.


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:

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.