Getting Started

This guide will walk you through the initial steps of getting an account, joining a project and working with your first instance.

Step 1: Create a Chameleon account

You will first need to create a user account.

This includes agreeing to the Chameleon terms and conditions which, among others, ask you to acknowledge the use of Chameleon in your publications. As part of creating an account you may request PI status, which means that you will be able to create and lead Chameleon projects. PI status is typically available to faculty members or research scientists at a scientific institution.

Important

If you are a student, do not request PI status.

After you have verified your account using the link sent via e-mail, you may continue to create a project if you are a PI, or join a PI’s project if you are a student.

Step 2: Create or join a project

To use Chameleon, you will need to be associated with a project that is assigned an allocation.

If you are a PI, you may apply for a new project. A project application typically consists of a description of your intended research and takes one business day to process. Once your project has been approved, you may add users to your project.

If you want to join an existing project, ask the PI of the project to add you to their project. They will need your Chameleon username.

For more information about project management, please see the Project Management section or FAQs about project management.

Step 3: Start using Chameleon!

Congratulations, you are now ready to launch your first instance! Instances are much like what you may expect to find in a virtual machine, except here the instances are on bare-metal nodes - the core feature of Chameleon. A bare-metal node is a whole physical server that you have exclusive access to. An instance is going to be a bare-metal node that has been launched with an operating system image. Follow these steps to make a reservation for a node, launch an instance and log in to it.

Note

Chameleon also offers a multi-tenant, virtualized cloud, with fewer functionalities and a smaller scale. See KVM for more details.

The Chameleon Dashboard

Chameleon resources are available at two sites. You may login to the Chameleon Dashboard for resources at the University of Chicago or the Texas Advanced Computing Center. Use the account name and password that you signed up with.

Note

If you change your account password, it can take up to 15 minutes for the change to propagate to each dashboard.

The Chameleon Dashboard login

The Chameleon Dashboard login

Once you are logged in, you should see a summary of your project’s current resource usage. It should look like this:

The Chameleon Dashboard's resource usage summary

An overview of your project’s current resource usage

Reserving a Node

First, we need to reserve a node for our use. Chameleon provides bare-metal access to nodes. When you create a reservation for one or more nodes, only you and other users on your project will be able to use those nodes for the time specified. We will create a single day reservation for a compute node, which are the most common types of nodes available on Chameleon.

  1. In the sidebar, click Reservations, then click Leases
  2. Click on the + Create Lease button in the toolbar
  3. Type my_first_lease for the lease name
  4. Find the Resource Properties section. In the dropdown below node_type, select compute_haswell
  5. Click the Create button
The Create Lease dialog

The Create Lease dialog - be sure to select compute_haswell in the dropdown below node_type

The reservation will start shortly, at which point you can launch an instance on a bare-metal node.

Note

You have created an “on demand” reservation. When you do not specify a start date or time in the future, the reservation will start as soon as possible and will last one day.

Important

Do not attempt to stack reservations to circumvent the 7-day lease limitation. Your leases may be deleted. Please refer to our best practices if you require a longer reservation.

Launching an Instance

Once the reservation starts, you can launch a bare-metal instance on the node that has been leased to you.

  1. In the sidebar, click Compute, then click Instances

  2. Click on the Launch Instance button in the toolbar and the Launch Instance wizard will load

  3. Type my_first_instance for the instance name and select your my_first_lease reservation

    Launch details

    Enter an instance name and select your reservation

  4. Click Source in sidebar. Then, find CC-CentOS7 in the image list and click the Up arrow to select it.

    Selecting an image

    Select the CC-CentOS7 image

  5. Click Flavor in sidebar. Select the baremetal flavor.

    Select the baremetal flavor

    Select the baremetal flavor

  6. Click Keypair in sidebar. Click the + Create Key Pair button and enter mychameleonkey for the key name. This will automatically start a download for a file named mychameleonkey.pem. This is your private key pair that you will use to access your instance.

    Create a keypair to secure your instance

    You can create or import a public/private keypair for accessing your instance.

  7. Click the Launch Instance button.

Congratulations, you have launched an instance on a bare-metal node!

Associating an IP Address

Your instance may take approximately ten minutes to launch. The launch process includes powering up, loading the operating system over the network, and booting up for the first time on a rack located either at the University of Chicago or the Texas Advanced Computing Center, depending on where you chose to launch your instance. Before you can access your instance, you need to first assign a floating IP address - an IP address that is accessible over the public Internet.

  1. If you don’t see your instance, go to the Instances list by clicking on Compute and Instances in the sidebar.

  2. Locate your instance. It is probably in the Spawning state.

    The current state of your instance

    Your instance is probably in the “Spawning” state

  3. Click the Associate Floating IP button. A dialog will load that allows you to assign a publicly accessible IP.

    The Manage Floating IP Associations dialog

    Here you can assign a floating IP address

  4. You may allocate a floating IP for your project by clicking on the + button next to the dropdown that says Select an IP address. A new dialog will open for allocating floating IP.

    The Allocate Floating IP dialog

    This dialog allows you to allocate an IP address from Chameleon’s public IP pool

  5. Click the Allocate IP button. You will return to the previous dialog and an IP address will be selected for you.

    You have now allocated a floating IP

    You have now allocated a floating IP address

  6. Click the Associate button and make note of the public IP address that has been associated to your instance.

Accessing Your Instance

Once your instance has launched with an associated floating IP address, it can be accessed via SSH using the private key that you downloaded during the Launching an Instance step.

Note

The following instructions assume that you are using a macOS or Linux terminal equivalent. You may view our YouTube video on how to login via SSH on Windows.

To log in to your instance, follow these steps:

  1. Open a terminal window and navigate to where you downloaded the mychameleonkey.pem file. Change the permissions on the file to user read/write only:

    chmod 600 mychameleonkey.pem
    
  2. Add the key to your current SSH identity:

    ssh-add mychameleonkey.pem
    
  3. Log in to your Chameleon instance via SSH using the cc user account and your floating IP address. If your floating IP address was 129.114.108.102, you would use the command:

    ssh cc@129.114.108.102
    

    Note

    Change the IP address in this command to match your instance’s floating IP address!