octobox.js

Port of octobox to node.js

Table of Contents

Table of Contents

- [Motivation](#motivation) - [Usage](#usage) - [Requirements](#requirements) - [Deployment to Heroku](#deployment-to-heroku) - [Development](#development) * [Getting started](#getting-started) + [Local database](#local-database) + [GitHub OAuth Application](#github-oauth-application) + [Configuration](#configuration) + [Start](#start) - [About](#about) * [Related projects](#related-projects) * [Contributing](#contributing) * [Running tests](#running-tests) * [Author](#author) * [License](#license)

Motivation

This is a port of Octobox from Ruby to JavaScript using express, sequelize, and handlebars instead of Rails, ActiveDirectory, and erb.

The goal is to learn more about the pieces of Rails and ActiveDirectory that are missing from Node.js and fill the gap by using other tools like assemble and generate and by creating missing tools like helper-octicon.

You can also read about the original motivation and features of the Octobox project here.

Usage

There is a hosted version available to try now.

You may also deploy to heroku and host it yourself.

Requirements

Web notifications must be enabled in your GitHub settings for Octobox.js to work: https://github.com/settings/notifications

Deployment to Heroku

You can host your own instance of Octobox.js using Heroku.

Heroku will ask you to provide a GitHub Client ID and GitHub Client Secret which you can get from GitHub by creating a new OAuth Application.

Optionally, you may set a Google Analytics Tracking ID that will place the Google Analytics script in each page.

Development

The source code is hosted at GitHub.

Getting started

Since this is a port to Node.js, you'll need Node.js and NPM. NPM will be installed when installing Node.js.

Once you have Node.js installed, git clone the repository:

$ git clone https://github.com/doowb/octobox.js.git

Then install the npm dependencies:

$ cd octobox.js
$ npm install

Local database

You'll need a local PostgreSQL database installed. On OSX you may use Homebrew or the PostgresApp. Please see these further instructions for installing Postgres via Homebrew.

$ brew install postgres

On Debian-based Linux distributions you can use apt-get to install Postgres:

$ sudo apt-get install postgresql postgresql-contrib libpq-dev

Next, you'll need to create the development and test databases:

Using psql:

$ psql

Create octobox_development and octobox_test databases:

> CREATE DATABASE octobox_development;
> CREATE DATABASE octobox_test;

Optionally, you may create a "production" database named octobox:

> CREATE DATABASE octobox;

These database names may be changed as long as the configuration files are changed to reflect the same names.

GitHub OAuth Application

Register a new OAuth Application for your development environment using the following settings:

If you're deploying this to production, just replace http://localhost:3000 with your application's URL.

Configuration

The repository has config.json files ignored in .gitignore to allow for keeping secrets, for your development environment, private. There are 2 files that should be added.

The first is config.json in the root of the project:

{
  "url": "http://localhost:3000",
  "GITHUB_CLIENT_ID": "YOUR_GITHUB_CLIENT_ID",
  "GITHUB_CLIENT_SECRET": "YOUR_GITHUB_CLIENT_SECRET",
  "ga": {"trackingId": "YOUR_GA_TRACKING_ID"}
}

This file contains the following properties:

• url: Site URL (used for building links)
• GITHUB_CLIENT_ID: Your GITHUB_CLIENT_ID from your OAuth Application
• GITHUB_CLIENT_SECRET: Your GITHUB_CLIENT_SECRET from your OAuth Application
• ga: An object with a trackingId property that has your Google Analytics tracking id. This is optional and if left out will leave out the Google Analytics code.

The second file is db/config.json in the db folder:

{
  "development": {
    "username": "doowb",
    "password": null,
    "database": "octobox_development",
    "host": "127.0.0.1",
    "dialect": "postgres"
  },
  "test": {
    "username": "doowb",
    "password": null,
    "database": "octobox_test",
    "host": "127.0.0.1",
    "dialect": "postgres"
  },
  "production": {
    "use_env_variable": "DATABASE_URL"
  }
}

This file contains the environment based configurations for the PostgreSQL database. Each environment (development, test, production) may have different configuration objects. Each configuration object may have the following properties:

• username: PostgreSQL username
• password: PostgreSQL password
• database: PostgreSQL database (this should match the database created earlier)
• host: Where the database is located
• dialect: "postgres" This should be "postgres" if you're following this Readme. Since this project uses sequelize, you have an option to use another database engine if you'd like.
• use_env_variable: Rather than setting all of the properties above, you may set a connection string on an environment variable and specify this variable here. When deploying to Heroku this is the option that's used and the default environment variable is DATABASE_URL.

Start

Now you can start the Node.js application using the following command:

$ npm start

If there are no errors, you can open the app in a browser at http://localhost:3000 and login through GitHub.

About

Related projects

• assemble: Get the rocks out of your socks! Assemble makes you fast at creating web projects… more | homepage
• express: Fast, unopinionated, minimalist web framework | homepage
• generate: Command line tool and developer framework for scaffolding out new GitHub projects. Generate offers the… more | homepage
• helper-octicon: Template helper for displaying octicon SVGs. Should work with any Handlebars, Lo-Dash, underscore or any… more | homepage
• sequelize: Multi dialect ORM for Node.JS/io.js | homepage
• update: Be scalable! Update is a new, open source developer framework and CLI for automating updates… more | homepage
• verb: Documentation generator for GitHub projects. Verb is extremely powerful, easy to use, and is used… more | homepage

Contributing

Pull requests and stars are always welcome. For bugs and feature requests, please create an issue.

Please read the contributing guide for avice on opening issues, pull requests, and coding standards.

Running tests

Install dev dependencies:

$ npm install -d && npm test

Author

Brian Woodward

• github/doowb
• twitter/doowb

License

Copyright © 2017, Brian Woodward. Released under the AGPL-3.0 license.

---

This file was generated by verb-generate-readme, v0.2.3, on January 08, 2017.