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