yak-yurt 0.1.dev16

A tool for deploying Django Web Apps to remote servers

==========================================
Yurt: A Deployment Script powered by Ansible and Fabric.
==========================================

Last Updated: March 31st, 2016

Supported on Mac OSX 10.11 (El Capitan)

A CLI tool that uses the magic of Fabric to create and deploy projects with Ansible Roles

Dependencies:
---------------
- Python (2.7)
- VirtualBox (5.0.6)
- Vagrant (1.7.4)
- vagrant-vbguest

First Time Setup
-----------------
1. Use `pip` to install `yurt`::

pip install yak-yurt

2. NodeJS is built into all Yurt-deployed servers thru Ansible. Run the following command::

ansible-galaxy install nodesource.node

OR::

sudo ansible-galaxy install nodesource.node


3. Vagrant sometimes has issues with managing synced folders. Run the following command to install a plugin fix::

vagrant plugin install vagrant-vbguest


Starting a project
------------------

1. Make a new directory in your projects directory and navigate to it::

mkdir ~/projects/new_proj
cd ~/projects/new_proj

#### NEW project Setup

1. Run `yurt add_settings` to generate `fabric_settings.py`::

yurt add_settings

2. Open `fabric_settings.py` in your desired text editor, filling in the blank values::

nano fabric_settings.py

OR::

Open fabric_settings.py on Sublime Text, PyCharm, or whatever else

3. Call `yurt new` to create a new project from scratch::

fab setup.new

#### EXISTING project Setup

1. Call the `setup.existing` Fabric task

```
fab setup.existing
```
2. Enter the SSH link to your repo

## Creating a new remote deployment target

1. Navigate to the project directory

```
cd ~/projects/new_proj
```

2. Enter the following command

```
fab add.remote_server
```

3. Answer the interactive questions

4. Confirm the settings by pressing Enter!

5. You now have a target server that can be deployed to. Let's prep that server!

## Prepping the Server (with PEM credentials)

1. Navigate to the project directory

```
cd ~/projects/new_proj
```

2. Creating the PEM file: Enter the following command

```
fab setup.create_pem_file
```

3. Copying the PEM file to the Remote Server: Enter the following command

```
fab setup.copy_pem_file
```
* Stick with the default 'root' user

4. You're ready to deploy

## Deploying a Yurt Project

1. Navigate to the repo in the project directory

```
cd ~/projects/new_proj/<repo_name>
```

2. Make sure your target branch has been committed and pushed to remote.

3. Enter the following command. There will be a prompt to choose which remote server to push to.

```
fab deploy
```

4. Advanced: The prompts for the above command can be skipped by setting the "env" variable to the remote server
environment name in the Fabric call, like below.

```
fab --set env=development deploy
```
* `development` would be the remote server environment name that could be
found in the project's `orchestration/inventory` directory

## Testing

You should at this point have a development environment for a Django project set up in a Vagrant VM.
To enter this VM, run the command:

```
vagrant ssh
```

The above command should not only bring you into the VM, but it should also activate the Python virtualenv that was
created during the Ansible-run process, as well as navigate you to the Django project directory. If not, type in the following:

```
workon <project-name>
cd /vagrant/<project-name>
```
- where `<project-name>` is the name of the project (usually the git repo name, sans `-`).

You should try to run the Django server as well:

```
cd /vagrant/<project-name>
python manage.py runserver 0.0.0.0:8000
```

## Adding a remote server

Once you have a Django project in your directory locally, you can use the `remote_server` functionality to add a remote
server to your Ansible inventory.

1. Go to project directory (the directory with the Vagrantfile)

```
cd ~/project/new_proj
```

2. Run `fab remote_server`

```
fab remote_server
```

3. Answer all the questions!


## Troubleshooting

- I am getting the following error whenever I use the `fab` command:
```
There was a problem importing our SSH library (see traceback above).
Please make sure all dependencies are installed and importable.
```
- Answer: The latest version of pycrypto does this on systems running
Python 2.7.8 (and lower) and Python 2.7.11. You can downgrade pycrypto to 2.5 by
running the following:

```
pip install pycrypto==2.5
```

- I am getting a Linux Permission Error when running the "EXISTING project Setup"
- Answer: When Yurt was started, Ansible was in version 1.9.4. Since the last update to Yurt, Ansible has since
updated to version 2. One change is that the new `django_manage` module runs Django's "manage.py" file
as an executable. You can add the following task to the beginning of your project's
`orchestration/roles/app/tasks/setup_django_app.yml` file:

```yaml
- name: Make `manage.py` executable
file: path="{{ project_path }}/manage.py" mode="u+x,g+x"
```

Then re-run vagrant's Ansible provisioner:

```
vagrant provision
```

- The existing project I'm trying to load is giving me `File Not Found` type errors.
- Answer: Yurt is a work in progress, so some variables that users could set in the past (specifically `project_name`)
are now generated automagically from other input (specifically `git_repo`). The solution is to edit `project_name` and
`application_name` in the YAML file `orchestration/env_vars/base.yml` directory to be the same name
as the Django project directory (the git repo name with `-` stripped).

Then re-run vagrant's Ansible provisioner:

```
vagrant provision
```