tugboatqa/docs

Tugboat Docs

Welcome to Tugboat!

Tugboat is a system that builds a working preview of a 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.

This document aims to provide the information required to use Tugboat. It includes tutorials, examples, and references for all experience levels.

Contributing

This document is open-source, and is available on GitHub. If you have any suggestions or other feedback about this document, we are happy to hear it! Open a GitHub issue or email us at [email protected].

Theme

The Hugo Learn Theme is included in this repo as a git subtree. To update the theme, find the latest tag at https://github.com/matcornic/hugo-theme-learn/releases and run the following

export TAG=2.4.0
git subtree pull --prefix themes/hugo-theme-learn https://github.com/matcornic/hugo-theme-learn.git $TAG --squash

Redirects

Redirects for historic URLs are maintained in static/.htaccess. These can be tested using Smolder config file in test/smolder.yaml. The tests need to be run against a live instance, like a Tugboat preview.

cat test/smolder.yaml | docker run -i mcameron/smolder pr125-mcktkhcj8krhxo5oaa7emgv5gcnf5e5l.tugboatqa.com

License Information

This document is licensed as Creative Commons Attribution-NonCommercial-ShareAlike CC BY-NC-SA.

Everything not covered above is licensed under the MIT license.

docs's Issues

Visual Diffs

Revise Visual Diffs page, including:

• Organize into sections:
  • Setting up Visual Diffs
  • Using/Viewing Visual Diffs
• Add note about visualdiffs service key (linked to Setting up Services -> Service Attributes -> visualdiffs
• Pull in some of the info from the visualdiffs attribute writeup to the Visual Diffs page
• Add a section about the visual diff config being in whatever you're building (See info from Ben)
• Add note about using visualdiff under php vs. apache, etc. (see note from James)

Tugboat CLI -> Review Commands

• Add a section about viewing logs
• Create links to this section from Troubleshooting page

Setting-up-Tugboat -> Connect with your provider

• Add a section about how to connect with a provider if you've already created a project

Add info to docs re: Tugboat's IPs

(from conversation in Support Slack)

Troubleshooting -> Running a background process

• Point ppl at Running a Background Process (from Support Slack, user running Etherpad application in development server, hence is a never-ending command)

Document how to create a GitHub "bot" user for commenting

1. Create a GitHub Tugboat user
2. Grant that user access to your GitHub repo
3. Generate a token for that user
4. Log back into GitHub with your personal account
5. While on the Tugboat Dashboard for the Repository, click Repository Settings
6. Scroll down almost to the bottom until you see GitHub Comments
7. Click the Change button and add your GitHub Tugboat token there

Fix link to shared Makefile source

The link to the shared Makefile source is broken.

Reference

Review/edit Reference docs, and incorporate into docs where possible:

• Config File
• Prebuilt Service Images
• Environment Variables
• Actions and States
• Glossary

Code Snippets

Review/Edit docs for:

• Drupal 7
• Drupal 8
• WordPress
• Pantheon
• Static HTML
• Generic LAMP
• Import a MySql Database
• Run Functional Tests
• SimpleTest
• Warm a Page Cache
• Tenon.io Integration
• Add a phpMyAdmin Service

Add SSH key link to Code Snippets

• After adding documentation to Setting-up-Tugboat -> Repository Settings -> SSH key, add links to SSH key area in Code Snippets -> Tutorial examples

Building a Preview -> Preview Deep Dive -> How Previews Work -> The Build Snapshot

• Add info to this page about containers being stopped and then restarted while the snapshot is taken/committed. This will kill any "sleeping" processes waiting for completion. Advice is to look at runit documentation, per Ben's response in the Support Slack.

Also, add info around this to Troubleshooting -> Fix Problem X

Document how to use Drupal multisite / add aliases

Topics might include:

1. How do you point a custom domain? (Use CNAME preview.tugboat.qa)
2. When using a custom domain, how do you get https working?
3. What are aliases?
4. How would you set up a Drupal Multisite installation?

Explain how preview size is calculated

We are not very up-front about how these calculations are made. Let's add a section somewhere to lay it all out.

Deprecate "Advanced" section of docs:

CLI and Background Process have already been incorporated elsewhere in docs. Figure out a place to put "Custom Environment Variables" and then remove "Advanced" from the site.

• Put "Custom environment variables" content somewhere else
• Edit links to custom-environment-variables/index.md to reflect new location
• Add "Advanced" pages to .htaccess

Building a Preview -> Preview Actions that start at `init`

• Missing auto-build a Preview from a PR with no Base Preview

Troubleshooting -> Debugging config files

• Shell
• Locally via command line
• Brute force push changes to git

Building a Preview -> How Base Previews Work

• Add a paragraph (or maybe a callout?) to this section pointing out that subsequent Preview builds start at build - and/or link to build stages explained

Deprecate "Concepts" section of docs

• Verify that all "concept" content is explained elsewhere in the docs, and if not, expand docs
• Remove "concepts" from the site
• Add "concepts" pages to .htaccess

API documentation for previews/rebuild

CLI Documentation

We need some formal documentation about how to use the Tugboat CLI.

I'm not sure where to put this, but this is how I got the CLI up and running on my mac.

curl --remote-name https://dashboard2.tugboat.qa/cli/macos/tugboat
chmod +x ./tugboat
mv ./tugboat /usr/local/bin/

Some instructions similar to this would be helpful, but I'm not sure how to put it into the current page.

and for what it's worth, curl doesn't add the ".dms" extension like Safari does.

Fix Tugboat logo in `hugo-migration` branch for the new docs site.

Here's the HTML for the logo:

https://github.com/TugboatQA/docs/blob/hugo-migration/layouts/partials/logo.html

The working doc for custom CSS is here:

https://github.com/TugboatQA/docs/blob/hugo-migration/static/css/tugboat.css

The directory for the SVGs are here:

https://github.com/TugboatQA/docs/tree/hugo-migration/static/images

Add a robots.txt

Looks like we're missing a robots.txt in this site:

$ curl -I https://docs.tugboat.qa/robots.txt
HTTP/1.1 404 Not Found
Date: Mon, 09 Apr 2018 19:09:43 GMT
Server: Apache/2.4.33 (Unix) OpenSSL/1.0.2l
Content-Type: text/html; charset=iso-8859-1

Broken links on References page

Links to anchors with underscores are broken on https://docs.tugboat.qa/reference/tugboat-configuration/.

For example, checkout_path links to https://docs.tugboat.qa/reference/tugboat-configuration/#checkoutpath, but should link to https://docs.tugboat.qa/reference/tugboat-configuration/#checkout-path

This appears to be a difference in rendering between gitbook and hugo

Visual Diffs -> How are visual diffs calculated?

Per conversation with Ben:
Visual Diffs = pixel by pixel comparison of Before and After. % calculation is a literal calculation of how many pixels have changed in the page from Before to After. If you move something at the top of the page that bumps content down, the whole page may show up as changed as a result. Consider adding info around this to the Using Visual Diffs page, and possibly Troubleshooting - i.e. why does my entire page show as changed?

Troubleshooting -> Tugboat Errors

• Failed to refresh preview
  • Tugboat Error 1064: Command Failed: Exit code (1)
  • Check Preview log for errors (1074, etc.)

Setting-up-Tugboat -> Repository Settings -> SSH Key

• Add more documentation around setting up/using SSH key

API documentation for webhooks/list endpoint

Setting up Tugboat -> Repository Settings

• Add Build Previews for Forked Pull Requests under Modify settings for your GitHub, GitLab or Bitbucket Integration

By default, Tugboat will not build Previews for forked PRs. Click this setting to enable this feature. When this feature is not enabled, Forked PRs will show up as available to build, but users will get an error if they try to build them.

Add a page that roughly amounts to "Why you don't need HTTP Auth, but how to add it anyway"

index.md links don't work

Any URL that links to index.md doesn't open on docs.tugboat.qa

There are a couple URLs to test on this page here:

https://docs.tugboat.qa/getting-started/create-a-preview/

Setting up Tugboat -> Add Repos to the Project

• For consistency with other pages, break out Add repos to the project into separate sections: new project, add repos to existing project.

FAQ

• Review/edit FAQ, and incorporate into docs where possible

Help and Support

• Review/edit/confirm is all good for new site

Defining Variables

Matt pointed out in the Support Slack that developers could define variables in their config files, like so: https://gist.github.com/mettamatt/18b9febcf4c33aa7cea8b1d757d9e934#file-lighthouse_config-yml-L27

Add a note about this to docs - maybe under custom environment variables?

Starter Configs -> Tutorials (Google Lighthouse)

Create a page for Adding Google Lighthouse to your Tugboat Project, verify that this process works: https://tugboat.qa/2018/09/18/automating-google-lighthouse.html

Add anchor links next to headings

It's helpful to be able to link directly to a heading, especially with support requests. Thankfully, there's a gitbook plugin for this:

https://plugins.gitbook.com/plugin/anchors

Use a Tugboat favicon

Let's use the same favicon(s) as https://tugboat.qa

Add details about --help to Tugboat CLI doc

The Tugboat CLI documentation should explicitly state that -h, --help can be used to query a specific command for more details (i.e. the args you can use with that command, etc.)

Administering Tugboat crew -> User permission levels explained

Add a screenshot for read-only users; as a regular user or admin, I have no easy way to know exactly what that is. For example, does the "preview" button for previews show all configured URLs for all services, or just the first one?

Search Results Page

With the transition to Hugo, we are losing the search feature from our 404 page. It'd be great to get that back, but it's going to take a little doing. I found an article explaining one way to do it, which looks promising.

https://codewithhugo.com/hugo-lunrjs-search-index/

Setting-up-Tugboat -> Repository Settings Access

• Add info about accessing Repository Settings when you’re not in the Setting Up phase

Troubleshooting -> Visual Diffs

• Add section about Visual Diffs
  • Visual diff based on config in the branch?

Troubleshooting -> Build Preview

• 1074: Repo configuration does not allow building of pull requests from forks - go to Build Previews for Forked Pull Requests (in Repository Settings) and enable it

Missing Google search results do not have redirects

Sometimes I use Google to find docs, and several times recently I've searched for something on Google and gotten a 404:

Troubleshooting -> PHP out of memory

• PHP out of memory issues
  - echo "memory_limit = 512M" >> /usr/local/etc/php/conf.d/my-php.ini

Apache redirects

• Confirm apache redirects for removed pages/new pages in the doc site update

Deprecate "Configuring Tugboat" section of docs:

• Verify that all "Configuring Tugboat" content is explained elsewhere in the docs, and if not, expand docs
• Remove "Configuring Tugboat" from the site
• Add "Configuring Tugboat" pages to .htaccess

FAQ -> Slack integration

• Add Q about Slack integration, point out GitHub (and other provider?) Slack integrations as alternative

Improve Drupal 8 example and associated config.yml

1. Our Drupal 8 Makefile doesn’t fix permissions on the file directories
2. Private files and exported config are typically stored outside the webroot. Since the webroot is a symlink, that can get funky.
3. IIRC, our D8 Makefile didn’t have composer install in the build target

We also should make sure that our Drupal 8 example tugboat project uses the same Makefile.

Troubleshooting -> MySQL

• MySQL server has gone away"
  - resolved by increasing the packet size for MySQL