FAQ

We hope you enjoy using Tokaido and that it makes your life as a Drupal developer a little bit easier. If you run into problems, we’d be really grateful if you could share your experience with us so that we can try to help, and make Tokaido just that little bit better. Before contacting us please check this document for common issues and questions.

What versions of Drupal are supported?

Tokaido is tested with the latest versions of Drupal 7 and Drupal 8, running PHP 7.1, so your Drupal site will need to be compatible with this version. It’s definitely time to upgrade, if it isn’t.

Do I have to put my Drupal site in /docroot?

No. When you first run tok up Tokaido will attempt to identify your DRUPAL_ROOT, or ask you if it can’t. This means you can use /docroot, /web, /app, or whatever you like.

It is possible to install your Drupal site in the root of your Git repository, but it’s not supported or recommended.

How can I bypass the Varnish cache?

You can bypass the Varnish cache (and haproxy) by accessing the Nginx container directly on HTTP. In almost all cases, this shouldn’t be necessary and isn’t recommended.

To access Nginx directly, run tok open nginx.

Can I test my site without SSL?

Yes, use the same instructions above for bypassing the Varnish cache to access your site directly via Nginx.

I get HSTS warnings from my browser when accessing the site using SSL

You need to add the proxy certificate authority to your browser to resolve these warnings. You can find the CA file in $HOME/.tok/proxy/client/tls/proxy_ca.pem

Is there Drupal Multisite Support?

Yes, Drupal multisite is tested and does work. In order to enable this, you first need to manually create the secondary database(s). The easiest way to do this is by logging in as the root user to MySQL from inside the Drush container:

ssh {project-name}.tok
mysql -u root -h localhost -p 

The password for the root user is tokaido.

What version of Drush is used?

The Drush/SSH container ships with Drush launcher which will automatically use the version of Drush you have installed via Composer.

If you don’t include Drush in your project (you should) then a global install of the latest stable Drush version is included in the SSH/Admin container.

Why does Tokaido set X-XSS-Protection, HSTS, Referrer-Policy, and X-Frame-Options headers? Can I turn it off?

One of our core design goals with Tokaido was to build a collection of Docker containers that work both in local development, and in production. In fact, we run Tokaido in production successfully.

We believe that good production environments maximise default security, and this includes sane defaults for HSTS, Referrer-Policy, and other headers.

These headers are set to their defaults by Varnish, unless they are otherwise set by Drupal. For example, if you want to change the X-Frame-Options header, you can simply specify a different value in Drupal and Varnish will not write a new header.

The only way to completely bypass these headers is to bypass the Varnish container, as discussed above.

Can I run Tokaido in Production?

Absolutely. In fact, the Tokaido Docker images are already in use for production sites, and are built with that goal.

You can simply re-use the existing images as they are on Docker Hub, or you can fork and modify the source images from GitHub.

It is not recommended to use the Tokaido CLI utility to create production environments, however.

How well does the filesystem sync process perform compared to other solutions?

In our testing with sites up to 20GB in size containing thousands of files, Unison performs excellently. The only real drawback with Unison, which we think is trivial, is that it has to receive notification that a file has been updated before it can begin the process to replicate it. This means there will always be some kind of delay between writing a file in one system, and having the change replicated to another system.

After I/O heavy tasks like composer install, this delay can become noticeable, but we have never seen this take longer than 1 or 2 seconds, even under the heaviest usage. In daily life for most sites, the replication process in Unison will be unnoticable and the process completed in a fraction of a second.

Most other Drupal local dev solutions (like Beetbox or DrupalVM) rely on a virtual machine to provide the dev environment. This generally results in consistent write operations between the local and virtual system. With these solutions, you’ll never see inconsistent content between local and dev environments, but you will see slower read and write performance inside the dev environment.

Because Tokaido uses Docker, it has the added benefit of using very limited system resources. Each Tokaido environment only needs CPU when your interacting with the Drupal site, and otherwise uses less than 400MB of RAM and 2% of CPU.

With most small and even medium Drupal sites, you won’t notice a performance difference either with Tokaido, or virtual-system based solutions like Beetbox and DrupalVM.

How does the SSH config work?

When you run tok up, Tokaido installed an SSH profile for your project into ~/.ssh/tok_config. It looks something like this:

Host project-name.tok
    HostName localhost
    Port 32774
    User tok
    IdentityFile ~/.ssh/tok_ssh.key
    ForwardAgent yes
    StrictHostKeyChecking no
    UserKnownHostsFile /dev/null

This makes it easy for you to use SSH with ssh project-name.tok.

Can I map Drush site aliases from my home directory (~/.drush/) ?

Unfortunately this is a difficult option to implement. Synchronising your ~/.drush directory would require a separate Unison listener process, which makes each Tokaido environment a little bit more complex and difficult to manage.

Since the official example for Drush suggests that the preferred location for site aliases is in the $ROOT/drush/sites/ folder, we decided to follow this example.

So in most cases, getting your site aliases to work inside Tokaido is as simple as copying the alias from ~/.drush/ to $ROOT/drush/sites/

Is xdebug Supported?

We have experimental support for xdebug and are working to improve this with each release. If you use xdebug, please help us to test it and report any issues you find.

To enable xdebug for your project, you need to add the following to your .tok/config.yml file manually:

system:
  xdebug:
    port: 9000
    enabled: true
    autostart: true

Once saved, run tok up again. Xdebug is now running inside your Tokaido environment, and it will attempt to connect to your system on port 9000.

To use xdebug with Visual Studio Code, for example, you can install the PHP Debug extension and then configure the VS Code debugger as follows:

{
    "version": "0.2.0",
    "configurations": [
        {
            "name": "Listen for XDebug",
            "type": "php",
            "request": "launch",
            "port": 9000,
            "pathMappings": {
                "/tokaido/site": "/path/to/your/repo"
            }   
        },
        {
            "name": "Launch currently open script",
            "type": "php",
            "request": "launch",
            "program": "${file}",
            "cwd": "${fileDirname}",
            "port": 9000,
            "pathMappings": {
                "/tokaido/site": "/path/to/your/repo"
            }            
        }
    ]
}