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 and can't find the answer in this documentation, we'd be really grateful if you could share your experience with us so that we can try to help.

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.

If you're having problems with a stale cache in Varnish, you can run tok purge to empty it. Note that Varnish only honors the cache headers that you send from Drupal, so if you turn off caching in Drupal you won't have caching in Varnish.

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 certificate 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 but certain features like tok snapshot and tok test aren't aware of multisite databases.

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 root 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 8 is included in the SSH/Admin container, but this is not the recommend way of using Drush - you should include it in your repo via Composer.

Why does Tokaido set X-XSS-Protection, Referrer-Policy, and other headers?

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, Tokaido was built for secure production managed hosting environments.

We believe that good production environments maximise default security, and this includes sane defaults for 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.

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?

Mounting local directories into Docker environments is easy, but maintaining native-disk-like performance levels inside the Docker environment is very difficult to do. In our testing, a simple process like drush site-install - which takes 25 seconds locally - takes 5 times longer (1m25s) when using a direct Docker Volume mount between the host and Docker environment. Longer-running tasks like composer install have an even more noticeable impact.

This is a known issue and to be fair, Docker continues to work hard on improving volume performance, specifically on MacOS.

Like Tokaido, some local environment tools attempt to resolve this problem using a variety of methods. For example, DDev uses NFS. Other tools don't resolve this problem at all, which is why some have a reptuation for poor performance, even if it's really Docker on Mac which is causing the issue.

Tokaido on MacOS lets you choose between using Docker Volume mounts (the default) or the Unison sync service. On Linux, only Unison sync is available.

Docker volumes are slow but extremely reliable. We've never had a problem with them.

Unison is much faster once the environment is running, but the initial sync during tok up is slower and many users have reported problems with Unison on MacOS failing to register file changes and thus not syncing often enough.

For these reasons, we recommend using Docker Volumes (the default) on MacOS.

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/) ?

On MacOS, this is available by default when using the Docker sync service (which is the default). On Linux and when using the Unison sync service, 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 $REPO_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 $REPO_ROOT/drush/sites/

Why does Tokaido use Nginx instead of Apache?

There are a few reasons why we've chosen to embrace Nginx over Apache for Tokaido. We know this might cause some problems for existing projects - especially where they use .htaccess files - but we think the advantages are too good to ignore.

The key reason most people have for adopting Apache is to enable .htaccess files. But, we think this is an anti-pattern and can lead to significant issues.

When it comes to performance, Apache must scan the requested directory - and every directory above it - for a .htaccess file on every request. This has a negative impact on performance. On small sites, the difference will be negligible, but on large sites, or sites that leverage clustered file storage (remember that Tokaido is designed to run in production), the difference can be significant; Every millisecond counts.

In addition, .htaccess files make certain directories behave in unique ways, and enables developers to control this. While this can be useful in certain circumstances, in most cases you can introduce uncontrolled behaviour that does not go through the ordinary checks and testing that most teams would employ. Not using .htaccess makes it easy to audit server config and behaviour.

After deciding that .htaccess isn't worth implementing, the choice of web server becomes more personal. We prefer Nginx because we find it's config is easier to work with and is faster while consuming less system resources.