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. For a quick preview of this walkthrough, check out our video here.

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.*), OS X Sierra (10.12.*)
  • Ubuntu (14.04 LTS, 16.04 LTS)
  • Amazon Linux (2016.03.3)
  • RHEL 6 & 7.2 (Yum/RPM)
  • Microsoft Windows - BETA (Windows 7, 10)

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.

Note: Client packages, with the exception of RHEL 6, now include Fugue Composer, refer to the Composer docs for additional details.

For Linux RPM (without Composer):

$ sudo rpm -ivh fugue-client*.rpm

For Linux RPM (including Composer):

$ sudo rpm -Uvh https://dl.fedoraproject.org/pub/epel/epel-release-latest-7.noarch.rpm
$ sudo yum localinstall fugue-client-desktop-*.rpm

For Linux DEB (without Composer):

$ sudo dpkg -i fugue-client*.deb

For Linux DEB (including Composer):

$ sudo dpkg -i fugue-client-desktop_*.deb
$ sudo apt-get install -f

For OSX PKG:

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

For Windows PKG:

Double-click on the .MSI 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.

Fugue generates IAM policies and roles for you during the install process. 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 know the region in which Fugue should operate – currently supported regions are:

  • us-east-1
  • us-east-2
  • us-west-2
  • eu-west-1
  • us-gov-west-1
$ fugue init <region>

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 --profile [PROFILE] <region>

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.

Possible Issues

If you encountered trouble while attempting to install Fugue, here are some common issues and their solutions:

Wrong AMI ID

Fugue selects a Conductor AMI ID for you during fugue init, as long as you provide a valid region. However, you have the option to provide a different Conductor AMI ID by using --ami id. Conductor AMI IDs are listed in the Download Portal.

If you provide an incorrect AMI ID, you’ll see this message:

fugue init us-east-1 --ami foo
[ ERROR ] There was a problem executing this command.
  Reason: "foo" is not a valid AMI ID.

If you receive this error, double-check your AMI ID and ensure it matches the one listed in the Download Portal. You can also execute fugue init <region>, without using the --ami id option, and Fugue will select the Conductor AMI for you.

The Fugue Conductor may only be installed in the following regions:

  • us-east-1
  • us-east-2
  • us-west-2
  • eu-west-1
  • us-gov-west-1

Incomplete Registration Process

If you didn’t complete the registration process in the Download Portal, your AWS account number may not have been whitelisted, and you will encounter one of the following error messages during fugue init:

You do not have access to any conductor in region <region>.
You do not have access to the <(TEAM|BASIC)> conductor in region <region>.

To fix it:

  • Complete the registration process at the Download Portal and ensure your AWS account ID has been entered properly.

Other Issues

Still having trouble installing Fugue? Reach out to support@fugue.co.

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.