From 34770262de9cf4d4df2218fc88cc4205b67a41a1 Mon Sep 17 00:00:00 2001 From: Patrick Koenig Date: Wed, 6 Jul 2016 23:36:06 -0400 Subject: [PATCH] Wrote documentation, closes #111 --- README.md | 132 ++++++++++++++++++++++++++++++++++++++++++++++++------ 1 file changed, 119 insertions(+), 13 deletions(-) diff --git a/README.md b/README.md index 6a4cfc05..adbe9a2e 100644 --- a/README.md +++ b/README.md @@ -1,17 +1,123 @@ -Binder App -=== -[![Build Status](https://travis-ci.org/sc0v/binder-app.svg?branch=master)](https://travis-ci.org/sc0v/binder-app) [![Coverage Status](https://img.shields.io/coveralls/sc0v/binder-app.svg)](https://coveralls.io/r/sc0v/binder-app?branch=master) [![security](https://hakiri.io/github/sc0v/binder-app/master.svg)](https://hakiri.io/github/sc0v/binder-app/master) [![Dependency Status](https://gemnasium.com/sc0v/binder-app.svg)](https://gemnasium.com/sc0v/binder-app) [![Code Climate](https://codeclimate.com/github/sc0v/binder-app/badges/gpa.svg)](https://codeclimate.com/github/sc0v/binder-app) +# Binder -The Spring Carnival managment application built for Carnegie Mellon Spring Carnival. +[![Build Status](https://travis-ci.org/sc0v/binder-app.svg?branch=master)](https://travis-ci.org/sc0v/binder-app) +[![Dependency Status](https://gemnasium.com/sc0v/binder-app.svg)](https://gemnasium.com/sc0v/binder-app) +[![Security](https://hakiri.io/github/sc0v/binder-app/master.svg)](https://hakiri.io/github/sc0v/binder-app/master) +[![Coverage Status](https://img.shields.io/coveralls/sc0v/binder-app.svg)](https://coveralls.io/r/sc0v/binder-app?branch=master) +[![Code Climate](https://codeclimate.com/github/sc0v/binder-app/badges/gpa.svg)](https://codeclimate.com/github/sc0v/binder-app) +Binder is a Spring Carnival management application built for [Carnegie Mellon Spring Carnival](https://www.springcarnival.org) using [Ruby on Rails](http://rubyonrails.org/). Binder is used by Spring Carnival Committee and booth building organizations to do things including tracking build progress, managing tool checkouts, selling building supplies, assessing fines/charges, and supervising student shifts. -Contributors: -- Chase Brownell -- Rachel Crown -- Meg Richards +Carnegie Mellon's Spring Carnival Committee hosts two live instances of Binder: +* **Production** (https://binder.springcarnival.org) - This environment is the production environment used to manage Spring Carnival and contains real data. *Do not deploy changes to this instance without first testing in the staging instance*. +* **Staging** (https://binder-dev.springcarnival.org) - This environment is identical to the production environment but contains fake data. This environment is used to test changes in a production-like environment before deploying them to the production instance. -And as part of 475: -- Steve McQuaid -- Dylan Corwin -- Shannon Chen -- Jonathan Chung + +## Setting up a development environment + +To work on and contribute to Binder, you will need to run Binder in a local development environment. + +It is highly recommended that you use a Linux environment for development, preferably in a Debian-based distribution. [Ubuntu](http://www.ubuntu.com), [Debian](https://www.debian.org/), and [Linux Mint](https://www.linuxmint.com/) are some popular Debian-based Linux distributions (the Spring Carnival Committee server that hosts Binder runs Ubuntu). The easiest way to quickly set up a Linux development environment is by using a VM. + +The following set up instructions are for Debian-based systems (specifically, Ubuntu). However, the general procedure is applicable for setting up Binder in any development environment, although the details of each step will likely differ. + +#### 1. Clone the Binder repository + +Clone the Binder repository. To do this, run the following command (you can choose any destination directory): + +``` +git clone https://github.com/sc0v/binder-app.git ~/binder-app +``` + +#### 2. Install dependencies + +Binder depends on [MySQL](https://www.mysql.com/), [SQLite](https://www.sqlite.org/), and a handful of additional development packages. To install these dependencies, run the following command: + +``` +sudo apt-get install mysql-server sqlite3 libldap2-dev libmysqlclient-dev libreadline-dev libsasl2-dev libsqlite3-dev libssl-dev zlib1g-dev +``` + +During installation of MySQL you must create a non-blank password for the MySQL "root" user. Binder reads the MySQL username and password through the environment variables `MYSQL_USERNAME` and `MYSQL_PASSWORD`, respectively. To set these environment variables, you will need to add them to your `~/.bashrc` (or other appropriate startup script). To do this, run the following command (where `` is replaced with the password you created): + +```sh +echo 'export MYSQL_USERNAME=root' >> ~/.bashrc +echo 'export MYSQL_PASSWORD=' >> ~/.bashrc +``` + +#### 3. Install Ruby + +Binder is a [Ruby on Rails](http://rubyonrails.org/) application, so running it requires an installation of [Ruby](https://www.ruby-lang.org). It is highly recommended that you use [rbenv](https://github.com/rbenv/rbenv) and [ruby-build](https://github.com/rbenv/ruby-build) to install and manage the Ruby versions installed in your development environment. To install Ruby: + +1. Follow the [instructions for installing rbenv](https://github.com/rbenv/rbenv#installation). +2. Follow the [instructions for installing ruby-build](https://github.com/rbenv/ruby-build#installation). It should be installed as a rbenv plugin. +3. Install the Ruby version used by Binder (currently 2.3.0, see [Gemfile](Gemfile)) and set it as the global Ruby version. To do this, run the following command: + + ``` + rbenv install 2.3.0 + rbenv global 2.3.0 + ``` + +#### 4. Install gem dependencies + +Binder depends on numerous Ruby libraries, called gems, which are managed using [RubyGems](https://rubygems.org/). To install these gem dependencies: + +1. Install the [Bundler](http://bundler.io/) gem (Bundler is used to manage gem dependencies in Binder). To do this, run the following command: + + ``` + gem install bundler + ``` +2. Install all gem dependencies. To do this, run the following command in the Binder repository directory: + + ``` + bundle install + ``` + +#### 5. Seed the database + +The database must be seeded with data before Binder can be run. To do this, run the following command in the Binder repository directory: + +``` +rake db:setup +``` + +
+To list all available rake tasks, run the following command in the Binder repository directory: + +``` +rake -T +``` + +#### 6. Run Binder + +To run Binder, run the following command in the Binder repository directory: + +``` +rails server +``` + +You can then navigate to [http://localhost:3000](http://localhost:3000) to view your local instance of Binder. For more options see the [rails server documentation](http://guides.rubyonrails.org/command_line.html#rails-server). + + +## Deploying Binder + +[Capistrano](http://capistranorb.com/) is used to deploy Binder to the staging and production instances. Capistrano deployment updates the staging or production environment to a specified revision from the Binder repository. + +***Do not deploy changes to the production instance without first testing in the staging instance***. + +To deploy Binder to the staging or production instance, run the following command in the Binder repository directory (where `` is either `staging` or `production`: + +``` +cap deploy +``` +By default, Capistrano deploys Binder from the `master` branch. However, when testing new features or improvements we often want to deploy from a different branch. To deploy from a specified branch, run the following command (where `` is replaced with the name of the branch to deploy from): + +``` +cap deploy branch= +``` + +
+To list all available Capistrano tasks, run the following command in the Binder repository directory: + +``` +cap -T +```