From e79f61fa27aebe5deadfbea750985ac5e04c5171 Mon Sep 17 00:00:00 2001
From: Bryan <btbonval@gmail.com>
Date: Mon, 11 Nov 2013 00:25:33 -0500
Subject: [PATCH] new branch for establishing a production-ready KarmaWorld VM
 which is used solely for develpment and local testing.

---
 .gitignore                                    |   6 +
 README.md                                     | 111 ++++++++++--
 Vagrantfile                                   | 165 ++++++++++++++++++
 ...{db_settings.py => db_settings.py.example} |   6 +-
 karmaworld/secret/filepicker.py.example       |   9 +
 .../{static_s3.py => static_s3.py.example}    |   0
 6 files changed, 283 insertions(+), 14 deletions(-)
 create mode 100644 Vagrantfile
 rename karmaworld/secret/{db_settings.py => db_settings.py.example} (54%)
 create mode 100644 karmaworld/secret/filepicker.py.example
 rename karmaworld/secret/{static_s3.py => static_s3.py.example} (100%)

diff --git a/.gitignore b/.gitignore
index c86d8cb..8628a18 100644
--- a/.gitignore
+++ b/.gitignore
@@ -1,3 +1,9 @@
+# Project secret files
+karmaworld/secret/*.py
+
+# ignore vagrant virtual machines
+.vagrant
+
 # Python bytecode:
 *.py[co]
 
diff --git a/README.md b/README.md
index d0256c9..f6998bb 100644
--- a/README.md
+++ b/README.md
@@ -1,6 +1,4 @@
-==========
-KarmaWorld
-==========
+# KarmaWorld
 __Description__: A django application for sharing and uploading class notes.
 
 __Copyright__: FinalsClub, a 501c3 non-profit organization
@@ -14,24 +12,111 @@ v3.0 of the karmanotes.org website from the FinalsClub Foundation
 
 
 
-Purpose
-=======
+# Purpose
 
 KarmaNotes is an online database of college lecture notes.  KarmaNotes empowers college students to participate in the free exchange of knowledge. 
 
-Docs
-====
+# Pre-Installation
 
-TODO: see `./docs/`
-TODO: Put docs on [RTFD](https://readthedocs.org/)
+Clone the project from the central repo using your github account:
 
+    git clone git@github.com:FinalsClub/karmaworld.git
 
-Install
-=======
+If you aren't using a system setup for github, then grab the project with
+this command instead:
 
-TODO: see `./docs/source/os-install.rst`
-TODO: Put docs on [RTFD](https://readthedocs.org/)
+    git clone https://github.com/FinalsClub/karmaworld.git
 
+Generally speaking, this will create a subdirectory called `karmaworld` under
+the directory where the `git` command was run. This git repository directory
+will be referred to herein as `{project_root}`.
+
+There might be some confusion as the git repository's directory will likely be
+called `karmaworld` (this is `{project_root}`), but there is also a `karmaworld`
+directory underneath that (`{project_root}/karmaworld`) alongside files like
+`fabfile.py` (`{project_root}/fabfile.py`) and `README.md`
+(`{project_root}/README.md`).
+
+# Development Install
+
+If you need to setup the project for development, it is highly recommend that
+you grab an existing development virtual machine for create one yourself, and
+then configure the virtual machine for production with the steps shown in the
+next section. Instructions for creating a virtual machine follow:
+
+1. Install (VirtualBox)[http://www.virtualbox.com/]
+
+1. Install (vagrant)[http://www.vagrantup.com/]
+
+1. Use Vagrant to create the virtual machine.
+    * While in `cd {project_root}`, type `vagrant up`
+
+# Production Install
+
+If you're starting to work on this project and you need it setup for production,
+follow the steps below.
+
+1. Ensure the following are installed:
+   * `git`
+   * `PostgreSQL` (server and client)
+   * `Python`
+   * `PIP`
+   * `virtualenv` and `virtualenvwrapper`
+
+1. Generate a PostgreSQL database and a role with read/write permissions.
+   * For Debian, these instructions are helpful: https://wiki.debian.org/PostgreSql
+
+1. Modify configuration files.
+   * There are settings in `{project_root}/karmaworld/settings/dev.py`
+   * There are additional configuration options for external dependencies
+     under `{project_root}/karmaworld/secret/`.
+       * Copy files with the example extension to the corresponding filename
+         without the example extension (e.g.
+         `cp filepicker.py.example filepicker.py`) 
+       * Modify those files.
+           * Ensure `PROD_DB_USERNAME`, `PROD_DB_PASSWORD`, and `PROD_DB_NAME`
+             inside `db_settings.py` match the role, password, and database
+             generated in the previous step.
+       * Ensure *.py in `secret/` are never added to the git repo. (.gitignore
+         should help warn against taking this action)
+
+1. Make sure that you're in the root of the project that you just cloned and
+   run
+
+        fab here first_deploy
+
+   This will make a virtualenv, install the development dependencies and create
+   the database tables.
+
+1. Now you can run ``./manage.py runserver`` and visit the site in the browser.
+
+# Accessing the Vagrant Virtual Machine
+
+## Connecting to the VM via SSH
+If you have installed a virtual machine using `vagrant up`, you can connect
+to it by running `vagrant ssh` from `{project_root}`.
+
+## Updating the VM code repository
+Once connected to the virtual machine by SSH, you will see `karmaworld` in
+the home directory. That is the `{project_root}` in the virtual machine.
+
+`cd karmaworld` and then use `git fetch; git merge` and/or `git pull origin` as
+desired.
+
+The virtual machine's code repository is set to use your host machine's
+local repository as the origin. So if you make changes locally and commit them,
+without pushing them anywhere, your VM can pull those changes in for testing.
+
+This may seem like duplication. It is. The duplication allows your host machine
+to maintain git credentials and manage repository access control so that your
+virtual machine doesn't need sensitive information. Your virtual machine simply
+pulls from the local repository on your local file system without needing
+credentials, etc.
+
+## Other Vagrant commands
+Please see (vagrant documentation)[http://docs.vagrantup.com/v2/cli/index.html]
+for more information on how to use the vagrant CLI to manage your development
+VM.
 
 Thanks
 ======
diff --git a/Vagrantfile b/Vagrantfile
new file mode 100644
index 0000000..dc458ca
--- /dev/null
+++ b/Vagrantfile
@@ -0,0 +1,165 @@
+# -*- mode: ruby -*-
+# vi: set ft=ruby :
+
+# This file is for use by Vagrant (http://www.vagrantup.com/).
+# It will establish a debian-based (Ubuntu) virtual machine for development.
+
+# The virtual machine environment attempts to match the production environment 
+# as closely as possible.
+
+# This file was generated by `vagrant up` and consequently modified.
+
+# Vagrantfile API/syntax version. Don't touch unless you know what you're doing!
+VAGRANTFILE_API_VERSION = "2"
+
+# Install fabric so that the KarmaWorld fabfile may be run.
+
+# build a shell script that installs prereqs, configures the database, pulls in
+# the code from the host machine, and then runs fabric.
+shellscript = <<SCRIPT
+apt-get update
+apt-get upgrade -y
+apt-get install -y python-pip postgresql python-virtualenv virtualenvwrapper git
+
+echo "CREATE USER vagrant WITH CREATEROLE LOGIN; CREATE DATABASE karmaworld OWNER vagrant;" | su postgres -c "psql"
+
+su vagrant -c "git clone /vagrant karmaworld"
+
+pip install fabric
+#su vagrant -c "cd karmaworld; fab here first_deploy"
+SCRIPT
+# end of script
+
+Vagrant.configure(VAGRANTFILE_API_VERSION) do |config|
+  # All Vagrant configuration is done here. The most common configuration
+  # options are documented and commented below. For a complete reference,
+  # please see the online documentation at vagrantup.com.
+
+  # Every Vagrant virtual environment requires a box to build off of.
+  config.vm.box = "Official Ubuntu 12.04 daily Cloud Image i386"
+  #config.vm.box = "Official Ubuntu 12.04 daily Cloud Image amd64"
+  #config.vm.box = "Official Ubuntu 12.10 daily Cloud Image i386"
+  #config.vm.box = "Official Ubuntu 12.10 daily Cloud Image amd64"
+  #config.vm.box = "Official Ubuntu 13.04 daily Cloud Image i386"
+  #config.vm.box = "Official Ubuntu 13.04 daily Cloud Image amd64"
+  #config.vm.box = "Official Ubuntu 13.10 daily Cloud Image i386"
+  #config.vm.box = "Official Ubuntu 13.10 daily Cloud Image amd64"
+
+  # 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://cloud-images.ubuntu.com/vagrant/precise/current/precise-server-cloudimg-i386-vagrant-disk1.box"
+  #config.vm.box_url = "http://cloud-images.ubuntu.com/vagrant/precise/current/precise-server-cloudimg-amd64-vagrant-disk1.box"
+  #config.vm.box_url = "http://cloud-images.ubuntu.com/vagrant/quantal/current/quantal-server-cloudimg-i386-vagrant-disk1.box"
+  #config.vm.box_url = "http://cloud-images.ubuntu.com/vagrant/quantal/current/quantal-server-cloudimg-amd64-vagrant-disk1.box"
+  #config.vm.box_url = "http://cloud-images.ubuntu.com/vagrant/raring/current/raring-server-cloudimg-i386-vagrant-disk1.box"
+  #config.vm.box_url = "http://cloud-images.ubuntu.com/vagrant/raring/current/raring-server-cloudimg-amd64-vagrant-disk1.box"
+  #config.vm.box_url = "http://cloud-images.ubuntu.com/vagrant/saucy/current/saucy-server-cloudimg-i386-vagrant-disk1.box"
+  #config.vm.box_url = "http://cloud-images.ubuntu.com/vagrant/saucy/current/saucy-server-cloudimg-amd64-vagrant-disk1.box"
+
+  # Create a forwarded port mapping which allows access to a specific port
+  # within the machine from a port on the host machine. In the example below,
+  # accessing "localhost:8080" will access port 80 on the guest machine.
+  # config.vm.network :forwarded_port, guest: 80, host: 8080
+
+  # OM (sanskrit) KW (KarmaWorld) on a phone: 66 59
+  config.vm.network :forwarded_port, guest: 80, host: 6659, auto_correct: true
+
+  # Create a private network, which allows host-only access to the machine
+  # using a specific IP.
+  #config.vm.network :private_network, ip: "192.168.66.59"
+
+  # Create a public network, which generally matched to bridged network.
+  # Bridged networks make the machine appear as another physical device on
+  # your network.
+  # Used to directly access the internet for downloading updates and so forth.
+  config.vm.network :public_network
+
+  # If true, then any SSH connections made will enable agent forwarding.
+  # Default value: false
+  # config.ssh.forward_agent = true
+
+  # Share an additional folder to the guest VM. The first argument is
+  # the path on the host to the actual folder. The second argument is
+  # the path on the guest to mount the folder. And the optional third
+  # argument is a set of non-required options.
+  # config.vm.synced_folder "../data", "/vagrant_data"
+
+  # Setup scripts
+  config.vm.provision "shell", inline: shellscript
+
+  # Provider-specific configuration so you can fine-tune various
+  # backing providers for Vagrant. These expose provider-specific options.
+  # Example for VirtualBox:
+  #
+  # 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
+  #
+  # View the documentation for the provider you're using for more
+  # information on available options.
+
+  # Enable provisioning with Puppet stand alone.  Puppet manifests
+  # are contained in a directory path relative to this Vagrantfile.
+  # You will need to create the manifests directory and a manifest in
+  # the file base.pp in the manifests_path directory.
+  #
+  # An example Puppet manifest to provision the message of the day:
+  #
+  # # group { "puppet":
+  # #   ensure => "present",
+  # # }
+  # #
+  # # File { owner => 0, group => 0, mode => 0644 }
+  # #
+  # # file { '/etc/motd':
+  # #   content => "Welcome to your Vagrant-built virtual machine!
+  # #               Managed by Puppet.\n"
+  # # }
+  #
+  # config.vm.provision :puppet do |puppet|
+  #   puppet.manifests_path = "manifests"
+  #   puppet.manifest_file  = "site.pp"
+  # end
+
+  # Enable provisioning with chef solo, specifying a cookbooks path, roles
+  # path, and data_bags path (all relative to this Vagrantfile), and adding
+  # some recipes and/or roles.
+  #
+  # config.vm.provision :chef_solo do |chef|
+  #   chef.cookbooks_path = "../my-recipes/cookbooks"
+  #   chef.roles_path = "../my-recipes/roles"
+  #   chef.data_bags_path = "../my-recipes/data_bags"
+  #   chef.add_recipe "mysql"
+  #   chef.add_role "web"
+  #
+  #   # You may also specify custom JSON attributes:
+  #   chef.json = { :mysql_password => "foo" }
+  # end
+
+  # Enable provisioning with chef server, specifying the chef server URL,
+  # and the path to the validation key (relative to this Vagrantfile).
+  #
+  # The Opscode Platform uses HTTPS. Substitute your organization for
+  # ORGNAME in the URL and validation key.
+  #
+  # If you have your own Chef Server, use the appropriate URL, which may be
+  # HTTP instead of HTTPS depending on your configuration. Also change the
+  # validation key to validation.pem.
+  #
+  # config.vm.provision :chef_client do |chef|
+  #   chef.chef_server_url = "https://api.opscode.com/organizations/ORGNAME"
+  #   chef.validation_key_path = "ORGNAME-validator.pem"
+  # end
+  #
+  # If you're using the Opscode platform, your validator client is
+  # ORGNAME-validator, replacing ORGNAME with your organization name.
+  #
+  # If you have your own Chef Server, the default validation client name is
+  # chef-validator, unless you changed the configuration.
+  #
+  #   chef.validation_client_name = "ORGNAME-validator"
+end
diff --git a/karmaworld/secret/db_settings.py b/karmaworld/secret/db_settings.py.example
similarity index 54%
rename from karmaworld/secret/db_settings.py
rename to karmaworld/secret/db_settings.py.example
index f185030..c70f70b 100644
--- a/karmaworld/secret/db_settings.py
+++ b/karmaworld/secret/db_settings.py.example
@@ -1,7 +1,11 @@
 #!/usr/bin/env python
 # -*- coding:utf8 -*-
 # Copyright (C) 2012  FinalsClub Foundation
-""" DO NOT check this file into source control """
+"""
+DO NOT modify this file directly, instead copy it to db_settings.py and modify
+that file.
+DO NOT check db_settings.py into source control.
+"""
 PROD_DB_NAME = 'DB_NAME'
 PROD_DB_USERNAME = 'DB_USER_NAME'
 PROD_DB_PASSWORD = 'PASSWD'
diff --git a/karmaworld/secret/filepicker.py.example b/karmaworld/secret/filepicker.py.example
new file mode 100644
index 0000000..bab7b50
--- /dev/null
+++ b/karmaworld/secret/filepicker.py.example
@@ -0,0 +1,9 @@
+#!/usr/bin/env python
+# -*- coding:utf8 -*-
+# Copyright (C) 2012  FinalsClub Foundation
+"""
+DO NOT modify this file directly, instead copy it to filepicker.py and modify
+that file.
+DO NOT check filepicker.py into source control.
+"""
+FILEPICKER_API_KEY = 0
diff --git a/karmaworld/secret/static_s3.py b/karmaworld/secret/static_s3.py.example
similarity index 100%
rename from karmaworld/secret/static_s3.py
rename to karmaworld/secret/static_s3.py.example
-- 
2.25.1