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 teleport config file you can generally run it over and over again without fear of breaking the target machine.

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.

Getting Started

  1. Install Teleport on your local machine.

    $ sudo gem install teleport
    
  2. Create a Telfile config file. 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 new server. 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.

Full Documentation

Full docs are in the wiki:

https://github.com/gurgeous/teleport/wiki