Advanced Tokaido

Full Tokaido Configuration Reference

This article details the full Tokaido configuration options. For more general information on how to edit the config and make simple changes, please see the [Managing the Tokaido Config](Managing the Tokaido Config) page.

Some Tokaido configuration settings aren't documented here simply because modifying them will almost certainly break your Tokaido environment. We strongly recommend against changing values in your .tok/config.yml if they are not documented here.

Tokaido is incredibly flexible. You are able to modify much of how your environment is created, and share that configuration with your teammates.

When you first run Tokaido in a new project, the .tok/config.yml file is created with a few few settings. You can modify this configuration file either directly or by using the config management commands which we'll discuss in a moment.

Because the config file is committed to your Git repository, you can easily share config settings with other developers in your team.

Tokaido Settings

This configuration branch applies to Tokaido, and is found under the tokaido: branch in the config YAML file.

Changes to these settings will be applied when you run tok rebuild

enableemoji

Toggle Tokaido's emoji output. This can be useful if your terminal doesn't support emoji output

Using the Tok CLI:

• Turn off with: tok config-set tokaido enableemoji false
• Turn on with: tok config-set tokaido enableemoji false
• Default value: true

Using the .tok/config.yml file

tokaido:
  enableemoji: true

betacontainers

Opt-in to the 'edge' container versions to help test pre-released changes.

Using the Tok CLI:

• Turn on with: tok config-set tokaido betacontainers true
• Turn off with: tok config-set tokaido betacontainers false
• Default value: false

Using the .tok/config.yml file

tokaido:
  betacontainers: true

dependencychecks

Tokaido runs some system dependency checks on the first boot to ensure that all required system components are available. If this system is reporting incorrectly for some reason, you can disable these checks.

Using the Tok CLI:

• Turn on with: tok config-set tokaido dependencychecks true
• Turn off with: tok config-set tokaido dependencychecks false
• Default value: true

Using the .tok/config.yml file

tokaido:
  dependencychecks: false

Drupal Settings

The drupal: config branch handles the path to your Drupal docroot and the major version of Drupal. Tokaido can auto-detect these values each time tok up or tok rebuild is run, so you generally won't need to modify these settings.

You can also configure private, public and temporary file paths corresponding to these settings generated in drupal-root/sites/default/settings.tok.php

$settings['file_public_path'] = '/tokaido/site/public/default/';
$settings['file_private_path'] = '/tokaido/site/private/default/';
$settings['file_temporary_path'] = '/tmp';

Using the Tokaido CLI:

• Path to Drupal root: tok config-set drupal path [docroot|web|app|etc]
• Private filepath: tok config-set drupal fileprivatepath /tokaido/site/private/default/
• Public filepath: tok config-set drupal filepublicpath /tokaido/site/private/default/
• Temporary filepath: tok config-set drupal filetemporarypath /tmp
• Drupal major version number: tok config-set drupal majorversion [7|8]
• Default values: Auto-detected by Tokaido

Using the .tok/config.yml file

drupal:
  path: [docroot|web|app|etc]
  majorversion: [7|8]
  filepublicpath: "/tokaido/site/public/default/"
  fileprivatepath: "/tokaido/site/private/default/"
  filetemporarypath: "/tmp"

System Settings

System settings instruct Tokaido how to manage components like background sync and xdebug on your local system. These settings are currently saved in the shared config.yml file in your repository, so if you modify these settings you may inadvertently change other user's system behaviour.

xdebug

Provide instructions for your local xdebug instance.

Note that Tokaido uses xdebug via the "remote back-connect method", where the Tokaido FPM service connects to your IDE. This means that your local IDE should be running and listening on the port you specify here. It is not possible to have Tokaido listen for incoming connections sent out from your IDE.

Using the Tokaido CLI:

• Set local IDE port is 9000: tok config-set system xdebug port 9000
• Enable xdebug: tok config-set system xdebug enabled true
• Disable xdebug: tok config-set system xdebug enabled false
• Set FPM xdebug autostart: tok config-set system xdebug autostart true
• Default values for all are unset and xdebug is disabled

Using the .tok/config.yml file

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

Background Sync Service

You can disable the background sync service. If you prefer to manually sync, after you disable the background sync service you can use tok sync for a one-time sync, or tok watch for an ongoing foreground sync.

Generally, we recommend leaving the background sync service running.

Using the Tokaido CLI:

• Disable background sync: tok config-set system syncsvc enabled false
• Default value: enabled true

Using the .tok/config.yml file

system:
  syncsvc:
    enabled: false

Docker Settings ("Services")

The services: config block exposes the ability to manage the Docker Compose file via the Tokaido configuration. This is the recommended way of managing Tokaido's Docker configuration, as it ensures your project can stay synced with changes in the Tokaido application, but also gives you a lot of power to change your environment.

See the Managing the Tokaido Configuration article for more complete details on how to modify Docker Services and why you would want to.

Whenever you change these settings, you need to run tok rebuildto apply the changes.

Unison

The Unison container provides the fast sync service between your local system and the Tokaido environment. Changing many of these values will break Tokaido, so we won't encourage you to do that.

However, you may want to manually override your Unison image name. You can do this to swap the Unison version that Tokaido runs to match your systems' version of the Unison service. Generally, Tokaido auto-detects this but you can modify the value if you need to.

Using the Tokaido CLI:

• tok config-set services unison image [reponame/imagename:version]

Using the .tok/config.yml file

services:
  unison:
    image: [reponame/imagename:version]

There are two versions that Tokaido ships with:

• tokaido/unison:2.48.4
• tokaido/unison:2.51.2

So for example, you could downgrade from Unison 2.51.2 to 2.48.4 by running tok config-set services unison image tokaido/unison:2.48.4

Memcache

Memcache is enabled in Tokaido by default, but you can disable it. You can also specify a different version of the image to use, from the official Docker image library

Using the Tokaido CLI:

• tok config-set services memcache enabled false
• tok config-set services memcache image memcached/1.5.9

Using the .tok/config.yml file

services:
  memcache:
    enabled: true
    image: memcached/1.5.9

Solr

Solr is disabled in Tokaido by default, but you can enable it. You can also change the version of the Apache Solr configuration that is deployed from the official Apache Solr image library

Tokaido runs Apache Solr 6.6 by default.

Using the Tokaido CLI:

• tok config-set services solr enabled true
• tok config-set services solr image solr/5.5

Using the .tok/config.yml file

ervices:
  solr:
    enabled: true
    image: solr/5.5

Kishu

Kishu is a custom service built by Tokaido that will restore write permissions on the settings directory in Drupal after the Drupal 'site-install' process is run.

This is important because making this directory read-only breaks the Tokaido sync service and any subsequent changes to your settings directory don't get replicated.

You can disable this service if you want, but we don't recommend it:

Using the Tokaido CLI:

• tok config-set services kishu enabled false

Using the .tok/config.yml file

services:
  kishu:
  enabled: false

An Example Configuration

The following is an example of an advanced Tokaido configuration.

tokaido:
  customcompose: false
  enableemoji: true
  betacontainers: true
  dependencychecks: true
project:
  name: myproject
  drupal:
    path: /docroot
    majorversion: 8
nginx:
  fastcgireadtimeout: "60"
fpm:
  maxexecutiontime: "60"
  phpmemorylimit: 512M
  phpdisplayerrors: "Off"
  phplogerrors: "On"
system:
  syncsvc:
    enabled: true
  xdebug:
    port: 9000
    enabled: true
    autostart: true
services:
  memcache:
    enabled: true
  solr:
    image: solr/7.1