Local installation on an Ubuntu VM

Original version with thanks to @twhyntie

##Introduction This guide will take you through installing and running Panoptes on a small (~20 GB) Ubuntu-based Virtual Machine (VM). We have used a Xubuntu 14.04 guest VM running on a Windows 7 VirtualBox host (a typical configuration in schools).

To setup your guest VM, please refer to this CERN@school guide.

##Software

###(J)Ruby management with RVM Panoptes is powered by JRuby, a Java implementation of the Ruby programming language. Managing different versions of JRuby (and Ruby, for that matter) is made relatively simple with RVM. We recommend installing RVM following the instructions here.

###Ruby Install Ruby 2.0.0 (patch 195) by typing:

$ rvm install ruby-2.0.0-p195 -- --enable-shared

The --enable-shared option is required by the rice Ruby Gem, which is used by Cellect (see below). Create a new gemset for your Zooniverse work with:

$ rvm use ruby-2.0.0-p195@zooniverse --create

###JRuby Panoptes has been tested against JRuby 1.7.16, and relies on some Ruby 2.0 features, so install it by typing:

$ rvm install jruby-1.7.16 --2.0

##Services You will need to set up the following services on the VM in order for Panoptes to work. Note: this section is incomplete...

###PostgreSQL PostgreSQL is the database system of choice for Panoptes. There's a useful getting started tutorial here, but the basic steps required to install and setup a database for the development Panoptes instance are outlined below.

####Installation To install PostgreSQL 9.3 on your VM, simply type:

$ sudo apt-get install postgresql postgresql-contrib

####Setup a database for Panoptes Enter the PostgreSQL user interface as the postgres user with:

$ psql -d template1 -U postgres

You can then create the panoptes user and the panoptes_development database, before giving the former access to the latter with the following PostgreSQL commands:

template1=# CREATE USER panoptes WITH PASSWORD 'panoptes';
template1=# CREATE DATABASE panoptes_development;
template1=# GRANT ALL PRIVILEGES ON DATABASE panoptes_development to panoptes;

(We will configure Panoptes to use this database later.)

###Apache Zookeeper Zookeeper (from Apache - and otherwise unrelated to Galaxy Zoo!) is a service that manages distributed systems. As Panoptes uses multiple services, you'll need an instance of Zookeeper running to keep everything in check. Below you will find how to install and run Zookeeper on your machine.

####Installation Following the handy instructions here, you can install Zookeeper to your preferred directory $ZK_HOME with:

$ cd $ZK_HOME
$ wget http://mirror.nus.edu.sg/apache/zookeeper/zookeeper-3.4.6/zookeeper-3.4.6.tar.gz
$ tar xvf zookeeper-3.4.6.tar.gz

You may wish to add the environment variable $ZK_HOME to your ~/.bashrc file for convenience.

####Configuration The default configuration provided with Zookeeper should be fine, so create a copy of the sample configuration file called conf/zoo.cfg with:

$ cd $ZK_HOME
$ cp conf/zoo_sample.cfg conf/zoo.cfg

####The Zookeeper service You can start, check the status of, and stop the Zookeeper service (with the default port 2181) with:

$ cd $ZK_HOME
$ bin/zkServer.sh start
JMX enabled by default
Using config: $ZK_HOME/bin/../conf/zoo.cfg
Starting zookeeper ... STARTED
$ bin/zkServer.sh status
JMX enabled by default
Using config: $ZK_HOME/bin/../conf/zoo.cfg
Mode: standalone
$ bin/zkServer.sh stop
JMX enabled by default
Using config: $ZK_HOME/bin/../conf/zoo.cfg
Stopping zookeeper ... STOPPED

(Note: $ZK_HOME will be replaced with the actual path in your output.)

You'll want to start Zookeeper before you try running Panoptes.

###Redis

####Installation Installing Redis is a little more involved, so it's worth looking at the excellent guide here. Don't forget to run make test and sudo make install, as well as the utils/install_server.sh script.

####The Redis server If you've followed the instructions, the Redis server should be running on the default port 6379. You can check this with:

$ sudo service redis_6379 status
[sudo] password for [your username]: 
Redis is running ([the process ID])

###Kafka

####Installation and setup Again, the installation is a little more involved so we recommend following this guide here. Once installed and configured to run with Zookeeper, start the server with:

$ cd $KAFKA_HOME
$ bin/kafka-server-start.sh config/server.properties &

###Cellect

####Getting the code Clone the Cellect code with the following (choose a suitable location for $CELLECT_HOME):

$ cd $CELLECT_HOME
$ git clone https://github.com/zooniverse/Cellect.git

MORE TO FOLLOW

##The Panoptes Application

###Getting the code Choose a suitable location for your Panoptes instance, with the environment variable $PANOPTES_HOME, and clone the repository:

$ cd $PANOPTES_HOME
$ git clone https://github.com/zooniverse/Panoptes.git

Alternatively, you can fork the repository.

###Configuration

The configuration files will need changing to reflect that everything is running locally (on localhost):

• config/cellect.yml: change zookeeper to localhost;
• config/social.yml: no changes required - yet...
• config/aws.yml: An Amazon Web Services (AWS) S3 bucket is required for the subject set. Add your ID, secret key, bucket name and path to the subject set in this configuration file;
• config/kafka.yml: change kafka to localhost;
• config/redis.yml: change redis to localhost;
• config/secrets.yml: no changes required;
• config/sidekiq.yml: no changes required.

###Before running Before you can run Panoptes, you'll need to migrate the database with the following command:

$ rake db:migrate RAILS_ENV=development

###Running Run Panoptes as a Rails app by starting the server:

$ rails s

Then access http://localhost:3000 on your web browser to view the app running. You should see something like the image below:

Original text With thanks to twhyntie

Panoptes running in the web browser.

WHAT'S NEXT?

##Useful links

• The Panoptes GitHub repository;
• The CERN@school guide to setting up a VM;
• VirtualBox;
• The RVM homepage;
• The PostgreSQL homepage;