Engine Configuration¶
Substance engines are defined by a simple YAML configuration file which is
located at $_HOME/.substance/engines/[enginename]/engine.yml
. This file is
automatically created for you when you create a new engine using the
substance engine create
command.
You can edit this file in any text editor of your choice. As a convenience,
Substance will open it in your favorite editor (specified by the EDITOR
environment variable) using the command substance engine edit [enginename]
.
What follows is an overview of all configuration sections in the file.
box
¶
Specifies the box file used to create the VM in VirtualBox upon first launch. After first launch, this setting is no longer used.
devroot
¶
This configures how the local directory for the engine will behave.
path
specifies the path to the directory on the local machine.mode
specifies the sync mode. Possible values areunison
(default) andsubwatch
(deprecated).excludes
lists filename patterns to ignore on sync. You can use this setting to ignore additional file patterns for the projects hosted using this engine. Note that this can only match patterns based on filename, not full directory path. To ignore files based on directory path, use thesyncArgs
setting.syncArgs
lists additional arguments to pass tounison
whenmode
is set tounison
.
Note
The subwatch
mode is the legacy way to sync files. It does not work as
expected under all conditions. You should really use unison
instead. If
unison
really isn’t working out for you, then try subwatch
, but
expect bugs. You will also have to install the subwatch
module
separately using pip
.
docker
¶
This configures the Docker daemon running inside the engine. You will usually want to leave the defaults as-is.
driver
¶
Specifies the virtualization backend to use for managing the virtual machine.
virtualbox
is the only currently-supported value for now, but more backends
will be added in the future.
network
¶
All Substance engines are networked using a Host-only network adapter serving as a DHCP server. The settings in this section are automatically filled in and updated by Substance after each launch of the engine.
profile
¶
Specifies the capabilities of the virtual machine. Currently, two settings are supported:
cpus
: Specifies number of virtual CPUsmemory
: Specifies amount of memory to reserve for the VM (in megabytes)
Note that these settings can be changed even after the VM has been created in VirtualBox (requires a reboot of the VM).
aliases
¶
Substance engines can define a list of commonly-used commands to execute within specific containers. This allows the user to avoid having to type a long and difficult-to-remember command for common tasks such as building a website, pulling packages, etc.
Since Substance was designed for web development first, all engines come
pre-configured with a few aliases for web development. All of these aliases are
configured to be executed within a container named web
as a user named
heap
within the directory /vol/website
:
substance make
: Executemake
.substance composer
: Execute thecomposer
command (PHP package manager).substance npm
: Execute thenpm
command (Javascript package manager)substance watch
: Execute thewebpack -w
command (Web build tool in watch mode)
Note that executing an alias will pass along all arguments following the name of the alias, e.g.:
$ substance make clean TARGETS=all # executes 'make clean TARGETS=all' within the container
You can add more aliases (or even change the configuration for the pre-configured ones) by editing your engine’s definition file. Here’s the example configuration for the above command:
aliases:
composer:
args:
- composer
container: web
cwd: /vol/website
user: heap
make:
args:
- make
container: web
cwd: /vol/website
user: heap
npm:
args:
- npm
container: web
cwd: /vol/website
user: heap
watch:
args:
- watch
container: web
cwd: /vol/website
user: heap
Simply add more entries to the aliases
YAML object to define new aliases
for your engine.