Installing HackDash

In a previous post I explained the project
history, goals and involved people. Shortly saying HackDash is a dashboard where
you can put your project ideas. It was specially designed for Hackatons but it
was used for other purposes with really good results.

Since I received lots of mails asking how to install it in different servers
I decided to make this post explaining how can you install it for yourself.

Furthermore I will explain the steps I usually do in order to install a
HackDash instance using Heroku and MongoLab (you can use it for free for small
projects, the free version for both services can hold a HackDash instance with an interesting amount of users and projects).

Dashboard

Basic Install

Installation Prequisites

HackDash is based on top of 2 open-source projects:

Node.js: You can install it using the install button on the home page. If you are using Linux you can build the sources or use your favorite package manager.
MongoDB: the downloads page will help you with the installation process.

That’s it. If you can run node.js and MongoDB, you can then install a HackDash instance.

Download the project and install the dependencies

First, download the project source. You can Download it from this link or clone the repo:

$ git clone git@github.com:danzajdband/hackdash.git

Then, inside the project folder, install the dependencies

$ npm install

Project configuration

When this process finish you'll need to config the app. The easiest way is to
copy the file called config.json.sample to config.json and
keys.json.sample to keys.json.

Open your config.json file and set yur config settings.

The keys.json file allows different auth providers. You need to fill at least
one of those to make your users LogIn. I want to provide email + password login
for the future but now is not available at the moment.

At the moment we allow 4 different auth providers: Twitter, Facebook, Meetup and
Github. Choose the services you want and fill the file with your credentials.

For example to get Twitter credentials you need to go to
Twitter dev and create a new application.

Keep in mind that the callback url format is /auth/{provider}/callback while you generate the provider
credentials.

Run the app

To run the app you just need to start MongoDB (the fork option is optional, it
will run MongoDB in background) and init the node server.

$ mongod --fork your/log/file
$ node server.js

Then open your browser using the address you provide and will have a fully-working HackDash instance.

Deploy options

This apply to any node.js project but I left it as a good remainder (don't
forget the HackDash is not more than a ExpressJS app) some deployment good advices.

If you are going to deploy it in a production environment, start the script with the production flag. $ NODE_ENV=production node server.js
It is recommended to use a node script reloader. I recommend
Up but is up to you.
Forever is also widely used.

Make yourself the Dashboard admin

If you point your browser to yourdomain.com/install while logged in you'll
became the admin of the Dashboard. The /install route will redirect to the
previous page you visited if the admin was selected before.

Installation using Heroku and MongoLab

I choose these services because I made some successful installations on this
environment, and it's pretty easy to work with.

Prequisites

Create a Heroku account and install the CLI.

Download and Configure

The steps (Download and Configure) are the same as the Basic installation, you'll want to
check it out above. For this type of installation I'll ask you to clone the
project instead of downloading the source tarball (It will be easy to deploy then). Once you finish configuring your project instance, this are
the next steps

Create a Procfile

Create a file in the root project folder called Procfile and write inside

web: node server.js

Create the Heroku application

To create a Heroku app, follow this steps

$ heroku login
$ heroku create

Add the MongoLab add-on to the app

I choose the starter package that is free, you can select https://addons.heroku.com/mongolab.

$ heroku addons:add mongolab:starter

Then add your MongoLab URI to the config file, the url will override other db config. To get your MongoLab URI perform this command in your terminal

$ heroku config | grep MONGOLAB_URI

Commit the changes, and deploy

You need to commit the changes you made to push the files to heroku.

$ git add config.json Procfile
$ git commit -m "Heroku deploy config"
$ git push heroku master

Scale the app

If you want to use more than one process it’s cool, you just need to change the 1 in the following command

$ heroku ps:scale web=1

Logs

If you want to see the logs you can do $ heroku logs

Final notes

This is the process I usually do for both kind of deployments. If you have any questions, please contact me. The project is under
development, I’ll be glad to add more people to the list of awesome
contributors.