Skip to content

Latest commit

 

History

History
279 lines (176 loc) · 10.7 KB

INSTALLATION.md

File metadata and controls

279 lines (176 loc) · 10.7 KB
Raw

Octobox Installation and Configuration Guide

The Octobox team hosts a shared instance of Octobox at octobox.io, but perhaps you're looking to host your own or get yourself set up to contribute to Octobox. Fantastic! There are a number of install options available to you.

Before you begin, remember that web notifications must be enabled in your GitHub settings for Octobox to work.

Installation

Configuration

Installation

Deployment to Heroku

You can host your own instance of Octobox using Heroku.

Deploy

Heroku will ask you to provide OAuth client ID and secret, which you can create on GitHub. When creating the OAuth application, make sure you enable the notifications scope on it (you will also need the read:org scope if you enable restricted access). For more help with setting up an OAuth application on GitHub, see below.

Local installation

First things first, you'll need to install Ruby 2.4.2. I recommend using the excellent rbenv, and ruby-build:

brew install rbenv ruby-build
rbenv install 2.4.2
rbenv global 2.4.2

Next, you'll need to make sure that you have PostgreSQL installed. This can be done easily on OSX using Homebrew or by using http://postgresapp.com. 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

Now, let's install the gems from the Gemfile ("Gems" are synonymous with libraries in other languages):

gem install bundler && rbenv rehash
bundle install

Once all the gems are installed, we'll need to create the databases and tables. Rails makes this easy through the use of "Rake" tasks:

bundle exec rake db:create db:migrate

Now go and register a new GitHub OAuth Application, your development configuration should look something like this:

screen shot 2016-12-18 at 21 54 35

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

Once you've created your application you can then then add the following to your .env:

GITHUB_CLIENT_ID=yourclientidhere
GITHUB_CLIENT_SECRET=yourclientsecrethere

Finally you can boot the rails app:

rails s

Using Docker

Using Docker Compose

You can use Docker to run Octobox in development.

First, install Docker. If you've got run macOS or Windows, Docker for Mac/Windows makes this really easy.

If you have Windows Home Edition, you'll need to download and run Docker Toolbox.

Second, download the docker-compose.yml file from here

Then, run:

GITHUB_CLIENT_ID=yourclientid GITHUB_CLIENT_SECRET=yourclientsecret docker-compose up --build

Octobox will be running on http://localhost:3000.

Note: You can add GITHUB_CLIENT_ID and GITHUB_CLIENT_SECRET to a .env file instead of supplying them directly on the command-line.

Note: If you want to help with the development of this project you should clone the code, and then run:

GITHUB_CLIENT_ID=yourclientid GITHUB_CLIENT_SECRET=yourclientsecret docker-compose -f docker-compose-dev.yml up --build

Production environment

First, Create a network interface

docker network create octobox-network

Second, download and run postgres instance

docker run -d --network octobox-network --name=database.service.octobox.internal -e POSTGRES_PASSWORD=development -v pg_data:/var/lib/postgresql/data postgres:9.6-alpine

Note: you should name your database instance database.service.octobox.internal so that octobox container can connect to it.

Then, run the following command to download the latest docker image and start octobox in the background.

GITHUB_CLIENT_ID=yourclientid GITHUB_CLIENT_SECRET=yourclientsecret docker run -d --network octobox-network --name=octobox -e RAILS_ENV=development -e GITHUB_CLIENT_ID=$GITHUB_CLIENT_ID -e GITHUB_CLIENT_SECRET=$GITHUB_CLIENT_SECRET -e OCTOBOX_DATABASE_PASSWORD=development -e OCTOBOX_DATABASE_NAME=postgres -e OCTOBOX_DATABASE_USER=postgres -e OCTOBOX_DATABASE_HOST=database.service.octobox.internal  -p 3000:3000 octoboxio/octobox:latest

Octobox will be running on http://localhost:3000.

Upgrading docker image:

  1. Pull the latest image using the command docker pull octoboxio/octobox:latest or docker-compose pull if you are using docker-compose.
  2. Restart your running container using the command docker restart octobox or docker-compose restart if you are using docker-compose.

Configuration

Allowing periodic notification refreshes

Note: This is not enabled on the hosted version (octobox.io).

You may allow users to set an auto-refresh interval that will cause a periodic sync and page reload when they are viewing notifications. To enable this simply set the environment variable MINIMUM_REFRESH_INTERVAL to any integer above 0. MINIMUM_REFRESH_INTERVAL is the lowest number of minutes between auto-syncs that the server will allow.

When enabled, user settings pages will have an 'Notification Refresh Interval' option. This can be set to any value above MINIMUM_REFRESH_INTERVAL.

Scheduling server-side notification syncs

Note: This is not enabled on the hosted version (octobox.io).

Now that you've set all to go you can configure the app to sync the notifications automatically, there is a rake task that will do this for every user

rake tasks:sync_notifications

You will need to configure this to run automatically

Heroku

Create a Heroku Scheduler

heroku addons:create scheduler:standard

Visit the Heroku Scheduler resource and add a new job to run rake tasks:sync_notifications daily

Cronjob

Run crontab -e

Add the following

@daily cd octobox_path && /usr/local/bin/rake RAILS_ENV=production tasks:sync_notifications

To find the full path for your rake executable, run which rake

Running Octobox for GitHub Enterprise

In order to setup Octobox for your GitHub Enterprise instance all you need you do is add your enterprise domain to the .env file / deployed environment.

Example:

GITHUB_DOMAIN=https://github.foobar.com

And that's it ✨

Using Personal Access Tokens

Octobox can optionally allow you to set a personal access token to use when querying for notifications. This must be enabled at the server level. In order to enable it, add the environment variable PERSONAL_ACCESS_TOKENS_ENABLED to the .env file / deployed environment.

Example:

PERSONAL_ACCESS_TOKENS_ENABLED=1

Once that is set, users can set a personal access token on the Settings page (found on the user drop-down menu).

Limiting Access

You can restrict access to your Octobox instance, and only allow members or a GitHub organization or team. To limit access set the environment variable RESTRICTED_ACCESS_ENABLED=1 then set either GITHUB_ORGANIZATION_ID=<org_id_number> GITHUB_TEAM_ID=<team_id_number>.

You can get an organization's id with this curl command: curl https://api.github.com/orgs/<org_name>

To get a team's id: curl https://api.github.com/orgs/<org_name>/teams. You must be authenticated with access to the org. This will show you a list of the org's teams. Find your team on the list and copy its id

Make sure you add the read:org scope if you have customized the scope at all.

Customizing the Scopes on GitHub

You can customize the scopes required for Octobox to work by modifying the GITHUB_SCOPE environment variable. By default notifications is enabled, unless you also limit access, in which case the default is notifications, read:org. These are required for the application to function correctly.

Customizing Source Link for Modified Code

If you have modified the Octobox code in any way, in order to comply with the AGPLv3 license, you must link to the modified source. You can do this by setting the SOURCE_REPO environment variable to the url of a GitHub repo with the modified source. For instance, if you run this from a fork in the 'NotOctobox' org, you would set SOURCE_REPO=https://github.com/NotOctobox/octobox.

Adding a custom initializer

If you have some need to run custom Ruby code or wish to configure Octobox directly on application load, you may add a file named custom.rb in config/initializers. This file is gitignored. Example:

# config/initializers/custom.rb

Octobox.config do |c|
  c.personal_access_tokens_enabled = true
end

Downloading subjects

Experimental feature for downloading extra information about the subject of each notification, namely:

  • Author for Issues, Pull Requests, Commit Comments and Releases
  • State (open/closed/merged) for Issues, Pull Requests

To enable this feature set the following environment variable:

FETCH_SUBJECT=true

If you want this feature to work for private repositories, you'll need to Customize the Scopes on GitHub adding repo scope to allow Octobox to get subject information for private issues and pull requests.

Google Analytics

To enable Google analytics tracking set the following environment variable:

GA_ANALYTICS_ID=UA-XXXXXX-XX