The following attributes control how a Service is built:
|image||String||The Docker image to use for this Service|
|checkout||Boolean||Whether to clone the git repository to this Service|
|checkout_path||String||Where to clone the git repository|
|depends||List||List of other Services that this Service depends on|
|commands||List||List of commands to run for various build stages|
|visualdiffs||List||List of visualdiffs to generate for the Service|
The following attributes configure how Service URLs are generated
|aliases||List||A list of aliases to generate URLs for|
|alias_type||String||What kind of aliases to generate|
|subpath||Boolean||Whether subpath URLs should be generated for this Service|
The following attributes configure how the Tugboat proxy routes HTTP requests to the Service:
|expose||Integer||Which port the Service should expose to the Tugboat proxy|
|default||Boolean||Whether this is the default Service for a Preview.|
|http||Boolean||Whether the Service should be available via HTTP|
|https||Boolean||Whether the Service should be available via HTTPS|
|domain||String||A custom domain for Tugboat to generate URLs with|
|subpath_map||Boolean||Whether to map the generated subpath to “/”|
What type of URL aliases to generate for the Service. Valid options are
domain. Alias URLs are generated
in addition to the normal Service URLs.
alias_type is set to
default, the alias URLs are constructed by substituting the preview name in the Service
URL with the values of
aliases. The values of
aliases are sanitized based on the value of
false, alias values are sanitized to create a valid host name, and is truncated to 30 characters, to
make the host name a maximum of 63 characters. If
true, the alias values are URL encoded.
aliases is set to
['foo', 'bar'], alias URLs look like the following
alias_type is set to
domain, the alias URLs are constructing by substituting the domain part of the Service URL
with the values of
aliases. The alias values are sanitized to create a valid domain name. If
aliases is set to
['foo.com', 'bar.com'], alias URLs look like the following
In order for these domains to resolve, a DNS entry must be added to the alias domains as a
previews.tugboat.qa. A wildcard entry is required if
subpath is set to
A list of aliases to generate URLs for. If set, additional alias URLs will be generated for the service. These URLs can
be used to route to different endpoints inside of the Service, such as for a Drupal Multisite. How the alias URLs are
constructed depend on the value of
default: trueis set)
Whether or not this Service should have a copy of the git repository cloned into it.
Specifies the path where the git repository should be cloned if
checkout: true is set. If this path already exists,
the clone will fail.
A set of commands to run during various points in a Preview’s lifecycle. These commands are divided into the following stages. Each stage consists of a list of commands. Each command is run in its own context, so things like changing directories does not “stick” between commands. If that behavior is required, an external script should be called.
|init||Commands that set up the basic Preview infrastructure, such as required packages or tools|
|update||Commands that import data or other assets into a service, such as a database or image files|
|build||Commands that build or generate the site, such as compiling Sass or running database updates from code|
|ready||Commands that indicate that a service is “ready”, such as checking for a listening TCP port|
|online||Commands to run once, after a Preview has built, is online, and is ready to accept incoming requests|
|start||Commands that should be run every time a Preview starts|
|clone||Commands that should be run on the cloned (new) Preview that has been created from an existing Preview|
build stages are related as follows:
When a Preview is created, the commands in
init are run, followed by the commands in
update, and finally the
When a Preview is refreshed,
the commands in
update are run, followed by the commands in
When a Preview is created from a Base Preview, only the commands in
build are run.
clone commands all run after the build snapshot, so these commands are executed after the
build is complete (although
cloneed commands are committed as a second build snapshot). For more info on the build
snapshot, see: The Build Snapshot.
trueif only one service is defined)
Whether this is the default Service for a
Preview. The default Service is where incoming HTTP requests to the preview URL are routed. Setting this to true also
expose: 80 and
checkout: true unless those attributes are explicitly set otherwise.
Defines the order in which commands are executed between the defined Services. If one Service has a dependency on another, it will wait for that Service’s commands to run before running its own commands. If not set, there is no guaranteed order in which Services will execute their commands relative to other Services.
A custom domain to use when generating URLs for the Service. If
example.com is used, for example, URLs for the service
http://preview.example.com/pr123-token/, depending on the other
configuration values. Note that using a custom domain will result in browsers issuing SSL/TLS certificate warnings when
default: trueis set)
If this Service should be publicly accessible via HTTP/HTTPS, this is the port that the Tugboat Proxy will forward incoming requests to.
By default, Tugboat only generates HTTPS URLs and forces a redirect to HTTPS. Setting this value to
true changes this
behavior to allow access to this Service’s URL directly via HTTP on port 80.
true, this Service’s URL is public accessible via HTTPS on port 443. In order to disable HTTPS for a Service URL,
https must be set to
http must be set to
true. If both
http are set to
The Docker image to use for this Service. Tugboat maintains a set of images on Dockerhub. These images all extend the official docker images, and are configured to work well with Tugboat. See also: Specify a Service image.
true, the URL generated for this Service will be a subpath of the root Preview domain instead of a subdomain.
Using a subpath URL is not common, but can solve problems with testing advertisements or using OAuth
subpath: true is set, URLs are rewritten by the Tugboat Proxy to replace the Preview-specific path
/ before being forwarded to the Service. When
false, URLs are passed through as-is.
A set of visual diffs that should be generated for the Service. These visual diffs are generated automatically when a Preview is created with a base preview. They are then updated when the Preview is refreshed or rebuilt.
The visual diffs are specified by providing a list of relative URLs to the Service. Each item in this list can be
either a string, such as
/blog, or a map overriding the following screenshot options:
|url||none||The relative URL to create the visual diff for. This option is required|
||Only create visual diffs for these Service aliases. The special
||How long to wait for a page to be ready when taking a screenshot, in seconds. Minimum:
||Which event to wait for before creating a screenshot of a page.|
||Disable this to use an alternate screenshot method that is more friendly to elements that have
waitUntil option can be one of the following events. If a list of events is given, the screenshot is created after
all of the listed events have fired
|load||Fires when the
|domcontentloaded||Fires when the
|networkidle0||Fires when there are no more than 0 network connections for at least 500ms|
|networkidle2||Fires when there are no more than 2 network connections for at least 500ms|
The visual diff URLs can optionally be grouped by Service alias, which is convenient when aliases have
different URL structures. Group URLs by nesting them in a map with the name of the alias they belong to. The special
:default alias can be used to create a group of URLs that should not use an alias.