metamon: A Shell repository from KFishner

#メタモン (Metamon)

      /~\_.-~-._,--.._
     |                ~-.._
      |     .     .        \
      |                    /
      |     --._..'       | \
      /                      \
     |                        |
     |                        \
     /                         |
     \_.-._  __...___.._______/
           ~~

Metamon is a Vagrantfile combined with a set of Ansible Playbooks which can be used to quickly start a new Django project.

##Motivation Setting up a development environment when starting a new project always turns out to be a tiresome and time consuming task. Metamon is a collection of Ansible Playbooks that aims to correct this by providing a standarized, automated and generic* environment (both for development and production). This way projects can be started a lot faster by just being able to jump directly into development.

Although Metamon is easily extensible by adding new Ansible roles, it is a better fit for people who use Django + Gunicorn + Nginx + PostgreSQL.

* generic in the context of Django applications.

##Features Metamon will:

Create an Ubuntu 14.04 machine.
Set-up basic Operating system dependencies.
Set-up a Virtualenv and automatically install dependencies.
Set-up Supervisor, PostgreSQL 9.3, Gunicorn and Nginx.
Start a new Django project if it's needed.
Automatically activate a virtualenv and cd to the project's directory when logging in during development.
Use separate requirements files for faster deploys.
Separate settings file for unit testing with coverage and customized settings to make testing faster.

... and more.

##Installation

Download and install Virtualbox.
Download and install Vagrant.
Install Ansible with pip: pip install ansible.
Copy the Metamon files to your project's root directory (or to a new one if you have not started yet) and customize.
Create a new virtual machine by running vagrant up from your project's root directory.
Deploy a new virtual machine by running the deploy_dev.sh script in the deploy directory. If you already have your code in there, no project should be created.

##Configuration and Customization

Configuration

In the deploy/group_vars directory are two values on all.yml that need to be set before the Playbooks can be run. project_name needs to be given the project's name. It will be used for finding the directory containing the Django project (or to create it) and used for pointing to some of the modules (for example urls). secret_key needs to also be set and is used in Django's settings file in SECRET_KEY.

If pull_repo is defined then repo_url must be defined. By default, the master branch will be used.

Vagrant

By default, Vagrant will provide a machine called dev that can be reached at 192.168.50.10. Several ports are forwarded:

80 to 8080 (for Nginx).
8000 to 8000.
9000 to 9000 (for Gunicorn).

The directory where the Vagrantfile is placed is shared with the virtual machine via the /vagrant/ directory. All of this can be changed by editing Vagrantfile.

For more information on what's installed please take a look at the ROLES.md file.

Requirements

The requirements for the Django application will also be installed automatically, however, they are split into three different files. There are also settings that define which requirements are installed during deployment.

requirements.txt should hold the packages needed to run the Django application. It is automatically installed with the application role.
test_requirements.txt should hold packages needed for running unit tests but not required by the application. It is automatically installed with the testing role.
dev_requirements.txt should hold packages needed only when developing (ipdb for example). Installation is marked by install_development_requirements and it is automatically set to Yes when the development role is selected.

Settings and settings for testing

Settings are automatically generated by the /deploy/roles/application/templates/django/settings*.py.j2 files. Two settings files are generated, one for the regular Django settings and one for running the unit tests. You probably want to run tests like so:

python manage.py test --settings=project_name.settings_test

.gitignore

Keep in mind that the .gitignore included in this repository is rather bare. It is recommended that you add rules for ignoring IDE files and generated binary files (for example SQLite databases). It is also a good idea to ignore the <project name>/static/ (collectstatic) directory.

Contributing

So far, Metamon has been an internal tool, and has been maintained in the little free time available to us. Bugs may appear, and there is a lot of room for improvement.