gurgeous / teleport

Teleport - opinionated server setup with Ruby.

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

teleport's Issues

Ability to only run a particular recipe for a server, rather than running everything?

I seem to be writing my teleport configuration to manage my whole server stack, which I guess is a good thing as it means my servers can be setup and managed without logging in (and easily migratable). One thing that would be really handy is if I could specifically ask teleport to run a recipe on the remote machine.

I understand the idea of teleport is to be non-destructive and cause no damage if run over and over again, which i'm keeping my recipes to (its great!). However, when I want to run a recipe (maybe it changed, or to update something) it's a pain that I have to wait for apt to update, and all of my other recipes to run.

Maybe its a lot of work to get this running, and not worth it, but I just figured it would be a cool thing to be able to do.

Add support for Ruby 1.9.3

Add support for per-role Gemfiles

This also requires changing how system-wide gems are uninstalled. Perhaps we should only do that at rvm install time.

Util.shell

Basically split("\n").each { run }, so things are easier with heredoc.

Explicit recipes

Several folks have asked for this. See pull request from @dbloete as a starting point. I definitely want to allow running recipes within the context of Teleport, with full support for Util.

ERROR: gem update --system is disabled on Debian

[20:13:08] Gems...
[20:13:08] Upgrading rubygems...
gem update --system
ERROR: gem update --system is disabled on Debian, because it will overwrite the content of the rubygems Debian package, and might break your Debian system in subtle ways. The Debian-supported way to update rubygems is through apt-get, using Debian official repositories.
If you really know what you are doing, you can still update rubygems by setting the REALLY_GEM_UPDATE_SYSTEM environment variable, but please remember that this is completely unsupported by Debian.
./gem/teleport/util.rb:56:in `run': gem update --system failed : 1 (Teleport::Util::RunError)

I'm planning on installing ruby and rubygems from source anyway. I wonder how to disable this...

teleport --infer fails without sources.list.d/

The full error can be found here. Here are the relevant parts:

$ teleport --infer

[20:20:50] Calculating apt sources and keys...

cat: /etc/apt/sources.list.d/*.list: No such file or directory

...lib/teleport/util.rb:72:in `run_capture': cat /etc/apt/sources.list /etc/apt/sources.list.d/*.list  failed ...

Workaround: I did touch /etc/apt/sources.list.d/temp.list and it worked.

Access to the server object instance in callback methods

It would be really handy if I could access the instance of Teleport::Config::Server so I could do something like this...

before_recipes do
    # If we don't have the cron option on the server, just set it to an empty array
    if [email protected]?(:cron)
        @server.options[:cron] = []
    end
end

after_recipes do
    # Do something with @server.options[:cron] - perhaps install them into crontab
end

I'd like to have my recipes create cron entries, e.g.: mysql database backups but currently I can't see a nice integrated way to get shared data between the original server definition, all the recipes and then out at the end.

Hopefully that makes sense :)

Support for FQDN

If hostname is a FQDN, both flavors should make it into /etc/hosts. See pull request from noeticpenguin as a starting point.

Apt update runs every time

I was under the impression that the sudo apt-get update command was only run when there were changes to sources, am I wrong here? It seems every time I run teleport for a server it runs it.

Error when running Ruby 2.0.0 on the server

Been getting this error during a setup:

[00:30:36] Creating deploy account...                                              

useradd --create-home --shell /bin/bash --groups adm deploy
mkdir -p /home/deploy/.ssh
setting up sudoers...
adding id_teleport.pub to authorized_keys...
/usr/local/lib/ruby/2.0.0/fileutils.rb:970:in `chmod': undefined method `mode_to_s' for File
Utils:Module (NoMethodError)
        from /tmp/_teleported/gem/teleport/util.rb:214:in `chmod'
        from /tmp/_teleported/gem/teleport/util.rb:123:in `mkdir'
        from /tmp/_teleported/gem/teleport/util.rb:130:in `mkdir_if_necessary'
        from /tmp/_teleported/gem/teleport/install.rb:189:in `_create_user'
        from /tmp/_teleported/gem/teleport/install.rb:40:in `block (2 levels) in initialize'
        from /tmp/_teleported/gem/teleport/install.rb:261:in `_with_callback'
        from /tmp/_teleported/gem/teleport/install.rb:39:in `block in initialize'
        from /tmp/_teleported/gem/teleport/install.rb:261:in `_with_callback'
        from /tmp/_teleported/gem/teleport/install.rb:36:in `initialize'
        from /tmp/_teleported/gem/teleport/main.rb:164:in `new'
        from /tmp/_teleported/gem/teleport/main.rb:164:in `install'
        from /tmp/_teleported/gem/teleport/main.rb:20:in `initialize'
        from -e:1:in `new'
        from -e:1:in `<main>'
[01:30:36] Failed!                                                                 

This is using v1.0.17, set up to use Ruby 2.0.0-p195. Any ideas as to what's causing it? I tried looking through the source but I couldn't see any issues.

Handy way to organize servers

I've only recently got into working with Teleport (just two days of use) but one thing I have noticed, after building a series of generic re-usable recipes is, I have a lot of config for my server options e.g.

server "db",

:role => :db,
:services => ["mysql"],
:recipes => ["slave.rb"],
:mysql => {
    :server_id => 00, # Last two octets of the IP address
    :master => {
        :host => "host-of-master",
        :port => 3306,
        :user => "replication-user",
        :password => "blabla"
    },
    :slave => {
        :skip => [000,111,222] # Skip replication errors with these codes
    },
    :readonly => true
},
:"sd-agent" => {
    :key => "XXX"
}

I wanted to do something where I could include files in, say, servers/db.server.rb rather than having three or four of those large declarations in my Telfile.

Hopefully that makes sense, and will bring a handy feature into Teleport :D Thanks!

@server is empty inside a .erb file

I have a dynamic config file in /files/test.conf.erb with a statement similar to the one below, and for some reason @server is now empty, whereas (I believe before 1.0.5) this used to be the current server configuration. I now get errors when running teleport as ERB says options is not a method on nil.

<%= @server.options[:something] %>

problem with 11.10

trying out teleport with new Ubuntu 11.10 server.

README states 11.10 is supported, comment in output "warning - Ubuntu 11.10 hasn't been tested with Teleport yet "

when trying to run teleport with a Telfile of only

ruby "1.9.3"

gives an error

Reading state information...
Package libreadline5-dev is not available, but is referred to by another package.
This may mean that the package is missing, has been obsoleted, or
is only available from another source
However the following packages replace it:
  libreadline-gplv2-dev lib64readline-gplv2-dev

E: Package 'libreadline5-dev' has no installation candidate
[14:07:56] Failed!                                        

Teleport for multiple servers at once

It would be cool if the command line binary supported this sort of command - teleport app-server db-server and it first updated the app-server then went on to update the db-server?

Rubygems

Hey,

Any idea when this update will be pushed out to ruby gems?

Tom.