Hello World, Part 1: Fugue Quick Setup

Overview

Welcome to Hello World, a walkthrough in three parts. This example is designed to teach absolute beginners how to install the Fugue CLI and Conductor, how to use Fugue, and how to write the Ludwig language.

In Part 1 – this part! – you’ll learn how to quickly set up Fugue. We explain how to install the Fugue Conductor and the Fugue CLI.

In Part 2, you’ll learn the basics of using Fugue. We explain how to use the Fugue CLI to manipulate Amazon Web Services infrastructure defined in a basic composition, or Ludwig file, called HelloWorld.lw.

In Part 3, you’ll learn all about the Ludwig language. We explain the structure and syntax of the HelloWorld.lw composition line by line.

Prerequisites

None! If you’re ready to get started with Fugue, we’ll walk you through the entire setup process, from downloading to configuring to installing.

What We’ll Do In This Example

We’ll show you where to download Fugue, how to install the Fugue Client Tools, how to configure your AWS credentials, how to initialize a project, and how to install the Conductor.

If you’re interested, we also have a hands-on demonstration of setting up Fugue using our recommended best practices (i.e. keeping the Conductor in a separate account) in our Using the Multi-Account Feature example from our Fugue by Example section.

What We’ll Have When We’re Done

A configured Fugue CLI and a running Conductor, setting you up for Hello World, Part 2: Fugue Basics.

How Long It Will Take

About 15 minutes. The Conductor will take an additional 5-15 minutes to boot up before you can run your first composition in Part 2.

Let’s Go!

Technical Requirements

To use Fugue, you need a couple of things – an account with Amazon Web Services (AWS) and a supported operating system:

  • OS X El Capitan (10.11.*)
  • Ubuntu (14.04 LTS, 16.04 LTS)
  • Amazon Linux (2016.03.3)
  • RHEL 6 (Yum/RPM)

Download Fugue Client Tools

You can register at https://fugue.co/users/register/ to request access to Fugue.

Once your request has been approved, you may log in to your account and download the Fugue Client Tools at the Download Portal.

Install Client Tools

After selecting the client package for the platform you’re working on, installation should be easy to follow. Instructions based on package type are included here. This installation step provides the CLI for Fugue.

Warning

These instructions use a wildcard filename for the package names. This works fine as long as you only have one matching file in the present directory. In addition, we recommend verifying that your version of Fugue meets the needs of your business, or reach out to support@fugue.co for details on a potential upgrade. The latest version of Fugue is available through our Download Portal.

For Linux RPM:

$ sudo rpm -ivh fugue-client*.rpm

For Linux DEB:

$ sudo dpkg -i fugue-client*.deb

For OSX PKG:

Double-click on the PKG file and follow the installation wizard.

Configure AWS Credentials

Note

This guide assumes you are running the Fugue CLI on a local machine. You can also easily run the Fugue CLI on an EC2 instance. If you choose to run the instance with a sufficiently privileged IAM role, you can skip this step.

Before you begin working with Fugue, you’ll need to set up AWS credentials on the client machine. This step ensures that Fugue is using the right credentials when interacting with AWS. The best way to do this is simply to use the AWS CLI’s aws configure command. Here’s a quick guide on getting set up with the AWS CLI, and then how to use it to configure AWS credentials for your machine.

Warning

The Fugue CLI does not support the use of AWS root account credentials. For details, see the explanation here.

While you can attach the AdministratorAccess policy to the IAM user associated with your credentials, we’ve made available two JSON policies with the minimum required permissions to run the CLI as an installer and as a user. For more information, see AWS Permissions and the Fugue CLI.

Initialize a Project

Fugue work is done in project directories. This makes Fugue projects easy to work on in version control systems. The project settings are saved in a fugue.yaml file that includes the AMI ID of the Conductor and the name of the AWS credentials profile to use for commands, if the default profile is not used. You may optionally customize your fugue.yaml with many more technical and advanced settings. All of this is set up using the fugue init command, and you can read more about init in the Fugue CLI Reference.

Note: Your AWS credentials are not checked in to version control.

Once you’ve made a directory for your Fugue project and made it your present working directory, you’re ready to initialize. Just make sure you have the AMI ID for the image you want to launch the Fugue Conductor with (which you can find at our Download Portal):

$ fugue init [AMI]

Optionally, you can specify an AWS credential profile to use. This is only necessary if you used the --profile flag when you ran aws configure. If you didn’t, you set credentials for the default profile, and that is the profile Fugue commands will use. If you did set a certain profile name, fugue init conveniently uses the same flag to define the profile for Fugue commands:

$ fugue init [AMI] --profile [PROFILE]

If you run ls, you should now see a file called fugue.yaml. The fugue.yaml file maintains the settings for the Fugue initialization process and guides the Fugue CLI through its various operations.

See the init reference for more information about the fields in fugue.yaml and how to customize them.

Install the Conductor

There are two components of Fugue to install. You’ve already installed the CLI, which is installed on a client machine such as your laptop, or an EC2 instance you’re using as an SSH bastion host.

The second component is the Fugue Conductor, which is comprised of an EC2 instance and several other resources and is installed resident in your AWS account. Installation of the Fugue Conductor is easy, and takes just about long enough for you to go and get a sandwich.

Note

This step is only required if you do not have a Fugue Conductor running in your account. If you or someone on your team has already installed the Fugue Conductor, skip this step.

To install the Fugue Conductor, simply type:

$ fugue install

The Fugue CLI determines the target AWS account for Conductor installation by sourcing AWS credentials in the following order:

  • The environment variables AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY; then,
  • The profile in ~/.aws/credentials or ~/.aws/config that matches the credentialProfile field in fugue.yaml; then finally,
  • The instance metadata service (IMDS), which is present only on EC2 instances and provides credentials reflecting the IAM Role of the instance.

The CLI asks you to confirm that you want to proceed with installing the Conductor into the target AWS account. Make sure that this is the account you want to use.

The CLI displays the installation progress and tells you when the Fugue Conductor and its dependencies have been successfully created.

Once the Fugue Conductor is installed, it needs another 5-15 minutes to boot up. The CLI displays a message asking for your patience while it boots Fugue. You’ll know it’s safe to go to the next step when the CLI returns you to your command prompt and displays this message:

[ Done ] Fugue has been successfully installed and is ready to receive commands.

That’s it! Fugue is ready for you to use.

You’re Done With Part 1!

Congratulations! You’ve learned how to install the Fugue Client Tools, configure your AWS credentials, initialize a project, and install the Fugue Conductor. Pat yourself on the back, and get ready for Part 2!

Next Steps

Now that you have Fugue installed, you’re ready for Hello World, Part 2: Fugue Basics, where you’ll learn the basics of using Fugue! Or, if you want to jump right in to other examples, you can browse the walkthroughs available in Fugue by Example.