configuring databases, init

docs/configuring/databases.rst

@@ -1,11 +1,39 @@
 Configuring Databases
 =====================
 
+NodeBB has a Database Abstraction Layer (DBAL) that allows one to write  drivers for their database of choice. Currently we have the following options:
 
-testing
+.. toctree::
+    :hidden:
+    :maxdepth: 0
 
+    MongoDB <databases/mongo>
+    LevelDB <databases/level>
 
-testing
--------
+* Redis (default, see :doc:`installation guides <../installing/os>`)
+* :doc:`Mongo <databases/mongo>`
+* :doc:`Level <databases/level>`
 
-testing
+.. note::
+
+    If you would like to write your own database driver for NodeBB, please visit our `community forum <https://community.nodebb.org>`_ and we can point you in the right direction.
+
+
+Running a Secondary Database
+----------------------------
+
+
+.. warning::
+
+    **This option is experimental and should not be used on a production environment.**
+
+
+Both databases **must** be flushed before beginning - there isn't a mechanism yet that detects an existing installation on one database but not another. Until fail-safe's such as these are implemented this option is hidden under the `--advanced` setup flag.
+
+.. code:: bash
+
+    node app --setup --advanced
+
+Consult the other database guides for instructions on how to set up each specific database. Once you select a secondary database's modules, there's no turning back - until somebody writes an exporter/importer.
+
+Currently this setup is being tested with Redis as the primary store (sets, lists, and sorted sets, because Redis is super fast with these), and Mongo as the hash store (post and user data, because ideally we wouldn't want this in RAM).

docs/configuring/databases/level.rst

@@ -0,0 +1,15 @@
+LevelDB
+=======
+
+Follow the instructions on the [homepage](https://github.com/designcreateplay/NodeBB/wiki) but feel free to omit the Redis installation.
+
+After cloning NodeBB, ensure that you run:
+
+    npm install levelup leveldown
+
+
+Finally, set up a directory to store your LevelDB database, for example:
+
+    mkdir /var/level/
+
+Run the NodeBB install, select `level` when it prompts you for your database. If you created the folder as above, you can leave the rest of the questions as default.

docs/configuring/databases/mongo.rst

@@ -0,0 +1,95 @@
+MongoDB
+=======
+
+If you're afraid of running out of memory by using Redis, or want your forum to be more easily scalable, you can install NodeBB with MongoDB. This tutorial assumes you know how to SSH into your server and have root access.
+
+**These instructions are for Ubuntu. Adjust them accordingly for your distro.**
+
+**Note:** If you have to add `sudo` to any command, do so. No one is going to hold it against you ;)
+
+## Step 1: Install MongoDB
+
+the latest and greatest MongoDB is required (or at least greater than the package manager). The instructions to install it can be found at [http://docs.mongodb.org/manual/administration/install-on-linux/](http://docs.mongodb.org/manual/administration/install-on-linux/).
+
+## Step 2: Install node.js
+
+Like MongoDB, the latest and greatest node.js is required (or at least greater than the package manager), so I'm leaving this to the official wiki. The instructions to install can be found at [https://github.com/joyent/node/wiki/Installing-Node.js-via-package-manager](https://github.com/joyent/node/wiki/Installing-Node.js-via-package-manager).
+
+*Note: NPM is installed along with node.js, so there is no need to install it separately*
+
+## Step 3: Install the Base Software Stack
+
+Enter the following into the terminal to install the base software required to run NodeBB:
+
+    # apt-get install git build-essential imagemagick
+
+## Step 4: Clone the Repository
+
+Enter the following into the terminal, replacing `/path/to/nodebb/install/location` to where you would like NodeBB to be installed.
+
+    $ cd /path/to/nodebb/install/location
+    $ git clone git://github.com/designcreateplay/NodeBB.git nodebb
+
+## Step 5: Install The Required NodeBB Dependencies
+
+Go into the newly created `nodebb` directory and install the required dependencies by entering the following.
+
+    $ cd nodebb
+    $ npm install
+
+## Step 6: Adding a New Database With Users
+
+To go into the MongoDB command line, type:
+
+    $ mongo
+
+To add a new database called `nodebb`, type:
+
+    > use nodebb
+
+To add a user to access the `nodebb` database, type:
+
+    > db.addUser( { user: "nodebb",
+    ...       pwd: "<Enter in a secure password>",
+    ...       roles: [ "userAdmin" ] } )
+
+**Note:** The role `userAdmin` gives all permissions to the user for that specific database.
+
+## Step 7: Configure MongoDB
+
+MongoDB needs text search enabled. Modify `/etc/mongodb.conf`.
+
+    # nano /etc/mongodb.conf
+
+Add `setParameter=textSearchEnabled=true` to the end. Also, to enable authentication, uncomment `auth = true`. Restart MongoDB.
+
+    # service mongodb restart
+
+## Step 8: Configuring NodeBB
+
+Make sure you are in your NodeBB root folder. If not, just type:
+
+    $ cd /path/to/nodebb
+
+To setup the app, type:
+
+    $ node app --setup
+
+* Change the hostname to your domain name.  
+* Accept the defaults by pressing enter until it asks you what database you want to use. Type `mongo` in that field.
+* Accept the default port, unless you changed it in the previous steps.
+* Change your username to `nodebb`, unless you set it to another username.
+* Enter in the password you made in step 5.
+* Change the database to `nodebb`, unless you named it something else.
+
+Continue with the installation, following the instructions the installer provides you.
+
+## Step 9: Starting the App
+
+To start the app, run:
+
+    $ node app
+
+Now visit `yourdomainorip.com:4567` and your NodeBB installation should be running.
+
+NodeBB can also be started with helper programs, such as [`supervisor` and `forever`](https://github.com/designcreateplay/NodeBB/wiki/How-to-run-NodeBB). You can also use `nginx` as a [reverse proxy](https://github.com/designcreateplay/NodeBB/wiki/Configuring-nginx-as-a-proxy-to-NodeBB).

docs/configuring/databases/secondary.rst

@@ -0,0 +1,9 @@
+**This option is experimental and should not be used on a production environment.**
+
+Both databases **must** be flushed before beginning - there isn't a mechanism yet that detects an existing installation on one database but not another. Until fail-safe's such as these are implemented this option is hidden under the `--advanced` setup flag.
+
+    node app --setup --advanced
+
+Consult the other database guides for instructions on how to set up each specific database. Once you select a secondary database's modules, there's no turning back - until somebody writes an exporter/importer.
+
+Currently this setup is being tested with Redis as the primary store (sets, lists, and sorted sets, because Redis is super fast with these), and Mongo as the hash store (post and user data, because ideally we wouldn't want this in RAM).

docs/installing/heroku.rst

@@ -0,0 +1,47 @@
+Heroku
+======
+
+**Note**: Installations to Heroku require a local machine with some flavour of unix, as NodeBB does not run on Windows.
+
+1. Download and install `Heroku Toolbelt <https://toolbelt.heroku.com/>`_ for your operating system
+2. Log into your Heroku account: ``heroku login``
+3. Verify your Heroku account by adding a credit card (at http://heroku.com/verify)
+4. Clone the repository: ``git clone https://github.com/designcreateplay/NodeBB.git /path/to/repo/clone``
+5. ``cd /path/to/repo/clone``
+6. Install dependencies locally ``npm install``
+7. Create the heroku app: ``heroku create``
+8. Enable WebSocket support (beta): ``heroku labs:enable websockets -a {APP_NAME}``, where ``{APP_NAME}`` is provided by Heroku, and looks something like ``adjective-noun-wxyz.herokuapp.com`` (NOTE: `See this doc <https://discussion.heroku.com/t/application-error/160>`_): drop the `.herokuapp.com` when entering ``{APP_NAME}`` above. 
+9. Enable `Redis To Go <https://addons.heroku.com/redistogo>`_ for your heroku account: ``heroku addons:add redistogo:nano``
+10. Run the NodeBB setup script: ``node app --setup`` (information for your Heroku server and Redis to Go instance can be found in your account page)
+    * Your server name is found in your Heroku app's "settings" page, and looks something like ``adjective-noun-wxyz.herokuapp.com``
+    * Use any port number. It will be ignored.
+    * Specify "n" when asked if a port will be used. Heroku transparently proxies all requests.
+    * Your redis server can be found as part of the redis url. For example, for the url: ``redis://redistogo:h28h3wgh37fns7@crestfish.redistogo.com:12345/``
+    * The server is ``fishyfish.redistogo.com``
+    * The port is ``12345``
+    * The password is ``h28h3wgh37fns7``
+11. Create a Procfile for Heroku: ``echo "web: node app.js" > Procfile``
+12. Commit the Procfile:
+
+.. code:: bash
+
+	git add -f Procfile config.json public/config.json && git commit -am "adding Procfile and configs for Heroku"
+
+13. Push to heroku: ``git push heroku master``
+    * Ensure that a proper SSH key was added to your account, otherwise the push will not succeed!
+14. Initialise a single dyno: ``heroku ps:scale web=1``
+15. Visit your app!
+
+If these instructions are unclear or if you run into trouble, please let us know by `filing an issue <https://github.com/designcreateplay/NodeBB/issues>`_.
+
+Keeping it up to date
+---------------------
+
+If you wish to pull the latest changes from the git repository to your Heroku app:
+
+1. Navigate to your repository at ``/path/to/nodebb``
+2. ``git pull``
+3. ``npm install``
+4. ``node app --upgrade``
+5. ``git commit -am "upgrading to latest nodebb"``
+6. ``git push heroku master``