When you kick off a Preview build, Tugboat grabs the config file from your linked repository. Tugboat follows the instructions to set up each Service in your config file, grabbing the specified Docker images and then executing the Service Commands in three phases:
init
update
build
During the init
phase, you might use commands that set up the basic preview
infrastructure. This might include things like installing required packages or
tools, or overriding default configuration files.
During the update
phase, you might use commands that import data or other
assets into a service. This might include things like importing a database, or
syncing image files into a service.
During the build
phase, you might use commands that build or generate the
actual site. This might include things like compiling Sass files, updating 3rd
party libraries, or running database updates that the current code in the
preview depends on.
In the process of building your Preview, you’ll specify a default service, and that’s the service where your git repository is cloned. If you want to clone it into other services, see: cloning git repositories into your Services.
By the time the build is complete, Tugboat has configured Services according to your config file, including pulling the Docker images you want it to use for each Service, and has pulled in your code to execute your Preview.
When you’re
changing
or
updating
your Preview builds - or
building new Previews from a Base Preview -
the build process may bypass some of the build phases. For example, when you
Refresh a Preview, the build process pulls in updated code from your repo, but
only executes Service commands from update
and build
- bypassing the init
commands.
This can get a little complicated, so we’ve made a handy-dandy flowchart to help you keep track of where various processes start in each build phase:
After your Tugboat Build completes, Tugboat commits the entire container, taking a snapshot of that container, including all of its data and Services, at that moment in time.
When you do things like:
Tugboat uses that build snapshot as the basis for those actions, enabling you to quickly duplicate a Preview build or reset a Preview build to the state it was in the moment the build completed.
When Tugboat creates the build snapshot, the containers are fully stopped while the snapshot is taken, and then restarted again once the data is committed. If you try to implement a script that “sleeps” in the background while the Preview is being built, that process will not be present when the Preview restarts.
When you build a regular Preview, the configuration file typically instructs Tugboat to pull in databases, image files, or other assets. This process can take a while; the larger the assets, the longer the build.
When you mark a Preview as a Base Preview, Tugboat uses that Preview’s build snapshot as a starting point for every new Preview build. None of the new Previews need to re-download copies of databases, image files, or other assets. Base Previews can dramatically reduce the amount of time required to generate a working Preview.
In addition to speeding up your Preview builds, Tugboat saves disk space by storing only a binary difference between the Base Preview and Previews built from that Base Preview. A new Preview only uses whatever space it needs that differs from the Base Preview. Often, this means a Base Preview might use 2-3GB of space, and a Preview built from it might only use 100-200MB. This is a great way to keep a Tugboat Project under your billing tier’s storage limit, even when you’re building multiple Previews.
When you set a Base Preview, new Previews you build -
including Previews that are built automatically from pull requests - use the
Base Preview as a starting point, and build only from the build
stage. This
means that if you’re making changes that would be processed during init
or
update
stages, or changing a Docker image, you’ll need to either
rebuild the Base Preview,
or
build the Preview from scratch without the Base Preview.
What Tugboat calls “Preview size” is actually the size of the container in which the Preview lives. When a Preview is done building, Tugboat takes a snapshot of the container at that moment in time, and that’s what you’re seeing in your Tugboat Dashboard.
When you set up Services in your Preview, Tugboat pulls those Service images into the Preview container. Each of these Service images contributes to the total size of the Preview when it is fully built.
For example, say I’m building a Preview that uses Tugboat’s Service images for
apache
, mysql
and redis
; those Service images are 154MB, 226MB, and 147MB
at the time of this writing. That’s over 500MB for these Services; by the time
you add a database file, the container’s operating system and other assets,
you’ll likely be looking at 800MB to 1GB for a Preview that’s only pulling in
100KB of code from your linked git repo.
This is why working from a Base Preview is so helpful in reducing Preview size; all of those assets are contained in the Base Preview. When you build a new Preview from the Base Preview, the new Preview only contains what’s different in the PR, Branch or Tag you’re building. In my example above, a new Preview built from the Base Preview was only 20KB.
Preview status is indicated in a couple of different ways:
ready
status, with a green dot to
indicate that the Preview is active and ready to view. When you click the
link, you’ll go directly to your site Preview.ready
status, with a
green half-moon to indicate that the Preview is available, but is currently
suspended. When you go to the Preview link, you’ll see a splash page while the
Preview starts running again, and then you’ll be taken to your Preview. If you
don’t want to wait through the splash page, you can go to the
Actions
drop-down next to the
Preview
button, and select
Start
; this will restart the Preview. When the
half-moon switches to a green dot, you’ll be able to go directly to the
Preview, bypassing the splash screen.building
status in yellow. If your Preview build
is taking significantly longer than your average build time, displayed in the
Repository Stats section lower on the Project -> Repo page, you may want to
start troubleshooting.rebuilding
status in yellow. This indicates a complete Preview
rebuild from the beginning of the build process, so it should take as long as
a typical build.refreshing
status in yellow. This indicates a Preview that is
pulling in the latest code from git, and then running any commands in the
update
section, followed by the build
section of the
Configuration file.resuming
status in yellow while the Preview starts
spinning up services again.stopping
status in yellow while the Preview goes
through the process of stopping services.stopped
status in red to indicate that the Preview has
successfully stopped services.suspended
status. Any incoming HTTP
request to the preview will automatically start it again.failed
status in
red. Details should be available in the Preview’s activity logs. Sometimes a
failed Preview can be recovered by resetting it. For more help with a failed
preview, take a look at our troubleshooting docs, or go
to our Help and Support page to join our Slack support channel or
email us.unavailable
status. This usually
indicates an internal Tugboat error.
Resetting a Preview
often fixes this.canceled
status in red.A Service could be in any of the above states, as well as: