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).
Configure Git with your user information:
$ git config --global user.name "Your Name" $ git config --global user.email "firstname.lastname@example.org"
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
$ curl -sS https://getcomposer.org/installer | sudo php -- --install-dir=/usr/local/bin --filename=composer
$ 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
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 "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
~/.ssh/config file to automatically load keys into the ssh-agent and store passphrases in your keychain.
~/.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.
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
Install the latest Node.js LTS release from nvm:
$ nvm install --lts
$ 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)
Download and install the latest version of VirtualBox for Windows.
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.
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==22.214.171.124
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 firstname.lastname@example.org -i ./.vagrant/machines/default/virtualbox/private_key -p"' >> ~/.bashrc $ source ~/.bashrc
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
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
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.