Advanced Config

Unleash the full power of Tokaido by learning about it's config structure

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

The Tokaido Configuration File

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 commited to your Git repository, you can easily share config settings with other developers in your team.

Using the Config Editor

Most configuration options can be easily managed through the tok config editor interface.

$ tok config
Please choose the Tokaido config area you'd like to edit
Use the arrow keys to navigate: ↓ ↑ → ←
Main Menu >>
  🤔 Tokaido Project Settings »  - Tokaido settings that define how this project built
     Drupal Settings »  - Simple Drupal settings that Tokaido needs, like your document root
     Nginx Settings »  - Nginx config settings that can be controlled from your codebase
     PHP FPM Settings »  - FPM config settings that can be controlled from your codebase
     Services »  - Enable or disable additional Tokaido services like Solr and Mailhog
     Exit

---------
These settings tell Tokaido how this project should be built and managed.
It includes essential items like if Tokaido should use beta Docker images and if
you want to self-manage your Docker Compose file.

The editor provides information about what each config option controls, and also specifies what the default Tokaido value is.

Using config-set and config-get

The tok command line interface has aliases that let you manage your configuration. This is an advanced feature but a useful way to share config changes that can be easily applied by other people.

For example, to enable Solr support in your Tokaido environment, you can run:

  • tok config-set services solr enabled true

Or to turn off the background sync service:

  • tok config-set system syncsvc enabled false

You can also use config-get to look up config settings, including defaults that might not be present in your .tok/config.yml file:

$ tok config-get system xdebug

{
  Port: "",
  Logpath: "",
  Enabled: false,
  Autostart: false,
}

Changes to your settings will be applied the next time you run tok up

Directly Managing Docker Compose

Tokaido creates and manages a Docker Compose file on your behalf, called docker-compose.tok.yml in your repository root. Most of the time, you shouldn’t need to modify this file, and if you do Tokaido will replace your changes the next time it is run.

You can “unlock” this file by telling Tokaido that you want to manage it yourself by setting the customcompose setting to true:

  • tok config-set tokaido customcompose true

Once you enable this feature, Tokaido will not make any changes to your Docker Compose file. This also means that much of the settings you can enable via the standard Tokaido configuration will no longer work.

If you do find yourself needing to manage the Docker Compose file directly, please let us know on GitHub when you needed to do that. We could add a new feature so you don’t have to.

You can still use the tok up command to control self-managed Docker Compose environments. Changes to the docker-compose.tok.yml file will be applied the next time you run tok up

Nginx and FPM Runtime Config

Nginx and PHP FPM are able to read certain configuration settings directly from your .tok/config.yml file at runtime. This means that you can commit values like the PHP Memory Limit and Nginx Max POST size in your repo, and ship those settings into production Tokaido hosting providers like Ironstar

We recommend using the tok config editor to manage these configurations.

$ tok config
Nginx Settings »
Use the arrow keys to navigate: ↓ ↑ → ←
Main Menu » Tokaido Configuration?
  🤔 Worker Connections   Using default value [1024]
     Client Body Max Size   Using default value [1024m]
     Keepalive Timeout   Using default value [65]
     FastCGI Read Timeout   Using custom value [60]
     FastCGI Buffers   Using default value [16 16k]
     FastCGI Buffer Size   Using default value [32k]
     « Main Menu
     Exit

---------
Sets the maximum number of simultaneous connections that can be opened by a
worker process.

It should be kept in mind that this number includes all connections
(e.g. connections with proxied servers, among others), not only connections with
clients. Another consideration is that the actual number of simultaneous
connections cannot exceed the current limit on the maximum number of
open files

Current Setting: Use Default Value
Default Setting: [1024]

Configuration Reference

Here is the full configuration reference for Tokaido.

Tokaido Settings

Changes to your settings will be applied the next time you run tok up

Enableemoji

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

Via CLI:

  • Toggle with: tok config-set tokaido enableemoji false
  • Default value: false on Windows, true on MacOS/Linux

In YAML:

tokaido:
  enableemoji: true

Betacontainers

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

Changing this setting will re-create your database container and you will lose all data.

Via CLI:

  • Toggle with: tok config-set tokaido betacontainers true
  • Default value: false

In YAML:

tokaido:
  betacontainers: true

Dependencychecks

Toggle Tokaido’s pre-Up system dependency checks.

Via CLI:

  • Toggle with: tok config-set tokaido dependencychecks false
  • Default value: true

In YAML:

tokaido:
  dependencychecks: false

Project

The Project Name and Path settings are used by Tokaido and should never need to be changed. We’ll document how to do this here, but if you change these values you will most likely break your environment.

Via CLI:

  • Toggle with: tok config-set tokaido project name [value]
  • Toggle with: tok config-set tokaido project path [/path/to/repo/root]
  • Default value: Your repository directory name and path to the repo root

In YAML:

tokaido:
  project:
    name: [value]
    path: [/path/to/repo/root]

Drupal

The Drupal config tree handles the path to your Drupal docroot and the major version of Drupal. Tokaido will auto-detect these values and you should never need to change them.

You can also configure private, public and temporary filepaths 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';

Via CLI:

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

In YAML:

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.

The Tokaido config is global, so changing these settings could impact other people working on your project. Please proceed with caution.

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.

Via CLI:

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

In YAML:

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

You must run tok up after updating the xdebug config.

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.

Via CLI:

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

In YAML:

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.

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

Unison

The Unison container provides the fast sync service between your local system and the Tokaido environment. Changing many of these valuse 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.

Via CLI:

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

In YAML:

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

There are two versions that Tokaido ships with:

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

FPM

You can modify the FPM service to pass additional environment variables into the container and change your PHP configuration.

The full list of available PHP settings and their defaults can be found here

Via CLI:

  • tok config-set services fpm environment VARIABLE_NAME value

For example: tok config-set services fpm environment PHP_MEMORY_LIMIT 1024M

In YAML:

services:
  fpm:
    environment:
      PHP_MEMORY_LIMIT: 1024M
      PHP_MAX_INPUT_TIME: 300
      PHP_POST_MAX_SIZE: 256M

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

Via CLI:

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

In YAML:

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.

Via CLI:

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

In YAML:

services:
  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:

Via CLI:

  • tok config-set services kishu enabled false

In YAML:

services:
  kishu:
    enabled: false

Advanced Configuration

Much of the Docker Compose language is available via the Tokaido configuration, but a lot of that power is unsupported and shouldn’t need to be changed. You can see a full list of the configuration values available by checking out the config struct in the Tokaido source repository.

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
  fpm:
    environment:
      PHP_MEMORY_LIMIT: 1024M
      PHP_MAX_INPUT_TIME: 300
      PHP_POST_MAX_SIZE: 256M

Adding a trusted certificate

Mac users will be prompted to automatically add to the system level trusted certificates on tok up. If you’d prefer to handle this manually however, the generated certificates can alternatively be trusted at the browser level. In this case, there is some manual process in order to complete.

The end result should be local HTTPS development without any warnings from your browser.

The Tokaido generated SSL certificates to be added can be found in the directory ~/.tok/proxy/client/tls. The certificate that should be added to your keychain or trusted certificate store is the root CA located at ~/.tok/proxy/client/tls/proxy_ca.pem.

Chrome

Chrome certificates are managed at either the browser level, or the OS level. Importing Certificates using Chrome on Mac OS X

Firefox

By default, Firefox doesn’t use the OS certificate store, so even Mac users may need to follow this guide. Installing root certificate in Mozilla Firefox

Windows/Edge

For Edge/IE, the certificate will need to be manually added at the OS level. See Manage Trusted Root Certificates

Alternative guides on adding a trusted certificate

Updating your hostsfile

While Tokaido will attempt to add the required entry to your hostsfile on tok up if proxy functionality is enable. You may however prefer to do this manually

Unix
  • Your hostsfile should be located in /etc/hosts open it elevated with sudo vim /etc/hosts
  • Add a new line to the bottom of the file with the text 127.0.0.1 <project-name>.tokaido.local, replacing <project-name>
  • Save and exit
Windows
  • Press the Windows key.
  • Type Notepad in the search field.
  • In the search results, right-click Notepad and select Run as administrator.
  • From Notepad, open the following file: C:\Windows\System32\Drivers\etc\hosts
  • Add a new line to the bottom of the file with the text 127.0.0.1 <project-name>.tokaido.local, replacing <project-name>
  • Click File > Save to save your changes.

For more detailed guides on amending your hostsfile