Getting Started

This guide will step you through installing AerisCloud on your computer, then starting a new project.

Dependencies

  • A UNIX-based operating systems, OSX and Linux are both supported
  • Python 2.7
  • python-virtualenv
  • Virtualbox
  • Vagrant 1.7+
  • git
  • rsync

When using Linux, also make sure to have the a working NFS server installed.

Manual Installation

If you already have all the dependencies installed, the first step is to clone the AerisCloud repository where you want it to be installed (something like /opt/aeriscloud is a good idea):

git clone https://github.com/aeriscloud/aeriscloud.git
cd aeriscloud

Then run make install to install all the necessary python dependencies in the current folder and generate the auto-completion.

When updating, just enter the AerisCloud folder, then just pull the latest version before running make install.

Install cloud without aeris

If you want to install only cloud to manage remote servers and you don’t have to manage local developement environment with aeris, you can install only cloud with make install-cloud.

Finally add the following line in you ~/.bash_profile:

source /path/to/aeriscloud/scripts/env.sh

Setting up AerisCloud

Once AerisCloud is installed, the first step is to create a new organization. Organizations are AerisCloud’s way to store your custom playbooks, roles and anything that might be private to your company, to do so run:

cloud organization init my-org

If it is your first time launching an AerisCloud command, you should be greeted by a short assistant to set the global configuration of the tool. Just answer each step as they are presented to you and if you do not know the answer/right configuration at that time, feel free to skip that step as you can always make changes later.

You terminal will then be moved to the folder containing my-org, where the structure of files should look like:

├── README.md
├── env_dev.yml
├── env_production.yml
└── roles
    ├── aeriscloud.disk
    ├── aeriscloud.dotdeb
    ├── aeriscloud.elasticsearch
    ├── ... more roles
    └── dependencies.txt

The default generated organization should have several general purpose ansible roles already installed to allow you to start hacking as soon as possible, but if anything is missing then dependencies.txt and env_production.yml are the two files to take a look at, more on that in Organization.

You are now ready to start using AerisCloud. For more details on the available configuration options provided by the tool, just jump to Configuration.

Starting a New Project

Now that everything is up and ready, it is time to start a new project, type:

aeris init my-project --up

A short assistant will ask for your project name, services you wish to enable and vagrant basebox, the default chef/centos-7.0 basebox should be a safe starting box but feel free to use your favorite box from Atlas. Just keep in mind that AerisCloud roles are mainly designed around CentOS and might not work on other distributions.

The box should start booting up right after that and the provisioning should start. It will take some time for the provisioning to finish the first time so you can go a grab a coffee, read your mails, build that treehouse you promised your kids last summer, etc...

If you want to set some custom variables or edit the virtual machine in any way before starting it up, remove the --up flag and take a look at the .aeriscloud.yml file. Once done you can just manually run:

aeris up

Once the provisioning is done, you’ll have a fully running virtual machine with the services you selected already installed and running, you can ssh in the machine with aeris ssh, you can suspend it by running aeris suspend, halt it by running aeris halt and finally destroy all traces of it by running aeris destroy.

Your code is mounted to /home/vagrant/my-project, one can use their favorite language, provided that the proper roles have been installed. The recommended way to manage dependencies, builds, etc... is through makefiles, the format is relatively simple though maybe limited. The recommended way to run your make commands is either via aeris ssh or the aeris make shortcut.

Here is a sample Makefile for a tentative node.js app:

.PHONY: all deps build run

all: build

node_modules:
      npm install

deps: node_modules

build: deps
      gulp assets

run:
      node .

What’s Next?

At this point you can already work on your application and test it in a contained environment, but the whole point of AerisCloud is to be able to run the same provisioning scripts on both your local box and your online servers. To learn how to do so, proceed to Cloud Command for more details on how ansible is used and how to write proper roles for your organization.