README.md

   1
   2 # Finals Club (FC)
   3
   4 This is the source code repository for [finalsclub.org](http://finalsclub.org/).
   5
   6 FC is a 501(c)(3) non-profit open education project dedicated to
   7 helping college students collaborate, learn, and share their knowledge freely online.
   8
   9
  10 ## Additional resources
  11
  12 [[ discussion groups, chat rooms, etc. related to FC and FC sources ]]
  13
  14
  15
  16 # Quick install
  17
  18 Requirements:
  19
  20 - Debian/ubuntu-server GNU/Linux Box with a modern kernel (2.6.39 <)
  21 - 1 GB (idealy) 512MB min.
  22 - Node.js (Version 0.6.1 or later) [More ...](http://nodejs.org)
  23 - MongoDB (Version  2.0.2 or later) [More ...](http://mongodb.org)
  24 - forever
  25
  26 Deployment:
  27
  28 1. Copy setup.sh to home directory.
  29
  30 2. REVIEW setup.sh BEFORE RUNNING!!!!
  31
  32 3. run: sudo setup.sh
  33
  34 4. mongorestore any back-up databases that you may have.
  35
  36 5. Copy "start" to home directory and run.
  37
  38
  39
  40 # System components
  41
  42 The system consists of these main parts:
  43
  44 - The website
  45 - The collaborative, real-time editor
  46 - The back channel
  47
  48 Most of the system is written in Javascript and executed by the Node.js runtime.
  49
  50
  51 # Source Code
  52
  53
  54 ## The Collaborative Real-time Editor
  55
  56 The editor is an embedded editor called [Etherpad-Lite](https://github.com/Pita/etherpad-lite) (EPL).
  57 It provides the ability for multiple people to simultaneously edit a single document.
  58 The documents in FC are the notes for a specific lecture.
  59
  60 EPL is installed as a git submodule to the main FC source tree with the name "etherpad-lite".
  61
  62
  63 ## The Back Channel (BC)
  64
  65 The back channel portion of FC is implemented with ["BC"](https://github.com/FinalsClubDev/bc).
  66 BC allows the note takers, or anyone else who is just observing,
  67 to suggest questions for the lecturer, and vote on each other's questions.
  68 It also allows people to post commentary.
  69
  70 Although the actual BC code was written for FC, it has been extracted from the original
  71 FC source and turned into an independent open source project.
  72
  73 BC is installed as a git submodule to the main FC source tree with the name "bc".
  74
  75
  76 ## The Surrounding Website
  77
  78 This is the FC website, which brings together the other two elements into
  79 a single website that serves it's stated purpose (above).
  80 This would be the home page, privacy policy page, the page that lists the participating
  81 schools, the sub pages containing lists of lectures and note taking sessions, and the
  82 core page where EPL and BC are both found along side each other.
  83
  84 Several node modules are leveraged to to make the basic website work:
  85
  86 - [async](http:npmjs.org)
  87 - [aws-lib](http:npmjs.org)
  88 - [connect](http:npmjs.org)
  89 - [connect-mongo](http:npmjs.org)
  90 - [ejs](http:npmjs.org)
  91 - [express](http:npmjs.org)
  92 - [express-messages](http:npmjs.org)
  93 - [hat](http:npmjs.org)
  94 - [hooks](http:npmjs.org)
  95 - [init](http:npmjs.org)
  96 - [jade](http:npmjs.org)
  97 - [mongodb](http:npmjs.org)
  98 - [mongoose](http:npmjs.org)
  99 - [socket.io](http:npmjs.org)
 100
 101
 102 [[ more detail about website generally, then defer to src comments ]]
 103
 104
 105 # Database
 106
 107 The database is MongoDB.
 108 MongoDB is not a relational database, but rather a noSQL or "document/object" database.
 109 Data is stored as structured objects versus tables and rows.
 110 (More about MongoDB)[http://mongodb.org].
 111
 112 ## Collections in the database
 113
 114 - archivedcourses
 115         [[ schema needed ]]
 116 - archivednotes
 117         [[ schema needed ]]
 118 - archivedsubjects
 119         [[ schema needed ]]
 120 - courses
 121         [[ schema needed ]]
 122 - lectures
 123         [[ schema needed ]]
 124 - notes
 125         [[ schema needed ]]
 126 - posts
 127         [[ schema needed ]]
 128 - schools
 129         [[ schema needed ]]
 130 - sessions
 131         [[ schema needed ]]
 132 - users
 133         [[ schema needed ]]
 134
 135
 136 ## [[ stuff ]]
 137
 138 [[ notes about scaling/replication/etc. ]]
 139
 140
 141
 142 # AWS Infrastructure
 143
 144 The actual finalsclub.org servers run in the cloud on Linux servers, using Amazon Web Services (AWS).
 145 Scaling is accomplished by adding additional servers to a load balancer.
 146
 147 NOTE: The scaling system is automatic; new servers have to be added manually, but it it's very easy.
 148 NOTE: Automatic fail-over of the database is not yet in place.
 149
 150 NOTE: There are currently 2 running server instances.  One for the live server and one for testing.
 151
 152 Data is stored in a MongoDB server running on the same AWS instance as the website.
 153 Data is backed up daily to the durable AWS S3 system.
 154 One backup of the database is kept for the most recent 30 days, one for each of the most
 155 recent 12 months, and one for every year.
 156
 157 AWS Cloudwatch is used to monitor the servers.
 158 When the configured conditions warrant attention, notices are sent to "info@finalsclub.org".
 159
 160 NOTE: There are currently 2 monitors set up:
 161
 162 - available disk space
 163 - CPU utilization
 164
 165 NOTE: We still have an ongoing issue with the EPL server hanging up.  This is being worked on.
 166
 167
 168
 169
 170