Getting Started with BowTie

This post will walk through the basics of getting spun up on BowTie, and demonstrate our recommended workflow. BowTie is designed for developers and agencies building sites and static apps for clients. We provide a git based workflow for developers and designers, and a simple and customizable cloud editor for non-technical content creators.

For Designers/Developers

To work with BowTie you will need to do a bit of basic setup. You’ll need an SSH key, a file editor, the BowTie client (for working locally), and a basic understanding of git. We also allow you to design and build custom interfaces for your clients/collaborators using Jekyll collections.

For Content Creators

BowTie provides a hosted editor for creating, editing, and removing content on your site (see below). Your workflow will be provided by the developer who set up your site. If you are working with templates provided by BowTie, you can learn how to work with content in our guide on blogging, our collections guide, and our theme guide. If you would like to access your full project repository or plan to work with content locally, read on.

Publishing content on BowTie

BowTie Markdown Editor

Basic Setup

Configuring SSH keys

Similar to GitHub and BitBucket, BowTie authenticates repository access using SSH. You’ll need to set up an SSH keypair in order to access your repository. If you already have an SSH key, copy and paste your public key into the BowTie dashboard.

Locating Your SSH Key:

For OSX systems, run $ pbcopy < ~/.ssh/id_rsa.pub to copy the contents of your public key into the clipboard. If you’re running another system, just open the ~/.ssh/id_rsa.pub file and copy the contents manually.

Note: When debugging repository access, comparing the key fingerprints is a good place to start. To determine the fingerprint of the key on your system, you can run the following from your terminal: ssh-keygen -l -f ~/.ssh/id_rsa.pub

Generating an SSH Key

If you’re new to SSH, or if you don’t already have an SSH key follow this process:

Step 1: Open your Terminal and type: ssh-keygen to return:

Generating public/private rsa key pair.
Enter file in which to save the key (/Users/user/.ssh/id_rsa):[]

Press Enter to save the new key to the default location.

Step 2: Create a passphrase:

Enter passphrase (empty for no passphrase): [Type a passphrase]
Enter same passphrase again: [Type passphrase again]

Step 3: After you enter a passphrase, the system returns the fingerprint, or id, of your SSH key:

Your identification has been saved in /Users/user/.ssh/id_rsa.
Your public key has been saved in /Users/user/.ssh/id_rsa.pub.
The key fingerprint is:
6f:10:2d:b6:67:f0:99:8f:b9:61:dc:7c:3f:a1:84:5f james@Jamess-MacBook-Pro.local
The key's randomart image is:
+--[ RSA 2048]----+
|                 |
|         .       |
|        = .      |
|       . * o     |
|        S * .    |
|         * B . E |
|          O * + .|
|         o o + o |
|          .     o|

Note: We configured a default key at ~/.ssh/id_rsa[.pub]. BowTie will work with an alternative key, and custom key locations. Keys must be at least 512 bits.

Adding your key to BowTie:

After locating or creating a key as detailed above, visit your BowTie Account Keys page and paste the contents of your clipboard into the “Key” field. Give the key a title that you’ll remember this machine by and hit “Save.” You’ll see a list of Keys that you’ve added to the system by their title and a fingerprint. BowTie allows access with a single key per user account.

Installing the BowTie Client

For local development, use the BowTie Client. Our client provides the same functionality as the Jekyll development server with additional features accessible by your BowTie project (backend proxy support, policy management, test payment environment etc).

To use the the BowTie Client, you’ll need to install the bowtie-io gem on your system.

From your terminal run: gem install bowtie-io

This should return:

Fetching: bowtie-io-1.x.x.gem (100%)
Successfully installed bowtie-io-1.x.x
Parsing documentation for bowtie-io-1.x.x
Installing ri documentation for bowtie-io-1.x.x
Done installing documentation for bowtie-io after 0 seconds
1 gem installed

Once the client is installed, you can now launch your BowTie project locally by visiting the root directory of your cloned project and running bowtie serve.

You can run $ bowtie --help for a full list of supported options.

Making Updates to Your Project Files

From there, start with one of our example templates, or build a static app using any of our Jekyll templates and components. We offer a number of user guides to help you get started.

Workflow

Cloning

If you’re unfamiliar with Git, please thoroughly read the documentation before starting development.

After creating a Project you will be returned to your dashboard. Look for your ‘SSH clone URL’ in the top middle of the page. Copy this URL, open terminal, and clone your repository to your local system using this command: git clone git@git.bowtie.io/example (Replacing git@git.bowtie.io/example with the Clone URL from your Project Dashboard.)

This should yield something similar to:

Cloning into 'example'...
remote: Counting objects: 215, done.
remote: Compressing objects: 100% (205/205), done.
remote: Total 215 (delta 18), reused 0 (delta 0)
Receiving objects: 100% (215/215), 1.57 MiB | 576.00 KiB/s, done.
Resolving deltas: 100% (18/18), done.
Checking connectivity... done.

You’ll now have a local directory at the location specified in your clone URL. In this example it is at ./example

The files in this directory will match the files in the master branch of your BowTie project repository. You can now access and edit those files from your local environment, and push them back to the server when you are ready to publish the site changes.

Previewing Changes

In your cloned Project’s directory, run the BowTie client with this command: bowtie serve

The yield will look like this:

`Configuration file: /Users/user/example/_config.yml
            Source: /Users/user/example
       Destination: /Users/user/example/_site
      Generating...
                    done.
 Auto-regeneration: enabled for '/Users/user/example'
Configuration file: /Users/user/example/_config.yml
[2015-02-03 15:52:02] INFO  WEBrick 1.3.1
[2015-02-03 15:52:02] INFO  ruby 2.1.3 (2014-09-19) [x86_64-darwin13.0]
[2015-02-03 15:52:02] INFO  WEBrick::HTTPServer#start: pid=66488 port=4000`

This launches the development server at “http://localhost:4000”, which you should now be able to visit with a browser.

The BowTie client wraps the general Jekyll system, and captures requests to /users/* and /bowtie/* which BowTie’s platform will handle for you.

File changes trigger a rebuild without needing to restart the server. You will also see errors rendered in the output of the terminal.

Publishing Changes

Changes made on your local system need to be committed, then pushed up to your repo for deployment.

The process is pretty straightforward. (If you need a primer on using git commands, read this.)

Check your status to verify your branch

git status

Add your new content to a commit, including a commit message for future reference

git add _posts/2015*

Then

git commit -a -m "Adds Post on Lack of Sleep"

The yield should look like this:

1 file changed, 18 insertions(+)
 create mode 100644 _posts/2015-02-03-lack-of-sleep-and-startups.markdown

Now, you just need to push those changes to BowTie

git push origin

Visiting your site (in this case “https://example.bowtied.io/”), shows the changes have been applied.

Team Development

Project owners can invite any other BowTie user to access their project from the Dashboard. The shared project appears in each contributor’s project dropdown.

In your dashboard, visit the Team page found in ‘Settings’ > ‘Team’ and enter your desired collaborator’s email address (must be an active BowTie account) in the ‘Add Team Member’ field. If the account is found, an ‘Add to Team’ button will appear, allowing you to grant access to your project.
Both the primary Project Owner and Contributor can remove Contributor access at any time by selecting the ‘Remove’ option next to the Contributor’s name on this page.

Team members who install SSH keys will be able to access the repository from the command line. Failure to do so will result in access/permission errors.