Welcome to Rambo’s documentation!

Join the chat at https://gitter.im/terminal-labs/rambo

Latest: v0.4.4

Quickstart

To get started fast, see Quickstart.

Quickstart

Hardware Recommendations

For running VMs locally in VirtualBox (default), we suggest a minimum of:

  • Reasonably fast cpu with 2 cores and virtualization hardware support (e.g. an Intel i7-3612QM 2.1GHz, 4 core chip with VT-x)
  • 8GB RAM
  • 16GB free drive space

For running containers locally (e.g. LXC) or spawning cloud based VMs (e.g. AWS EC2) you can get away with comparatively slow computer and you don't need VT-x, you don't even need VirtualBox. In fact, these providers can be managed from just a Raspberry Pi.

Supported Host Operating Systems

We expect it's likely you can get Rambo to work on any Unix-like system, but your milleage may vary. So far we have made no effort to get this working with Windows. Contributions are very welcome.

Installation

  1. Install / Use Python 3.2+ and pip (for example with a Virtual Environment).
  2. Download and install VirtualBox 5.1 or newer.
  3. Download and install Vagrant.
  4. Install Rambo with pip,
    • latest release with pypi: pip install rambo-vagrant, or
    • from source: git clone git@github.com:terminal-labs/rambo.git --recursive; cd rambo; pip install -e .
  5. Install plugins with rambo install-plugins

Note: Vagrant and VirtualBox update frequently, and sometimes with breaking changes. Additionally there are may be provider specific dependencies.

Create Project

Now that Rambo is installed, you must initialize a project. This will create a directory that will be tied to your VM. Outside of this directory, Rambo won't be able to find the VM to control it. This also means that if you want to create or control multiple VMs with Rambo, you can, by simply creating more projects and running Rambo commands from the directories where they reside. Create and go to your project:

rambo createproject yourprojectname
cd yourprojectname

In this project directory Rambo gave you a few things to help you get started, a rambo.conf, auth dir, and saltstack dir. These are basic configs to start you out. You don't need to modify them for basic use.

Providers

Rambo supports various providers, and aims to let you switch between them as easily as possible. Nevertheless, some providers do have particular considerations, such as setting up keys and payment for cloud services, or specific dependencies for the host OS. This is a list of Rambo's supported providers, with links to specific documentation pages for each.

Default Provider - VirtualBox:

If you never specify any provider, Rambo will use the VirtualBox as its default choice, and is simply

rambo up

or the identical, more verbose command

rambo up -p virtualbox

Python API

Rambo's CLI and Python API are compatible. In other words, what you can do in the CLI, you can do in the Python API. To accomplish this the CLI is largely dependant on the Python API. You can access the Python API by importing the various functions in app.py, such as with from rambo.app import vagrant_up

Through the Python API you can call vagrant_up and vagrant_destroy to create and destroy VMs. vagrant_ssh is also available and presents an interactive shell to the VM, as if you ran rambo ssh with the CLI.

CLI options are available to be set as either functions in app.py, or as parameters to those functions, depending on whether the CLI option was on rambo or a command (e.g. up). For instance, the following are equivalent:

rambo --vagrant-cwd /sample/path up -p virtualbox

from rambo.app import set_vagrant_vars, vagrant_up
set_vagrant_vars(vagrant-cwd,"/sample/path")
vagrant_up(provider="virtualbox")

CLI

Rambo's CLI is the expected normal way people interact with Rambo. At it's core, Rambo is an interface to Vagrant. Rambo duplicates several commands from Vagrant, that are either commonly used, or Rambo needs to do some preemptive work for before passing the reigns to Vagrant. For most other Vagrant commands, you can call Vagrant through Rambo. Many commands have various options that have defaults that are used when the option is not specified, e.g. rambo up defaults using VirtualBox as the provider.

This is a short list of Rambo's commands, followed by a more detailed explanation of each:

Commands

  • createproject: Create a Rambo project dir with basic setup.
  • destroy: Destroy a VM / container and all its metadata. Default leaves logs.
  • export-vagrant-conf: Get Vagrant configuration.
  • halt: Halt VM.
  • install-plugins: Install Vagrant plugins.
  • scp: Transfer files with scp.
  • ssh: Connect with vagrant ssh
  • up: Start a VM / container with vagrant up.
  • vagrant: Run a Vagrant command through Rambo.
createproject

Create project takes an arguement for the name to give to the project it creates. It will create a directory in the CWD for this project. Upon creation, this project directory will contain a rambo.conf file, an auth directory, and a saltstack directory.

  • rambo.conf is the config file that is required to be present in your project to run rambo up, and is described later in conf.md.
  • auth contains some sample scripts that will aid in setting up keys / tokens for the cloud providers. It is not required. How to use that is described in the cloud provider specific documentation.
  • saltstack is a basic set of SaltStack configuration code that Rambo offers. It can be modified for custom configuration.
destroy

Destroy a VM / container. This will tell vagrant to forcibly destroy a VM, and to also destroy its Rambo metadata (provider and random_tag), and Vagrant metadata (.vagrant dir).

export-vagrant-conf

Places the default Vagrantfile and its resources (vagrant dir, settings.json) in the CWD for customizing.

halt

Tells Vagrant to 'halt' the VM. Useful to free the Host's resources without destroying the VM.

install-plugins

Install passed args as Vagrant plugins. all or no args installs all default Vagrant plugins from host platform specific list.

scp

Transfer files or directories with scp. Accepts two args in one of the following forms:

<local_path> <remote_path>

<local_path> :<remote_path>

:<remote_path> <local_path>

<local_path> [vm_name]:<remote_path>

[vm_name]:<remote_path> <local_path>

For example: rambo scp localfile.txt remotefile.txt

ssh

Connect to the VM / container over SSH. With -c / --command, will executed an SSH command directly.

up

Start a VM or container. Will create one and begin provisioning it if it did not already exist. Accepts many options to set aspects of your VM. Precedence is CLI > Config > Env Var > defaults.

vagrant

Accepts any args and forwards them to Vagrant directly, allowing you to run any Vagrant command. Rambo has first-class duplicates or wrappers for the most common Vagrant commands, but for less common commands or commands that are not customized, they don't need to be duplicated, so we call them directly.

rambo.conf

The rambo.conf file is used to add options to various Rambo commands without having to pass them to the CLI. This is encouraged and has a few benefits. See the following quick example:

[up]
provider = digitalocean
guest_os = centos-7

is equivalent to:

rambo up --provider digitalocean --guest-os centos-7

For a more detailed description, see the separate rambo.conf docs.

Environment Variables

This is advanced and shouldn't be used without good reason.

Like the config file, options can also be specified as environment variables. However, this is much more complex, and we strongly recommend not using these manually, as we think it's much easier to lose track of what's going on and cause undue headache. If you really need to know, look at this specific page for Environment Variables.

rambo.conf

The rambo.conf file is used to add options to various Rambo commands without having to pass them to the CLI. This is encouraged and has a few benefits. See the following quick example:

[up]
provider = digitalocean
guest_os = centos-7

is equivalent to:

rambo up --provider digitalocean --guest-os centos-7

The rambo.conf file is required at the top level in your project directory. It is an INI config file that can specify options. Options passed to the CLI will take precedence over options set via this config file. If you're repeating the same CLI options, setting those options in this config might make your life a little easier. Further, if you intend on tracking your Rambo project in version control, it can be very handy to set some options in this config that match the purpose of your project.

Options can be set in rambo.conf. For example, a useful rambo.conf could look like this:

[up]
provider = digitalocean
guest_os = centos-7

which is equivalent to:

rambo up --provider digitalocean --guest-os centos-7

Setting the config file to this allows you to type simply rambo up to run up with the provider and guest-os options set in the rambo.conf, and not specified in the CLI.

Option Names

The options in the conf file are the same as the full option names in the CLI, with preceeding dashes removed and other dashes replaced with underscores. As examples:

  • vagrant_dotfile_path in the conf, corresponds to --vagrant-dotfile-path in the CLI
  • provider in the conf, corresponds to --provider or -p in the CLI
  • guest_os in the conf, corresponds to --guest-os or -o in the CLI
  • ram_size in the conf, corresponds to --ram-size or -r in the CLI

Option Precedence

When an option is set in both places, the CLI takes precedence. For example, if the provider is set to digitalocean in the config:

[up]
provider = digitalocean

and virtualbox in the CLI

rambo up -p virtualbox

then virtualbox would take precedence and be the provider that is used. If instead, the config still read

[up]
provider = digitalocean

and no provider was specified in the CLI, as in

rambo up

then the provider digitalocean would be used, because the config file takes precedence over the default value virtualbox, but no explicit value is given in the CLI.

The precedence is CLI > Config > defaults.

Customizing Rambo

Rambo aims to make it easy for you to switch providers and customize provisioning. Below is documentation about how to go about cusomizing your provisioning with Salt Stack, switching provisioners, adding providers, and customizing provider-specific code.

Rambo is young, and we'd love to improve Rambo and make this all easier still. Please consider opening a pull request if you add another provisioner or provider, or make any customization that would be a good contribution. :)

Custom Provisioning

Rambo provides a basic default provisioning with Vagrant and SaltStack. To build out what you need for your project you will need your own customized provisioning. You can do this provisioning with any tool you like through Vagrant, such as with shell scripts, SaltStack, or any other provisioning tool.

All Rambo code that is used to provision the VM is kept where Rambo is installed. This directory is copied into the VM at an early stage in the spawn process so that it can be invoked to provision the VM.

SaltStack

Rambo has a few basic Salt States available that are placed in your project dir by rambo createproject. These run unless removed, and work out of the box. The saltstack dir can also be modified however you like for any SaltStack provisioning. You can add your custom Salt States right into the Salt code and they should be automatically picked up and used.

Other Provisioners

If you want to add provisioning with any other tool, you will need to modify the Vagrantfiles to add that provisioning. To export the Vagrantfiles, run rambo export-vagrant-conf inside your project dir. This will drop the Vagrantfile and several of its dependencies. You can likely add custom provisioning straight to the main Vagrantfile without worrying about the other files.

For example, if you'd like to provision with Ansible, you will need to add custom Vagrant code to make this work. There are many useful introductions to various provisioners on Vagrant's website, such as the page on Ansible Provisioning.

Custom Providers / Provider configuration

First grab the Vagrantfiles with rambo export-vagrant-conf.

The main Vagrantfile is extended by other provider-specific vagrantfiles located in vagrant/vagrantfiles such as vagrant/vagrantfiles/virtualbox for VirtualBox. If you need to customize how Rambo works with a provider manually, these are the files you'll need to modify. For instance, you may want to customize many aspects of your VirtualBox VM's networking.

Environment Variables

This is advanced and shouldn't be used without good reason.

Like the config file, options can also be specified as environment variables. However, this is much more complex, and we strongly recommend not using these manually, as we think it's much easier to lose track of what's going on and cause undue headache.

Most env vars are prefixed with RAMBO_ in an attempt to make them easy to visually pick out, and unlikely to conflict with other env vars used by your shell session. After this prefix is the name of each CLI option, in all caps, with dashes replaced by underscores, e.g. RAMBO_GUEST_OS. This form covers most env vars, the exception being env vars that Rambo needs to set that are used by Vagrant directly. In this case we cannot change the name of the env var, and must use Vagrant's. For example, Rambo uses (and you can set) VAGRANT_DOTFILE_PATH and VAGRANT_CWD. All of these CLI-related env vars can be set in the shell session, and will be picked up and used by Rambo if those same options are not otherwise set. Both the rambo.conf file and options set within the CLI take precedence over env vars. The precedence is thus CLI > Config > Env Var > defaults.

AWS EC2

Create Account

After you installed the dependencies on your host computer you now need to create an account at AWS. This repo will create real resources on AWS so you need to provide AWS with valid payment and remember you might rack up a bill if you run a whole bunch of machines. You have been warned.

Create SSH Keys

Next you need to create a SSH key pair for AWS.

Run:

mkdir -p auth/keys
cd auth/keys
ssh-keygen -t rsa -N '' -f "aws.pem"

*If you want multiple users or computers to access the same AWS profile or team, you must have unique key names. For example, you will need to change the base name of your .pem and .pem.pub files to something else like aws-myname.

Create a new key and name the key the same as the base name of your SSH key. If AWS's key name and the one one your host don't match, you won't communicate to your VM.

Now go to AWS's "EC2 Dashboard", on the left hand side go to "Key Pairs" and click the "Import Key Pair" button.

Here are instructions on how to setup SSH keys with aws:

http://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ec2-key-pairs.html

You will need to copy the contents of aws.pem.pub.

NOTE: You need the aws.pem file and the aws.pem.pub file. The aws.pem file needs permissions set to 600 and The aws.pem.pub file needs permissions set to 644

Be careful not to commit this file to the repo. We setup this repo to ignore all files ending in .pem. But, you could theoretically still commit the pem file (by forcing a commit for example). Store this pem file in a safe place with restricted access. Anyone who has this file can log into your machines on AWS and run arbitrary commands on them.

Create Security Group

Now go to AWS's "EC2 Dashboard", on the left hand side go to "Security Group" and click the "Create Security Group" button.

Name the new security group salted_server.

Add these inbound rules to the security group

"All ICMP - IPv4", ICMP, 0 - 65535, anywhere

"SSH", TCP, 22, anywhere

"HTTP", TCP, 80, anywhere

"HTTPS", TCP, 443, anywhere

"Custom TCP Rule", TCP, 4505, anywhere

"Custom TCP Rule", TCP, 4506, anywhere

"Custom TCP Rule", TCP, 5000, anywhere

"Custom TCP Rule", TCP, 8080, anywhere

"Custom TCP Rule", TCP, 8888, anywhere

Create API Token

Next you need to manually create an API access token on AWS.

Go to the "IAM Dashboard", then go to "users", now click on the user who will be creating the AWS EC2 instances. Click on the "Security Credectials" tab, click the "create access key" button.

You MUST get both the Access key ID and the Secret access key.

NOTE: AWS will only show you this key ONCE.

Edit Script to Load Environment Variables

Here is the contents of the aws.env.sh file. Edit it by replacing the placeholder tags with your keys and tokens.

#!/bin/bash

# for aws
export AWS_ACCESS_KEY_ID=<YOUR AWS KEY ID>
export AWS_SECRET_ACCESS_KEY=<YOUR AWS ACCESS KEY>
export AWS_KEYPAIR_NAME="Vagrant"
export AWS_SSH_PRIVKEY="auth/keys/aws.pem"

Put your aws access key token in the line: export AWS_ACCESS_KEY_ID=<YOUR AWS KEY ID>

Put your aws secret acces key token in the line: export AWS_SECRET_ACCESS_KEY=<YOUR AWS ACCESS KEY>

Put the name of your aws ssh private key in the line: export AWS_KEYPAIR_NAME="aws"

Put the path to your aws ssh private key in the line: export AWS_SSH_PRIVKEY="auth/keys/aws.pem"

After editing, your aws.env.sh file will look similar to this:

#!/bin/bash

# for aws
export AWS_ACCESS_KEY_ID="AKIAITT673DAF4YNV7MA"
export AWS_SECRET_ACCESS_KEY="m25AyjXtiYB2cCWMv1vQeyZtWqiWg0nqxi2Wm2QX"
export AWS_KEYPAIR_NAME="aws"
export AWS_SSH_PRIVKEY="auth/keys/aws.pem"

Note: the public key must be in the same dir as the private key and the public key must share the same base name as the private key (just append ".pub" on the public key file's name).

Now you need to source the aws.env.sh file. cd into the repo and run:

source aws.env.sh

Launching Your AWS EC2 Instance

Finally, run:

rambo up -p ec2
rambo ssh

DigitalOcean

Create Account

After you installed the dependencies on your host computer you now need to create an account at DigitalOcean.

This repo will create real resources on DigitalOcean so you need to provide DigitalOcean with valid payment and remember you might rack up a bill if you run a whole bunch of machines. You have been warned.

Create SSH Keys

Next you need to create a SSH key pair for DigitalOcean.

Run*:

mkdir -p auth/keys
cd auth/keys
ssh-keygen -t rsa -N '' -f "digitalocean.pem"

*If you want multiple users or computers to access the same DigitalOcean profile or team, you must have unique key names. For example, you will need to change the base name of your .pem and .pem.pub files to something else like digitalocean-myname.

Now go to https://cloud.digitalocean.com/settings/security

Create a new key and name the key the same as the base name of your SSH key. If DigitalOcean's key name and the one one your host don't match, you won't communicate to your VM.

Copy the contents of digitalocean.pem.pub into the new key field.

Here are instructions on how to setup SSH keys with DigitalOcean:

https://www.digitalocean.com/community/tutorials/how-to-use-ssh-keys-with-digitalocean-droplets

You will need to copy the contents of digitalocean.pem.pub.

NOTE: You need the digitalocean.pem file and the digitalocean.pem.pub file. The digitalocean.pem file needs permissions set to 600 and The digitalocean.pem.pub file needs permissions set to 644

Be careful not to commit this file to the repo. We setup this repo to ignore all files ending in .pem. But, you could theoretically still commit the pem file (by forcing a commit for example). Store this pem file in a safe place with restricted access. Anyone who has this file can log into your machines on DigitalOcean and run arbitrary commands on them.

Create API Token

Next you need to manually create an API access token on digitalocean.com

Go to:

https://cloud.digitalocean.com/settings/api/

NOTE: DigitalOcean will only show you this key ONCE.

Store this token in a safe place with restricted access. Anyone who has this token can create, edit, or destroy resources on digital ocean, they could rack up a huge bill for you or shut down all your vms.

Edit Script to Load Environment Variables

Here is the contents of the digitalocean.env.sh file. Edit it by replacing the placeholder tags with your key and token.

#!/bin/bash

# for digitalocean
export DIGITALOCEAN_TOKEN=<YOUR DIGITALOCEAN API TOKEN>
export DIGITALOCEAN_PRIVATE_KEY_PATH="auth/keys/digitalocean.pem"

Put your DigitalOcean API token in the line: export DIGITALOCEAN_TOKEN=<YOUR DIGITALOCEAN API TOKEN>

Put the path to your DigitalOcean ssh private key in the line: export DIGITALOCEAN_PRIVATE_KEY_PATH=<PATH TO YOUR PRIVATE KEY>

After editing, your digitalocean.env.sh file will look similar to this:

#!/bin/bash

# for digitalocean
export DIGITALOCEAN_TOKEN="0bf1d884e737417e2ea6f7a29c6035752bf8c31b366489c5366745dad62a8132"
export DIGITALOCEAN_PRIVATE_KEY_PATH="auth/keys/digitalocean.pem"

Note: the public key must be in the same dir as the private key and the public key must share the same base name as the private key (just append ".pub" on the public key file's name)

Now you need to source the digitalocean.env.sh file. cd into the repo and run:

source digitalocean.env.sh

Launching Your DigitalOcean Instance

Finally, run:

rambo up -p digitalocean
rambo ssh

Docker

At this time Docker is supported by using an intermediate host. The intermediate host is created with VirtualBox, and is the same OS as is used for the Docker container inside it. Setting both of those OSes to be the same avoids certain complexities and potential problems that would otherwise present.

Basic usage of Docker:

rambo up -p docker
rambo ssh

LXC

NOTE: At this time, this will only work on Ubuntu 16.04+ host OS

At this time LXC is supported natively on Ubuntu 16.04. For this native support, you need a few additional dependencies. They can all be installed with this:

sudo apt install -y build-essential linux-headers-$(uname -r) lxc lxc-templates cgroup-lite redir

After that, starting an LXC container with basic usage is:

rambo up -p lxc
rambo ssh

Note: At this time using LXC as a provider will require root priveleges / sudo.

Changelog

0.4.4 (March 9, 2018)

BUGFIX:

  • Now custom fork of click_configfile is added as a submodule so it's always present, and included this in the MANIFEST.

0.4.0 (March 9, 2018)

FEATURES:

  • Added Ubuntu Dockerfile.
  • Added machine-type option for various cloud providers.
  • Added ramsize and drivesize options.
  • Added ability to load options via rambo.conf.
  • Added createproject cmd to create project dir, including default saltstack code, auth dir, and mandatory rambo.conf.
  • Added install-plugins cmd for installing vagrant plugins.
  • Refactored shell invocation of Vagrant to ouput near real-time stdout and stderr, keeps ANSI formatting, stderr and exit status passthrough.
  • Better logging of shell invocation of Vagrant.
  • Added the ability to custom saltstack code dir that is automatically used.
  • Added the ability to custom Vagrantfile that is automatically used.
  • Added export-vagrant-conf cmd for dropping vagrant files for customization.
  • Added option for guest os.

IMPROVEMENTS:

  • Rounded out OS whitelist: Debian 8/9, CentOS 7, Ubuntu 14.04/16.04
  • Fix Docker bugs
  • Added readthedocs.
  • Defining a project by the existence of a conf file.
  • Remove support for using env vars and api simultaneously.
  • If no saltstack dir is in a the project dir, no salt is run.
  • Saltstack files moved to terminal-labs/sample-states repo. The 'basic' branch is pulled and used.
  • Added in vagrantfile setting kind of syncing.
  • Added toggle in vagrantfile for grabbing canonical apt sources or not since some images come with different, unreliable sources.
  • Renamed vagrant_resources to vagrant, and salt_resources to saltstack.
  • Changed default guest os from Debian 8 to Ubuntu 16.04.

0.3.3 (November 28, 2017)

FEATURES:

  • Added ubuntu 14.04 to hosts list.

IMPROVEMENTS:

  • Add version cli option.

0.3.2 (November 27, 2017)

FEATURES:

  • Added additional Salt states for Hadoop edgenode and worker.
  • Allowing setting custom tmpdir path.

IMPROVEMENTS:

  • Using standard get/set_env_var_rb functions.
  • Change VM_SIZE to RAMBO_RAM and created RAMBO_DRIVESIZE.
  • Changed VM_Host to RAMBO_GUEST_OS.
  • Cleaned up some Vagrant code.

BUG FIXES:

  • Stop setting a default apt source on CentOS.
  • Stop setting hostname on CentOS. Another ticket was made for that.
  • Passing ctx to ssh and destroy commands.
  • Changed name of base box according to the box name change on app.vagrantup.com for the default Debian box.

0.3.1 (November 8, 2017)

FEATURES:

  • Now AWS makes use of VM_Size flag to produce t2.nano, t2.micro, and t2.small VMs.

IMPROVEMENTS:

  • Updated docs for CLI, Python API, Environment Variables
  • Renamed tmp dir to rambo-tmp.

BUG FIXES:

  • rambo destroy now finds and deletes metadata in tmp dir.
  • Fix Docker failing on editing non-existant bashrc. Now ensuring existence first.
  • Fixing vagrant up exit trigger when VM not named 'default'.
  • Fixed bug preventing provisioning without Salt.

0.3.0 (October 26, 2017)

FEATURES:

  • Added Salt states to apply Anaconda licenses.
  • Adding a Python API.
  • Added Nano to base Salt provisioning.
  • Able to set Vagrant environment variables via the CLI
  • Refactored packaging for PyPI.
  • Added in support for Ubuntu 14.04 and Centos 7 guest OSs.
  • Added in 4GB and 8GB RAM for all supported OSs.
  • Added Salt states for setting up licensed Anaconda.
  • Made Rambo a pip installable package.
  • Created a Python based CLI for Rambo.
  • Added support for multiple users on DigitalOcean.
  • Added a Salt state for Hadoop Ambari.
  • Added basic network modifications for clustering.
  • Setting the hostname to the VM_NAME.

IMPROVEMENTS:

  • Now downloading base vagrant boxes from vagrantup.com.
  • Now enforcing Vagrant >=1.9.7.
  • VM_NAME now contains host's hostname, and rambo's working dir, and a unique hex id.
  • Now deletes broken symlinks found that would otherwise break Rambo during the rsync process.

BUG FIXES:

  • Fix ability to set repository branch and then execute highstate.

0.2.1 (August 9, 2017)

FEATURES:

  • Now activating conda environment upon vagrant ssh.
  • Added Salt State for Anaconda.
  • Added Salt State for loading a database dump from a local store, and allowing using this or the artifacts state.

IMPROVEMENTS:

  • Added default fingerprints for BitBucket and GitHub.
  • Renamed miniconda state to conda.
  • Added documentation for Docker provider.

BUG FIXES:

  • Fixed misnamed reference to Miniconda state.
  • Now requiring artifacts grains before trying to load a database.
  • Deduping state IDs for adding fingerprints for git and hg.
  • Specifying fingerprint hash type since that's now required by a Salt update.
  • Deduping state IDs for installing pip requirements with conda and venv.
  • Removing unused salt state directory.
  • Bumped required vagrant version.

0.2.0 (August 3, 2017)

FEATURES:

  • Added a Salt State for Miniconda.
  • Added Docker as a provider.

IMPROVEMENTS:

  • Using Packer made base boxes for VirtualBox.
  • Now using paravirtualization with VirtualBox for increased speed.
  • Enhanced documentation and helper markdown files.
  • Renamed 'AWS' provider to 'EC2' to avoid future confusion.
  • Updated documentation.
  • Some code cleaning.

BUG FIXES:

  • Changed the standard AWS EC2 size to t2.micron.

0.1.0 (May 22, 2017)

FEATURES:

  • Initial commit.

The changelog began with open sourcing Rambo at version 0.1.0.

What’s Rambo For?

This project is for provisioning and configuring virtual machines (and containers) in a simple, predictable, and highly reproducible way. Just run one command and your VM is up, code is deployed, and your app is running, on any supported platform.

At this time this repo allows you to create a Linux VM on multiple providers (AWS EC2, DigitalOcean, VirtualBox, LXC). Several Operating Systems are available on select providers. The base machine configuration is a Ubuntu 16.04 64bit OS with 1024MB RAM, and 30GB drive.

One of the goals of this project is be able to run a simple command and have a new VM be created on your provider of choice. Once the VM is initialized SaltStack is used to deploy code to and provision your machine. The SaltStack machine configuration code (states) will run the same regardless of which provider is actually running the machine. You can easily cycle your VMs by destroying and rebuilding them.

Another goal of this repo is to have the spawned VMs be maximally similar across providers. Usually, your configuration will not need to change at all and will simply run on all providers.

By default Rambo offers a basic VM configuration with SaltStack, but you can customize this. See Customizing Rambo for that.

Basic Usage

Once installed, you can run one of these commands to get your VM:

for VirtualBox run

$ rambo up
$ rambo ssh

for AWS EC2 run

$ rambo up -p ec2
$ rambo ssh

for DigitalOcean run

$ rambo up -p digitalocean
$ rambo ssh

for Docker run

$ rambo up -p docker
$ rambo ssh

for LXC run

$ rambo up -p lxc
$ rambo ssh

Contributing

We heartily welcome any contirubtions to this project, whether in the form of commenting on or posting an issue, or development. If you would like to submit a pull request, you might first want to look at our development guidelines for this project.

Special Thanks

Thanks go out to the Vagrant community and HashiCorp. Vagrant is a great tool it has helped us a lot over the years.

Rambo is supported by Terminal Labs.