User:2016fwilson/Conductor/User guide

From Livedoc - The Documentation Repository
< User:2016fwilson‎ | Conductor
Revision as of 10:42, 16 March 2016 by 2016fwilson (talk | contribs) (Created page with "= Conductor user guide = == What is Conductor? == Conductor is a system for managing Linux containers. What that means for you is that you can run applications on the CSL's...")
(diff) ← Older revision | Latest revision (diff) | Newer revision → (diff)
Jump to: navigation, search

Conductor user guide

What is Conductor?

Conductor is a system for managing Linux containers. What that means for you is that you can run applications on the CSL's infrastructure that previously were unsupported and thus difficult, if not impossible, to run.

Setup

Here's what you need in order to use Conductor: - A Computer Systems Lab workstation to work on (the system isn't accessible outside of the local network right now). - An authentication certificate. A CSL sysadmin can create this for you. Once this has been done, and you have a copy of your certificate, you'll need to install it. To install the certificate, open a browser (Chromium seems to work best) go to Settings, click "Show advanced settings", then "Manage certificates" (under the "HTTPS/SSL" header), then "Import." Find your certificate, then enter the certificate import password provided to you by whoever created the certificate. - A container to work with. Again, a CSL sysadmin can create this for you, and grant permissions in order for you to use it. Usually, you will want to use one container per project.

Using the system

There are a few important actions that aren't immediately obvious or intuitive. This section describes how to perform those actions.

Accessing Conductor

To access Conductor, go to this link from a Computer Systems Lab workstation. It is not accessible outside of the TJ network.

Accessing a container

All containers are accessible over the SSH protocol. In order to take advantage of this, you can use an SSH client program. In the CSL, you can do that by opening a terminal. In the terminal application, type "ssh root@address", where "address" is your container's IPv6 address, as displayed on the container's information page. When prompted for the password, copy and paste the string in the "comment" field, labelled "Initial root password." Do not include the string "Initial root password"; the password will only have alphanumeric characters.

Creating a new container

There aren't any obvious buttons in the interface for this, which is intentional! You'll need to contact a CSL sysadmin in order to have a container created for you.

Renaming a container

In order to rename a container, click the "edit" link next to its name. The name of the container will change to an editable box. Modify the hostname as you like, then click "edit" again. A few seconds later, the change will be saved, and the hostname will change back to its normal, non-editable state.

Deleting a container

If you're really sure you'll never, ever need a container again, you can destroy it. This process is irreversible, so don't do it unless you know for sure that you do not need the contents of the container. First, power off the container. A red button labelled "destroy" will appear. Click it, then confirm your action. The container will be destroyed.

Granting permissions

If you'd like to work with someone on a container, you will need to grant them permissions to it. Find the "Grant access" header. Directly under it, there is a dropdown menu with a list of system users. Find the user you would like to grant access to. Then, select what level of access you would like to give them. Here's a summary of the two different access levels:

  • view: A user with "view" access can see the container's ID, IP addresses, and comment.
  • modify: A user with "modify" access has full control over a container. A "modify" user can set the power state of the container, destroy the container, and change permissions. In addition, they can run additional management actions as defined by you. Be careful when granting users "modify" access.

Once you've chosen between these two, click "Grant access." A new entry should appear under the "Groups with access" header. If you ever need to revoke access, simply click the "revoke" link next to the appropriate entry.

Defining additional management actions

You may have noticed the header labelled "Additional management actions", and noticed that there were no "additional management actions" to perform. This is because by default, a container doesn't have any. In order to define some, create the directory /conductor/action on your container. Create a script in this directory that performs an action. Then, add the name of the script to the "/conductor/actions" file. You may have to create this file if it doesn't exist. An example session might look something like this:

root@anothertestnode:~# cd /conductor/
root@anothertestnode:/conductor# ls
power-off  set-hostname
root@anothertestnode:/conductor# mkdir action 
root@anothertestnode:/conductor# cd action/
root@anothertestnode:/conductor/action# cat > restart_service
#!/bin/sh
/etc/init.d/apache2 restart
root@anothertestnode:/conductor/action# chmod +x restart_service 
root@anothertestnode:/conductor/action# cd ..
root@anothertestnode:/conductor# echo restart_service >> actions

Once you've done this, a new "Invoke action" button will appear with the name of the action you've just defined. Clicking it will run the script that you've created.

Working with the Node.js template

Running Node.js applications on our infrastructure is usually impossible, because of the architecture of Node's runtime. Conductor allows you to run any application you like, including Node.js applications. The initial setup of a container built to run Node can be a little tricky, so follow these steps carefully. Make sure you're following these steps on a CSL workstation.

Initial setup

Creating an SSH key

If you don't already have an SSH key, you'll need one to push your app to your container. If you're not sure if you have an SSH key, try running this command:

cat ~/.ssh/id_rsa.pub

If you see some text starting with ssh, then you have a key. If you see an error along the lines of "no such file or directory", you'll need to generate a key:

2019username@ras2 ~ $ ssh-keygen
Generating public/private rsa key pair.
Enter file in which to save the key (/your/home/directory/.ssh/id_rsa): (just press "Return" here to accept the default)
Enter passphrase (empty for no passphrase): (again, just press "Return" to create a key without a passphrase)
Enter same passphrase again: (press Return)
Your identification has been saved in /your/home/directory/.ssh/id_rsa.
...
2019username@ras2 ~ $

Once you have an SSH key, continue to the next step.

Adding your key

You'll need to add your key to your container, so that you're able to push code. First, log in, following the steps in the "Accessing a container" section:

2019username@ras2 ~ $ ssh root@address
root@address's password:
...
root@yourcontainer:~# 

You'll need to have your SSH key ready for this step. Run the command

cat ~/.ssh/id_rsa.pub

on a separate terminal, and copy the results onto your clipboard.

Now, type the commands according to the example. When you are prompted for a key, paste the contents of your clipboard:

root@yourcontainer:~# /conductor/add-key
Key: (paste here)
Key added!
root@yourcontainer:~# exit

If your key was added successfully, you should be able to run the following command:

2019username@ras2 ~ $ ssh nodejs@address whoami
nodejs
2019username@ras2 ~ $

If you get an error when trying to run the above command, contact a CSL sysadmin. If you see "nodejs" or similar as the output, then you've done everything correctly!

Managing the container

Deploying your application

Now, you can use a tool like scp to deploy your application to the container. Assuming that your application is in a folder called "my-node-app" in your CSL home directory, you could do something like this:

2019username@ras2 ~ $ scp -r my-node-app nodejs@address:

Running your application

Now that you have an application in place, you can run it on your container. You're able to use npm to install missing dependencies as you normally would. You're also able to start your app as you would in development. Running your app will depend on what framework you're using, but an example session might look like this:

2019username@ras2 ~ $ ssh nodejs@address
...
nodejs@mycontainer ~ $ cd my-node-app
nodejs@mycontainer ~/my-node-app $ node app.js
Listening on port 8000

Again, you'll have to adjust the command you're using to start your app based on the tools you're using to build it.

Accessing your application

Now that you're running an application on your container, you can actually access it in a web browser. Go to "http://[address]/" where "address" is the IPv6 address of your container. You should either see your Node.js application, or an error page. If you see an error page, that page should give you enough information to fix the problem. If you have trouble, or are getting something different, talk to a CSL sysadmin.

Contact information

If you have any trouble with any of these steps, please contact a CSL sysadmin by emailing conductor-admins@tjhsst.edu.