Installing Tokaido

Windows

Tokaido version 1.12.0 returns support for Windows 10! There are two methods supported for running Tokaido on Windows. Through Windows Subsystem for Linux (WSL), or through Git Bash or equivalent bash compatible terminal. Sorry, no PowerShell at this point in time.

It is ready to support the most common Drupal configurations. Before using Tokaido for your project, it's a good idea to make sure it's compatible.

Tokaido works with Drupal projects running:

• Drupal 7 or Drupal 8
• PHP 7.1, 7.2 or 7.3
• Your Drupal site must be in a Git repository

It is highly recommended that your project also includes the following best practices:

• You should use PHP Composer to install and manage your Drupal site and modules
• Your Drupal site should be located in a sub-directory off your Git root, such as /web or /docroot

Once you're comfortable with the requirements above, you're ready to install Tokaido.

While building Tokaido, we made some assumptions about how most people develop their Drupal sites. If you can't satisfy these requirements, but would still like to use Tokaido, please get in touch. We want to hear from you so that we know that there is demand for other use cases, and we hope we can ask you to help us test support for these new configurations.

Windows System Requirements

Before installing Tokaido on Mac, please ensure you have the following pre-requisites installed:

• Docker for Mac

Once you have Docker installed, you'll also want to make sure the drive you're devloping on is enabled as a Shared Drive in Docker settings. If you're working on C:/, you can right click on the Docker icon in the tray -> Settings -> Shared Drives -> Check the box for C and hit Apply.

Git Bash

Tokaido has been developed for compatibility on native Windows when using the Git Bash shell. Although other shells such as Cygwin or MinGW have not been tested, Tokaido may still work in environments providing bash commands are available.

If you don't currently have Git Bash on your system, it's a cinch to install. A rather comprehensive guide for installing Git Bash can be found here: https://www.sitereq.com/post/easiest-way-to-install-git-bash-commands-on-windows. But TL;DR, you can download the auto-installer here: https://git-scm.com

Setting Up Your Environment

We recommend changing your Git Bash terminal type to xterm-256 to fix render problems present in the default xterm type. This can be done by clicking the top left Git Bash icon > Options > Terminal and then changing the setting from the Type dropdown.

Installing Tokaido

Once you have Unison and unison-fsmonitor installed, you can get the latest Tokaido release as a binary from our Github release page

First up, download the binary to your system and make it executable:

curl -L https://github.com/ironstar-io/tokaido/releases/latest/download/tok-windows.exe -O && chmod +x tok-windows.exe

The Tokaido CLI has a built-in self-installer, so you now run...

./tok.exe install

This will install Tokaido to ~/.tok/bin/{version}/tok and create a symlink to this location from somewhere on your path (exactly where depends on your Windows config, but this is most likely under c:\Users\{your user}\AppData\Local\Ironstar

You don't have to do this. If you'd like to install Tokaido somewhere else and use it directly, just copy the binary you downloaded, for example:

cp tok-windows.exe ~/local/bin/tok

Upgrading Tokaido

You can easily upgrade Tokaido at any time by running:

tok upgrade

This command will check for a new version of Tokaido and if available, offer to download it to ~/.tok/bin/{version}/tok and link to it from /usr/local/bin/tok

If you prefer not to use this method, you can always get the latest Tokaido version from our Github release page

TODO: Testing required

Known Limitations

• Running docker-compose exec needs to be prefixed by winpty to fix TTY compatibility problems in Windows.

Installing the Tokaido Certificate Authority in Windows

Tokaido offers an easy-to-use proxy service on the https://*.local.tokaido.io:5154 address. This makes it offers a way to easily find your projects locally without having to worry about fixing port numbers.

This service is provisioned using a trusted SSL Certificate Authority which you can install in Windows to avoid annoying SSL security warnings.

1. Open Certificate Manager by navigating to "Manage User Certificates" in the Control Panel

   

2. Under "Certificates" > "Trusted Root Certification Authories" right click on "Certificates" and select "Import"

   

3. Click "Next" and "Browse", then find the Tokaido CA certificate in c:\Users\{Your User Name}\.tok\tls\ca\ca.crt

4. Click "Next", "Next", and "Finish"

Windows Subsystem for Linux (WSL)

Tokaido has been developed for compatibility with WSL v1 running Ubuntu. At the time of writing, WSL v2 is currently only available as an insider preview and may not be compatible immediately with Tokaido due to the relatively wide paradigm shift present in v2, particularly for how Docker is handled.

Setting Up Your Environment

If you don't already have WSL installed, we won't run through the setup guide again here, there are already some really good ones that exist online. Here's the one I used when I set up WSL for the first time: https://linuxhint.com/install_ubuntu_windows_10_wsl/

The next step is configuring Docker to work with WSL. There's a few steps to this, however the most important parts are having the Docker daemon exposed on port 2375, docker-compose installed and volume mounts working correctly. There is an excellent guide for setting up a Docker environment in Windows available here: https://nickjanetakis.com/blog/setting-up-docker-for-windows-and-wsl-to-work-flawlessly

I'd also recommend following this guide: https://medium.com/@blurdylan/transforming-your-ugly-terminal-to-a-unicorn-b83f315a36d1 to set up your WSL environment to look prettier than the default terminal and adding oh-my-zsh for a much more convenient experience.

The other package that you'll need installed is git with the command sudo apt-get install git

Installing Tokaido

Now that your environment is set up, let's install Tokaido. Currently this process is manual with a view to release to a package manager in the future.

wget -O /usr/local/bin/tok "https://github.com/ironstar-io/tokaido/releases/latest/download/tok-windows.exe"

This command should download the latest Linux release of Tokaido and place it in your PATH as the command tok.

Known Limitations

• Tokaido projects must be initialised in the Windows filesystem, outside of the WSL configured $HOME directory. This is due to the way $HOME is resolved by Docker for Windows causing a known, and currently unsolved, issue with Docker volume mounts. More information on this particular problem can be found here: https://github.com/docker/for-win/issues/2151. This will apparently be resolved in WSL v2, but will likely not be resolved in v1. To work around this, please ensure your projects are created outside $HOME in WSL. Your Windows home directory at /c/Users/<username>/x or similar will work just fine.

• The CA generated by Tokaido for valid needs to be manually trusted for SSL certificates to work correctly.

Stay up to date!

We release a new version of Tokaido pretty regularly, so be sure to periodically check the latest releases on Windows.