Skip to content

Home

Jump to bottom
Adam Doppelt edited this page Jun 30, 2013 · 45 revisions

Welcome to Teleport

Teleport is a lightweight way to set up Ubuntu machines. The name derives from the mechanism that teleport uses to setup the target machine - it copies itself onto the target machine via ssh and then runs itself there. In effect, it "teleports" to the target. This design makes it possible for teleport to bootstrap itself onto a fresh machine. There's no need to install ruby or anything else by hand.

Teleport strives to be idempotent - you can run it repeatedly without changing the result. In other words, as you build up your Telfile you can generally run it over and over again without fear of breaking the target machine. It also works hard to only print status when packages, files or directories actually change.

Teleport is great for managing a small number of hosted machines, either dedicated or in the cloud. Due to it's opinionated nature and limited scope you may find that it works better for you than other, more complicated tools.

At the moment Teleport supports Ubuntu 10.04-13.04 with Ruby 1.8.7, 1.9.2, 1.9.3, 2.0.0 or REE.

Table of Contents

Getting Started

  1. Install Teleport on your local machine.

    $ sudo gem install teleport

  2. Create a Telfile. Here's a simple example. Note that we actually define two machines, server_app1 and server_db1:

    $ mkdir ~/teleport
$ cd ~/teleport

    Put this into ~/teleport/Telfile:

    user "admin"
ruby "1.9.3"
apt "deb http://downloads-distro.mongodb.org/repo/ubuntu-upstart dist 10gen", :key => "7F0CAB10"
role :app, :packages => [:memcached]
role :db, :packages => [:mongodb-10gen]
server "server_app1", :role => :app
server "server_db1", :role => :db
packages [:atop, :emacs, :gcc]

  3. You'll want to copy files to your new machines too. Put the files into your teleport directory. For example, maybe you want to automatically have your .bashrc and .emacs files copied to your target machine. You'll want the memcached and mongodb config files too. Here's what your teleport directory should look like:

    Telfile
files/home/admin/.bashrc
files/home/admin/.emacs
files_app/etc/default/memcached
files_app/etc/memcached.conf
files_db/etc/mongodb.conf

  4. Now run Teleport:

    $ teleport server_app1

Teleport will ssh to the machine and set it up per your instructions.

Order of Operations

Here is the exact sequence of operations performed by Teleport on the target machine:

  1. install ruby
  2. install/update rubygems and bundler
  3. set the hostname (/etc/hostname, hostname -F and /etc/hosts)
  4. create the user account and setup sudo
  5. copy id_teleport public key if possible
  6. configure apt (this may require a second apt-get update)
  7. install packages
  8. install Gemfiles
  9. install files

A Word About SSH

Make sure you can ssh to the target machine before you try running Teleport!

Teleport copies itself to the target machine and runs there. It uses ssh to connect to the target. Remember that ssh will use port 22 and your current username by default when connecting. This is most likely NOT what you want.

Before running Teleport against a new machine, you may need to add a section to your ~/.ssh/config file:

Host server_*
User ubuntu
IdentityFile ~/path/to/your/sshkey

Depending on your needs, you may want to change your ssh config once Teleport finishes setting up the machine.

/etc/hosts

To reiterate, Teleport just uses straight ssh to get the job done. You might need to edit your /etc/hosts file so that ssh can find your target machine. We recommend that you always use hostnames instead of IP addresses. Whenever you bring up a new machine, simply add it to your /etc/hosts file.

id_teleport

Some machines are pre-provisioned with ssh keys, like Amazon EC2 boxes. For other providers you just get a root account and a password. Wouldn't it be nice if Teleport would automatically set up a key for you?

If you provide a public key, Teleport will copy it to ~/.ssh/authorized_keys on your target machine automatically. It looks for your public key here:

~/.ssh/id_teleport.pub

You can use an existing key, or create a new one with this command:

$ ssh-keygen -t rsa -f ~/.ssh/id_teleport

Telfile

Your Telfile explains how to set up your machine(s). Here are the supported commands:

ruby

ruby "REE"

The version of ruby to install on the target. You can specify:

  • 1.9.3 (default)
  • 1.9.2
  • 1.8.7
  • REE

user

user "admin"

The account to create on the new machine. This account will be created along with /etc/sudoers.d/teleport to let the user sudo. Also, id_teleport will be copied to ~/.ssh/authorized_keys if provided. See A Word About SSH.

If you don't specify a user, Teleport will use the current username from your machine.

apt

apt "deb http://downloads-distro.mongodb.org/repo/ubuntu-upstart dist 10gen", :key => "7F0CAB10"

Add apt sources and keys. You can call this repeatedly.

This will add that line to /etc/apt/sources.list.d/teleport.list and add the key using apt-key if necessary. If necessary, Teleport will run apt-get update.

packages

packages %w(atop imagemagick nginx wget)

A list of packages to install using apt-get. These will be installed on all machines regardless of role. Be sure to use apt to add sources if necessary.

server

server "server1", :packages => [:xfsprogs] # install xfsprogs
server "server2", :role => :db # this machine is a db

Customize each target machine, either by specifying packages directly or by using roles. You don't have to use server at all, but if you use it Teleport will insist that you use it for all of your machines.

role

role :app, :packages => [:imagemagick, :nginx]
role :db, :packages => [:"mysql-server"]

Just like with Capistrano, roles are used to group similar machines. A role is nothing more than a way to say "install these packages and files for all machines of this type." Note that roles are totally optional - you don't have to use them at all.

Then you can use the roles when you define your servers:

server "server_app1", :role => :app
server "server_app2", :role => :app
server "server_app3", :role => :app
server "server_db1, :role => :db

Roles are also used to figure out which files to install. See Files.

ssh_key

ssh_key "/home/admin/my_key.pub"

Set this if you want to put your teleport public key somewhere other than id_teleport.pub. Totally optional, of course.

Files

After Teleport finishes installing packages, it will copy files to the target machine from files/. If your server defines a role, it will copy files_<ROLE>/ as well. Permissions and timestamps will generally be copied from the source file. Files will be owned by root unless they live in /home.

Also, you can use ERB to create templates. For example, you can customize the prompt on each server by creating files/home/admin/.bashrc.erb:

PS1='<%= host %> $'

Or you can make it more elaborate:

<% if host == "server1" %>
PS1='Don't mess with this machine!!! $'
<% end %>

Gemfiles

Teleport can install system-wide gems using one or more Gemfiles. After Teleport finishes installing packages, it will look for Gemfiles. First it will check for files/Gemfile, then files_<ROLE>/Gemfile. Note that if you create a Gemfile, you must create a Gemfile.lock file as well. Teleport used bundler to install the Gemfiles.

Infer (reverse engineer an existing server)

Teleport can create a simple Telfile by reverse engineering the packages and files from an existing server, or even your local machine. It's similar to blueprint, though much simpler. Many thanks to blueprint for implementation ideas.

Teleport will print out a Telfile based on the local machine, including apt sources, packages and files from /etc. It doesn't write anything to disk - it just prints to stdout.

Infer a Telfile like this:

$ teleport --infer

########################################################################
# Telfile inferred from xyzzy
########################################################################

user "me"
ruby "REE"
apt "deb http://downloads-distro.mongodb.org/repo/ubuntu-upstart dist 10gen", :key => "7F0CEB10"
apt "deb http://ppa.launchpad.net/mozillateam/firefox-stable/ubuntu lucid main", :key => "CE49EC21"
apt "deb http://ppa.launchpad.net/webupd8team/sublime-text-2/ubuntu lucid main", :key => "EEA14886"

packages %w(apache2 apache2-threaded-dev atop autossh beanstalkd ...)

########################################################################
# Also, I think these should be included in files/
########################################################################

# /etc/environment
# /etc/mongodb.conf
# /etc/nginx/nginx.conf
# /etc/rc.local
# /etc/ssh/ssh_config

# You can do that with this magical command:
#
# mkdir files && cd files && tar cf - ...

Callbacks

Telfile supports an extensive callback mechanism which can be used to customize installation. Here are some handy things to do inside callbacks:

  • start/stop services
  • turn iwatch off, then on again when teleport completes
  • setup munin plugins
  • call debconf before packages are installed
  • delete the default "ubuntu" user on EC2
  • print a REMIND so you won't forget to scp your custom ssh key
  • etc.

See Callbacks.

Recipes

Looking for existing recipes or inspiration to write your own? See our list of Recipes.

Use Cases

Looking for help installing a specific package? See our list of Use Cases.

Limitations

There are a few limitations that you should be aware of:

  • Only supports Ubuntu 10.04-12.10 with Ruby 1.8.7, 1.9.2, 1.9.3, or REE.
  • Ruby is installed system-wide and RVM is not used.
  • Only a single role per server. This differs from Capistrano.
  • Only runs against one server at a time. You have to run it against each server individually. This differs from Capistrano.

Changelog

1.0.19

  • Use Ruby 1.9.3-p448 and 2.0.0-p247

1.0.18

1.0.17

  • fixed 1.8.7 on 13.04

1.0.16

  • Use Ruby 1.9.3 p429 and 2.0.0 p195
  • Added --version command line flag

1.0.15

  • Support for Ruby 2.0 added by @dennisreimann
  • You can now upgrade Ruby with --upgrade, also by @dennisreimann.
  • (1.0.14 was skipped due to a local build problem)

1.0.13

  • Ruby 1.9.3 p392

1.0.12

  • When Ruby 1.9.3 is installed from source, install p374. Fixed by @dennisreimann.
  • Fix issue #20, which was breaking --infer if /etc/apt/sources.list.d was empty. Reported by @tarnfeld.

1.0.11

  • Upgrade rubygems immediately after installing the stock Ubuntu 1.9.3 package. If you upgrade later your gem path will change, and all your gems will stop working. It's better to just upgrade right away.

1.0.10

  • Important change: On 12.04 and higher teleport will now install the standard ubuntu ruby1.9.3 package instead of installing from source. We've been testing with the standard ubuntu package internally and it works great.
  • Support for 12.10

1.0.9

  • Use 1.9.3 p286

1.0.8

  • Use 1.9.2 p320 and 1.9.3 p194 (thanks @john)
  • Remove apt rubygems package if necessary (#14)

1.0.7

  • Support for Ubuntu 12.04 (thanks @noeticpenguin)

1.0.6

  • Support for --recipe (thanks to @tarnfeld for the idea)

1.0.5

  • Install Ruby 1.9.3 p125
  • Support for overriding ssh_key, thanks to @arvida!

1.0.4

  • Support for Ubuntu 11.10 (oneiric)

1.0.3

  • #4 Support for :recipes, thanks to @dbloete!

1.0.2

  • #2 Support for FQDN when setting hostname
  • #3 Add support for per-role Gemfiles
  • #5 Util.shell
  • #6 Ruby 1.9.3

1.0.1

Clone this wiki locally