-==========
-KarmaWorld
-==========
+# KarmaWorld
__Description__: A django application for sharing and uploading class notes.
__Copyright__: FinalsClub, a 501c3 non-profit organization
-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
======
--- /dev/null
+# -*- 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
projects / oweals / karmaworld.git / commitdiff