Metadata-Version: 1.1
Name: anouman
Version: 0.0.2
Summary: Rapidly deploy your django project behind gunicornand nginx
Home-page: UNKNOWN
Author: John Furr
Author-email: UNKNOWN
License: BSD
Download-URL: https://github.com/gnulnx/anouman/tree/0.0.2
Description: Anouman Overview
        ================
        
        Anouman is a django site deployment tool that is designed to greatly
        simplify the process of deploying
        `Django <https://www.djangoproject.com/>`__ projects behind
        `gunicorn <http://gunicorn.org/>`__/`nginx <http://nginx.com/>`__. In
        the spirit of reusing great open source software Anouman makes use of
        `virtualenv <https://pypi.python.org/pypi/virtualenv>`__/`virtualenvwrapper <http://virtualenvwrapper.readthedocs.org/en/latest/>`__
        to help manage the process of deploying your django instances.
        
        The easiest way to become familiar with Anouman is to dive in and use it
        by following along with the tutorial below. However, before you begin
        you will first need to install `vagrant <http://www.vagrantup.com/>`__
        and `virtualbox <https://www.virtualbox.org/>`__. We will be using these
        tools to build a fresh Ubuntu VM to test your django deployment on.
        
        **Disclaimer:** *Anouman is still very much alpha stage software. As
        such it has only been tested on Ubuntu 12.04 using the BASH shell. I'd
        love to hear from others if they get this working in other OS/SHELL
        combinations.*
        
        Virtual Machine Creation and Provisioning
        -----------------------------------------
        
        **Step 1:** VM creation. Hopefully by now you have vagrant and virtual
        box both installed. Next you should create a directory called 'site1'
        and place the following vagrant settings into a file named
        *'Vagrantfile'*
        
        ::
        
            # -*- mode: ruby -*-
            # vi: set ft=ruby :
        
            # Vagrantfile API/syntax version. Don't touch unless you know what you're doing!
            VAGRANTFILE_API_VERSION = "2"
        
            Vagrant.configure(VAGRANTFILE_API_VERSION) do |config| 
              # Every Vagrant virtual environment requires a box to build off of. 
              config.vm.box = "site1" 
        
              # The url from where the 'config.vm.box' box will be fetched if it 
              # doesn't already exist on the user's system. 
              config.vm.box_url = "http://files.vagrantup.com/precise64.box" 
        
              # Run bootstrap.sh provisioning script 
              config.vm.provision :shell, :path => "bootstrap.sh" 
        
              # Create a private network, which allows host-only access to the machine 
              # using a specific IP. 
              # config.vm.network :private_network, ip: "192.168.33.10"  
        
              # Create a public network, which will make the machine appear as another 
              #physical device on your network. 
              config.vm.network :public_network 
        
              #config.vm.provider :virtualbox do |vb| 
              # # Don't boot with headless mode 
              #  vb.gui = true 
              # 
              #  # Use VBoxManage to customize the VM. For example to change memory: 
              #  vb.customize ["modifyvm", :id, "--memory", "1024"] 
              #end 
            end
        
        **Step 2:** Next you will create a simple bootstrap provision file to
        use with vagrant VM. Copy the following into a file called
        *'bootstrap.sh'* in the same directory as your Vagrantfile.
        
        ::
        
            #!/usr/bin/env bash
            sudo apt-get update                         # Update apt-get
            sudo apt-get install -yf vim                # VIM because VI isn't as cool
            sudo apt-get install -yf git                # install git
            sudo apt-get install -yf nginx              # install nginx
            sudo apt-get install -yf mysql-client       # only install mysql command line client
            sudo apt-get install -yf libmysqlclient-dev # needed for django mysql integration
        
            ### PYTHON STUFF
            sudo apt-get install -yf python-setuptools
            sudo apt-get install -yf python-virtualenv
            sudo apt-get install -yf python-dev
            sudo apt-get install -yf build-essential
        
        **Step 3:** Power on your virtual machine and finish setting it up:
        
        ::
        
            vagrant up
        
        When vagrant finishes powering up, log into your VM with:
        
        ::
        
            vagrant ssh
        
        Next you should create a new user for deplying your django project. If
        you want to follow along closely with this tutorial then create a user
        name *'anouman'*.
        
        ::
        
            sudo adduser anouman
        
        Next you will want to give your new user sudo privileges, by editing
        /etc/sudoers and adding the following line:
        
        ::
        
            anouman ALL=(ALL:ALL) ALL  
        
        directly below the line that says:
        
        ::
        
            root    ALL=(ALL:ALL) ALL
        
        Next you need to make sure your server has the appropriate database
        software installed. This tutorial will assume you are using MySQL since
        the provision script above already installed mysql-client you only need
        to install mysql-server.
        
        ::
        
            sudo apt-get install mysql-server
        
        Now we will use ifconfig to determine the public ip address of your new
        server.
        
        ::
        
            ifconfig
        
        Remember this information because you know want to logout and log back
        in as your new user.
        
        ::
        
            exit
            ssh anouman@your.vm.ip.address
        
        Assuming this worked then you are ready to walk through the anouman
        tutorial and deploy your django project on a fresh virtual machine.
        
        Anouman Setup and Deployment Tutorial
        -------------------------------------
        
        Section 1: Packaging
        ~~~~~~~~~~~~~~~~~~~~
        
        **Step 1:** Switch to the python virtualenv you use for development. You
        are using `virtualenv <http://www.virtualenv.org/en/latest/>`__ for
        python development right? If not Anouman should still work with your
        python system packages.
        
        ::
        
                source /path/to/your/virtualenv/activate
                pip install anouman
        
        **Step 2:** Update your django settings file to reflect the Virtual
        Machine you are about to deploy it on.
        
        First set your database host to match the ip address of the virtual
        machine you created above. For example if your virtual machine ip is
        10.0.1.15 then make sure you have the following in the DATABASES section
        of your settings file:
        
        ::
        
            'HOST': '10.0.1.15'
        
        Next we need to ensure that STATIC\_ROOT and MEDIA\_ROOT are set
        correctly in your settings.py file. I recommend installing into the
        anouman package location... For example if your domain name is
        *example.com* and your deployment user is *anouman* then I reccomend
        updating your settings.py file with the following:
        
        ::
        
                STATIC_ROOT=/home/anouman/example.com/static_root
                MEDIA_ROOT=/home/anouman/example.com/media_root
                
        
        Now when you run *manage.py collectstatic* your site will stay bundled
        up in one nice neat directory, which turns out to be incredibly useful
        if you want to deploy and manage more than one site...
        
        **Step 3:** Next you will create an anouman package that will be
        deployable on an anouman loaded server. Start by navigating to the
        directory containing your django project. This is the directory you
        originally ran "django-admin.py startproject" from and type the
        following.
        
        ::
        
                anouman --django-project={path to your change project} --domainname=example.com
        
        Behind the scenes your django project was copied into a directory named
        example.com/src. Inside this directory is another file which contains a
        listing of python packages you are using for your django projects. This
        was determiend from the output of "pip freeze"
        
        Section2: Deploying
        ~~~~~~~~~~~~~~~~~~~
        
        **Step 4:** Scp your project to the virtual machine we created above.
        
        ::
        
                scp example.com.tar.gz  anouman@your.vm.ip.address:/home/anouman
        
        **Step 5:** Install anouman into the servers system python repository.
        
        ::
        
                sudo pip install anouman
        
        **Step 6:** Setup anouman and deploy your new project. The first time
        you run anouman, with or without arguments, it will install itself. For
        the sake of this tutorial we will do both setup and deployment with one
        command.
        
        ::
        
                anouman --deploy example.com.tar.gz
        
        The first time you call anouman it will download and install
        virtualenv/virtualenvwrapper and create a wrapped 'anouman' virtualenv
        and a wrapped 'example.com' virtualenv.
        
        **Step 7:** We now want to update your .bash\_profile so the bash
        environment for your site is loaded on login. To do this add the
        following lines to the end of your .bash\_profile. If you don't have a
        .bash\_profile in your home directory create one.
        
        ::
        
            source /usr/local/bin/virtualenvwrapper.sh
            workon example.com
        
        Now load the new environment:
        
        ::
        
            source ~/.bash_profile
        
        **Step 8:** You now have a few shell commands that were appended to the
        end of your sites virtualenv activate script. For instance to check the
        status of gunicorn/nginx type:
        
        ::
        
            site status
        
        Now let's bring it up..
        
        ::
        
            site start
        
        Likewise you can stop your site with:
        
        ::
        
            site stop
        
        and you can force nginx to do a reload with:
        
        ::
        
            site reload
        
        These site management commands are specific to the site curently being
        worked on. If you install another django project anouman will gladly set
        it up for you and ensure that nginx properly directs traffic to the
        appropriate django back end and it's all managed with virtualenv and
        virtualenvwrapper. To switch between sites deployed with anouman is as
        simple as switching wrapped virtualenv's. For ex: workon example.com,
        workon site2.com, etc.
        
        **Step 9:** Adjust client /etc/hosts file to simulate DNS for your web
        site. First make sure your site is running (see step 8). Next, add the
        following line to your /etc/hosts
        
        ::
        
            your.site.ip.address   www.example.com   example.com
        
        **Step 10:** Now point your browser to either site1.com and you should
        see you django website. Enjoy.
        
Platform: UNKNOWN
Classifier: Environment :: Web Environment
Classifier: Development Status :: 2 - Pre-Alpha
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python
Classifier: Topic :: Internet :: WWW/HTTP
Classifier: Topic :: Internet :: WWW/HTTP :: WSGI
