What is Tokaido?

An overview of the Tokaido environment and how it works

Tokaido is a local development environment manager for Drupal websites. It’s similar in purpose to other utilities in this space such as Lando and DrupalVM.

What makes Tokaido different is some core design goals that we’ve achieved:

  • Tokaido is easy to use. No prior knowledge or study is needed. Just run tok up and go.
  • Tokaido is lightweight. A standard Tokaido environment uses less than half a gig of memory.
  • Tokaido is fast. A typical Tokaido startup takes less than 60 seconds.
  • Tokaido is powerful. You can modify your Tokaido environment in almost every way.
  • Tokaido is robust. Tokaido runs in production and locally, with sane defaults for security and performance.

Read on to learn a bit more about how Tokaido delivers on these promises.

Why Tokaido is easy to use

Tokaido is a command-line interface (CLI) and a collection of small production-grade Docker containers. These two items work together to run isolated Drupal environments.

Starting an Environment

Launching a new Drupal environment is as simple as moving into your Drupal site’s Git repository and running tok up

$ tok up

🚀  Tokaido is starting up!
🔄  Creating a background process to sync your local repo into the Tokaido environment
🚅  Tokaido started your containers
🔐  Setting up HTTPS for your local development environment
  
WELCOME TO TOKAIDO
==================

Your Drupal development environment is now up and running

💻  Run "ssh myproject.tok" to ssh into the environment
🌎  Run "tok open" to open the environment in your browser
👀  Run "tok exec" to run one-time commands like 'tok exec drush status'
🤔  Run "tok status" check the status of your environment

Check out https://tokaido.io/docs/using/ for tips to help you get the most out of your Tokaido environment

Administering your site

With Tokaido, you can adminster your Drupal site locally, or you can SSH into the Tokaido environment and gain immediate access to a collection of heplful tools such as Drush, Yarn, Npm, and more.

Tokaido automatically creates an SSH alias for your site, such as umami.tok if your main project directory is umami.

Generally, you start your Tokaido experience by running composer install:

$ ssh umami.tok

The Tokaido local development system is ephemeral. Each time you restart the
local Tokaido instance, your database is reset. Content not saved in the
/tokaido/site folder will also be lost forever.

Be sure to check out https://tokaido.io/docs for help

🚅 LOCAL umami 02:27:00 /tokaido/site/web $ cd ..
🚅 LOCAL umami 02:27:00 /tokaido/site $ composer install
...

Sometimes it’s faster to just use tok exec to run commands from your local host without having to SSH into the environment. For example:

$ tok exec drush status
Drupal version                  :  8.5.6
Site URI                        :  http://default
Database driver                 :  mysql
Database hostname               :  mysql
Database port                   :  3306
Database username               :  tokaido
Database name                   :  tokaido
Database                        :  Connected
...

tok exec starts in your website root, such as /tokaido/site/projectname/web. If you want to run composer install this way, you can include an instruction to change directory, such as: tok exec 'cd .. && composer install'

Opening your site

Once your environment is ready, you can run tok open and the Tokaido site will open in your default browser using an SSL-encrypted site. On Mac, this certificate can be automatically added to your keychain so your Drupal site is immediately trusted. On Linux and Windows, you can manually add the certificate authority and still receive the same trusted SSL certificate for all your Tokaido sites.

You can also access the Tokaido proxy server at https://local.tokaido.io:5154. This displays all of the Tokaido environments that have been created in your site, so you can easily access them.

tokaido proxy preview

Why Tokaido is Lightweight

Tokaido uses small purpose-built Docker containers to run components like MySQL, Nginx, and Varnish. While solutions like DrupalVM create an entire virtual operating system, the Tokaido approach only uses the resources that these small containers require, without the substantial ovehead that a VM involves.

Consider for example this standard project using the (slightly tidied-up) output from docker stats:

NAME                CPU %     MEM USAGE / LIMIT  
umami_mysql_1       0.06%     193.1MiB / 31.34GiB
umami_haproxy_1     0.00%     9.449MiB / 31.34GiB
umami_varnish_1     0.27%     27.86MiB / 31.34GiB
umami_nginx_1       0.00%     12.53MiB / 31.34GiB
umami_fpm_1         0.00%     44.05MiB / 31.34GiB
umami_drush_1       0.00%     11.45MiB / 31.34GiB
umami_kishu_1       0.00%     4.656MiB / 31.34GiB
umami_memcache_1    0.01%     2.594MiB / 31.34GiB
umami_syslog_1      0.00%     3.758MiB / 31.34GiB
umami_mailhog_1     0.00%     3.773MiB / 31.34GiB
umami_unison_1      0.00%     109.8MiB / 31.34GiB

As you can see, this Tokaido environment is using less 430MB of RAM, and almost no CPU.

The strongest advantage of this approach is that you can run multiple Tokaido environments even on very small laptops, whereas you can generally only run a single or maybe two VM-based environments.

Why Tokaido is Fast

Because Tokaido uses Docker, it is almost as fast as a local MAMP/LAMP style setup. There is no virtual hardware layer required to translate virtual hardware calls into physical hardware calls.

Even more importantly, because Tokaido uses Unison for synchronising files between your local and Tokaido environments, file system access is much faster than competing Docker-based solutions.

This is because, on Mac and Windows, Docker still runs a virtual machine and so the same virtual<>physical hardware calls are impacting performance, especially filesystem performance.

By using Docker and Unison, Tokaido can boast the fastest performance times of any Drupal local development engine.

Why Tokaido is Powerful

Out of the box, Tokaido aims to be incredibly easy to use. We find that 90% of Drupal sites running on Tokaido require no special configuration. However, should you need to, Tokaido exposes two levels of advanced configuration options.

Firstly, you can modify the Tokaid config file inside .tok/config.yml. This config is shared with anyone else who clones your Git repo, and can be used to easily enable additional services. For example, the following config when added to .tok/config.yml will enable Solr, Adminer, and Mailhog support the next time tok up is run:

services:
  solr:
    enabled: true
  mailhog:
    enabled: true
  adminer:
    enabled: true

You can also use the tok config-set command to quickly change config settings, such as tok config-set services adminer enabled true to enable Adminer

In addition to these simple configuration changes, you have the ability specify your own Docker images for common services. These can be either new images, or modified forks of Tokaido’s own images. For example, if you needed PHP 5.6 support you could create a PHP 5.6 container and instruct Tokaido to use this image:

services:
  php:
    image: yourrepo/php:5.6

Finally, you can tell Tokaido to completely stop managing the Docker Compose file it uses to orchestrate Docker. This way, you can directly modify the Docker Compose configuration.

You can learn more about these advanced configuration options, including changing PHP runtime configuration, in our advanced config section

Why Tokaido is Robust

The Docker images that Tokaido runs were first designed to be run in production-grade environments for large enterprise and goverment hosting. They were adapted to Tokaido later.

As such, these containers either enforce or encourage a secure and reliable approach to Drupal hosting design. Our design philosophy here is that your local environment should be as close to production as possible, and Tokaido provides a very production-like environment.

Here are some examples of Tokaido’s default configuration that encourages security and resilience:

  • Tokaido includes Varnish, because all production environments should use caching
  • Tokaido sets secure headers like X-Frame-Options, X-XSS-Protection, and Referrer-Policy
  • Tokaido’s PHP config uses sane defaults for things like max children, memory, and so on.
  • Tokaido uses trusted TLS certificatres with HSTS headers

Sometimes these defaults can get in the way, which is why we’ve made it possible to disable these controls. However, it is key to Tokaido’s way of working that these are opt-out rather than opt-in settings.