README - Installation Instructions

Step One - Install Ansible

You can follow the instructions on the [Ansible website] http://docs.ansible.com/intro_installation.html#installing-the-control-machine or either of the options below:

(if you have OSX)

first install homebrew if you dont have it installed

ruby -e "$(curl -fsSL https-//raw.github.com/Homebrew/homebrew/go/install)"

then run

brew update
brew install python
brew install ansible
pip install paramiko PyYAML Jinja2 httplib2

OR (if you use ubuntu/debian)

sudo apt-get install python-yaml python-markupsafe nfs-kernel-server nfs-common portmap
sudo apt-get install software-properties-common

Test to see if ansible is installed using ansible --version If it is not installed, do the following:

sudo apt-add-repository ppa:ansible/ansible
sudo apt-get update
sudo apt-get install ansible

OR (if you have centos/redhat)

yum install ansible

Step Two - Virtualbox

Download VirtualBox and install.

Step Three - Vagrant

Download Vagrant and install.

Step Four - Repo

Go to directory you want clone into. For example, if you want to clone into /someuser/myapps/

You could do: cd /someuser/myapps/

Then type below:

git clone https://github.com/webapp-builders/ahoy.git

or this if using ssh:

git clone git@github.com:webapp-builders/ahoy.git

Step Five

cd ahoy

You can confirm that you are in the correct directory by typing ls.
If you see a file Vagrantfile you are in the correct directory.

Note: If you are using ubuntu as your primary OS, uncomment line 22 to use the VirtualBox GUI.

Note: If your computer only supports 32-bit operating systems, after cd groundwork, open the file: Vagrantfile
Comment out line 3 and uncomment line 5 to use "ubuntu/trusty64"
(this will tell VirtualBox to run the "precise32" operating system).

Step Six

vagrant up

READ Below for possible "terminal messages":
Numerous messages and errors may occur once typing vagrant up.
Read the following Terminal Message 1 and Terminal Message 2, to make sure you are on the right track.

Terminal Message 1: If your terminal seems to be "stuck" at TASK: rvm... just wait. This might take a while, because you are installing Ruby using RVM. This is a good sign. It means everything is installing properly.

Terminal Message 2: You many receive an error if you already have Rail or Postgresql running on your machine.
This means you need to stop Rails and/or Postgresql.

An error might look like the following:

Vagrant cannot forward the specified ports on this VM, since they
would collide with some other application that is already listening
on these ports. The forwarded port to 5432 is already in use
on the host machine.

To fix this, modify your current projects Vagrantfile to use another
port. Example, where '1234' would be replaced by a unique host port:

  config.vm.network :forwarded_port, guest: 5432, host: 1234

Sometimes, Vagrant will attempt to auto-correct this for you. In this
case, Vagrant was unable to. This is usually because the guest machine
is in a state which doesn't allow modifying port forwarding.

For Rails server, find the terminal window that is running Rails locally and press ctrl+c together.

You may not realize it, but Postgres might have started automatically at startup. If Postgresql is running, to stop your:

For Ubuntu:

sudo service postgresql stop

For OSX homebrew:
Go online, search for "how to stop postgresql osx"
(There will be different instructions depending on how your Mac is setup).

Step Seven (ON first host OS Terminal Tab)

vagrant ssh

Your terminal prompt should change from your normal one. Now this tab becomes your Guest OS Terminal Tab

For example:
(These are not exact, the will vary from computer to computer)
Your terminal prompt before: OSX@jennifer~/myworkfiles $
Your terminal prompt after: vagrant@vagrant-ubuntu-trusty-64:~$

Once you have typed vagrant ssh and your terminal prompt has successfully changed to a new one such as vagrant@vagrant-ubuntu-trusty-64:~$ this means you are now using the terminal of another operating system!

The whole reason you are using Vagrant is to have another operating system (within your computer) to have a completely isolated environment for development.

Step Eight(ON guest OS Terminal Tab)

manually add the following lines to .profile file: Note: this is a one time temprorary fix to deal with the issue of ansible task failing to update the file.

export WORKON_HOME=/vagrant/.venvs source $(which virtualenvwrapper.sh) alias pgstart='/etc/init.d/postgresql restart' alias pipfreeze='pip freeze > requirements.txt' alias pipinstall='pip install -r requirements.txt' alias wo='workon' alias da='deactivate' alias run='python manage.py runserver' alias gun='gunicorn -b 127.0.0.1:4000 manage:app' alias browse='open -a /Applications/Google\ Chrome.app/Contents/MacOS/Google\ Chrome http://localhost:5000'

after adding the lines, source .profile the file by typing:

. .profile

alternatively type 'exit' to end the ssh session and type 'vagrant ssh' again to connect to the vagrant box again.

next make sure the database is started by typing: (TODO: should add this to init.d)

sudo /etc/init.d/postgresql restart

next type:

workon web

or its alias:

wo web

This will activate the virtual environment and cd into the project directory. You will now be in the web project directory with the virtual environment named "web" activated as indicated by the (web) text before the prompt. Also all packages defined in requirements.txt file in the project directory are automatically re-installed every time you type workon web Also all environment variables exported in the .env file in the project directory are sourced every time you type workon web

Go to STEP NINE.

Step Nine(ON guest OS Terminal Tab)

create the database schema by typing the following: Note: when database migrations are added this step will be replaced. Note: that the virtual environment must be activated before this step Note: the database was already created via ansible. This step just creates tables. Note: this is a one time operation unless you need to update the database by droping and re-creating the tables.

(web)$ python manage.py initdb.py

you can clear (but not delete) the db by typing:

(web)$ python manage.py dropdb.py

to see a list of available commands type:

(web)$ python manage.py

Go to STEP TEN.

Step Ten(ON Guest OS Terminal Tab)

Start the flask develoment server by typing:

python manage.py runserver

or alternatively use the alias:

run

Go to your browser and open http://localhost:5000

You can stop the server by typing ctrl-c

Step Eleven(ON Guest OS Terminal Tab)

At anytime you can deactivate the virtual environment simply by typing:

deactivate

or its alias:

da

and you can reactivate it again by again typing:

workon web

or its alias:

wo web

you can also see a list of all virtual environment

using:

workon

or:

wo

Step Twelve

Open a second Host OS Terminal Tab cd into project directory

You can run git commands for the project here. Note: git is not installed on the guest OS so all git management should be done on the Host os. Treat the Guest OS like a production environment and the project files on the guest os as readonly.

Step Fourteen

Open a third Host OS Terminal Tab cd into project directory

You can type the command that launches your text editor here

Vagrant Notes:

the initilal vagrant up command also runs the vagrant provision automiatically subsequent vagrant up (or vagrant reload) commands will only run the changes in the vagrantfile but will not run the ansible configuration specified in the vagrant file unless the vagrant destroy command is run before it. In order to run the changes in the ansible configuration run the following command (ON first host OS Terminal Tab)

vagrant provision

Note vagrant prvision will only run the changes to the ansible configuration but will not run changes in the vagrant file. for executing the changes in the vagrant file type vagrant up or vagrant reload (ON first host OS Terminal Tab)