Tugboat builds a working preview of your Craft CMS website for any branch, tag, commit, or pull request in a git repository. It can automatically create these previews for pull requests by integrating with GitHub, GitLab, or Bitbucket git repositories.

To get started, you’ll need to add a .tugboat/config.yml file to your project to tell Tugboat which services you need enabled and how you’d like your site to be built. We’ve put together a sample configuration file which creates a new Craft 3 CMS site.

Here are the steps:

Step 1. Fork our Repository

Tugboat Config Yml Craft Cms

Our repository includes the config.yml file, and that’s about it. Go ahead and fork the repository to make your copy of the site. Here’s the GitHub documentation on how forking works.

Step 2. Sign into Tugboat with your GitHub account

Now that you have a fork of the repos, login into Tugboat by authorizing with your GitHub account. Creating a Tugboat account is free. There are other paid plans for additional disk space and features, but that’s not necessary for this tutorial.

Once you’re logged in, click Create a New Project. You’ll then give your project a name and select the repos you just forked. If you don’t see the repos, make sure you authorized Tugboat using the right GitHub user. If you belong to multiple organizations within GitHub, make sure the right organization is selected in the drop-down selector within the Tugboat form.

Click the Create Project button and Tugboat will import your repository.

Step 3. Create your Environment Variables

Tugboat Environment Variables Craft CMS

Craft CMS needs to know some personal details about your site. To generate the first user we need to know their email address and define a password. While we could add this information into our config file, that would present a security risk. Instead, we will define environment variables within Tugboat to securely pass along these credentials.

On your repository landing page, click on the Repository Settings link and scroll down to the Environment Variables section. Add two variables: one for the CRAFT_EMAIL and one for the CRAFT_PWD.

Step 4. Build Your Preview

Tugboat Craft First Build

Back on your Repository Landing page, go ahead and build the main branch by clicking the Build Preview button. Once the build begins, click the title of the preview to watch the build happen in real-time and monitor the log files. This step will take a couple of minutes to bring your services online.

Step 5. Preview your site

Tugboat Preview Landing Page

Once the build is complete, the Preview button will turn blue and voila! You have a fully working Craft CMS site. Log in with your email address and password you defined as environment variables within Tugboat.

Welcome To Craft CMS Via Tugboat

Click on the Launch Terminal link next to either the PHP or MySQL service for command-line access to each service. Use it for debugging or adding additional software. Remember though, none of these changes will stick when the preview is rebuilt unless you go back and add the details to the configuration file.

Next Steps

There are many things you can do from this point. Feel free to jump right into the documentation.

  • You can create Pull Requests and Tugboat will automatically build out your Previews. On the Repository settings page, you can enable Tugboat to post the URL of the Preview back into the GitHub as a comment.

  • Keep working on your site. In the repository settings page, grab a copy of Tugboat’s SSH Key and add it to GitHub as an SSH Deploy Key. Click the Launch Terminal link next to a service within a Preview and have command-line access. A Deploy Key will enable you to commit your changes back to GitHub. If you’re not familiar with vi, consider installing nano with apt-get install nano.

  • Work locally, using Tugboat. Clone your repos from GitHub and download Tugboat’s CLI tool. Or use our API and programmatically kick off a build. As long as the code is committed back to the repos Tugboat can find it and generate a fully working site Preview.

  • Need faster build times or additional disk space? Consider one of our paid plans. All paid plans come with the ability to create Base Previews. Base Previews let you take a snapshot of a working Preview and use it as a starting point from where it can build new Previews. The advantage of Base Previews is they drastically reduce preview build times as well as the amount of space a preview occupies on disk.

Enjoy! As always, if you have any questions or concerns the best way to reach us is through our Slack channel. There’s a small community there ready to help!