Blank Box

Blank Box is a pages based knowledge repository concerned with creating a central resource for information that can be referenced easily, and that a team actually wants to engage with. It is structured around a Category > Chapter > Page model, allowing for easy organisation, and has a search feature driven by ElasticSearch so that looking up what you need will be zoom-zoom fast no matter how many pages you add.

Blank Box also offers bookmarking, and optional features such as curation (which hands page approval/resource quality management responsibility to selected users) and badges (listing visual accolades on a user's profile as they are earned for submissions).

How To Use

Contents

1. Before You Start
2. Configuring Homestead
3. Setting Up the Repository
4. Setting Up Local Databases
5. Setting Up ElasticSearch
6. Notes

---

1. Before You Start

If you do not have a vagrant box ready to put this on, it is recommended you install Homestead.

---

2. Configuring Homestead

This is only necessary if using Homestead.

Find your Homestead.yaml located in /C:/Users/YourName/.homestead (for Windows - Mac users fend for yourselves). Then replace the contents with:

---
ip: "192.168.10.10"
memory: 2048
cpus: 1
provider: virtualbox

authorize: ~/.ssh/id_rsa.pub

keys:
    - ~/.ssh/id_rsa

folders:
    - map: C:/Directory/To/Your/Git/Repos
      to: /home/vagrant/sites

sites:
    - map: blank-box.app
      to: /home/vagrant/sites/blank-box/public

databases:
    - blank_box

Replace C:/Directory/To/Your/Git/Repos with the location you plan to clone the Blank Box repo to, eg C:/Sites.

---

3. Setting Up the Repository

Clone the repository to the location you changed above:

git clone git@github.com:hannahtinkler/blank-box.git

From the root of the new directory, install the dependencies:

composer install

npm install

Copy the .env.example from the root into a file called .env

Run the following commands to port configs into the main application:

php artisan vendor:publish

cp .env.example .env

php artisan key:generate

---

4. Setting Up Local Databases

Navigate to the Homestead directory. On Windows, this is located in C:/Users/YourName/Homestead. From here, SSH into the Homestead box:

vagrant ssh

Navigate into the root of the Blank Box directory, eg:

cd sites/blank-box

Migrate the databases and run the seeders:

php artisan migrate

This will create the schema you need and insert the necessary data.

---

5. Setting Up ElasticSearch

Since ElasticSearch is based off Java, you will need install Java 8 on your Vagrant box if you have not already. You can do that by running the following:

sudo add-apt-repository -y ppa:webupd8team/java

sudo apt-get update

sudo apt-get -y install oracle-java8-installer

Agree to the terms when prompted. Don't worry about reading them. You're only signing away your soul. You can verify your install by running the following command:

java -version

Next you need to download and install ElasticSearch. Again, this is mainly a paste job:

wget https://download.elastic.co/elasticsearch/elasticsearch/elasticsearch-2.3.2.deb

sudo dpkg -i elasticsearch-2.3.2.deb

You will also need to configure some of the things. Run the following command:

sudo vim /etc/elasticsearch/elasticsearch.yml

Then change/add the following config values to as below. You will also need to uncomment then (obviously).

node.name: "Blank Box 1"
cluster.name: Cluster1
index.number_of_shards: 1
index.number_of_replicas: 0

Finally, start ElasticSearch and test it by running the following commands:

sudo service elasticsearch start

curl -GET "http://localhost:9200"

Some JSON should be output; if it is and it looks a bit like this, you win:

{
  "name" : "Blank Box 1",
  "cluster_name" : "Cluster1",
  "version" : {
    "number" : "2.3.2",
    "build_hash" : "b9e4a6acad4008027e4038f6abed7f7dba346f94",
    "build_timestamp" : "2016-04-21T16:03:47Z",
    "build_snapshot" : false,
    "lucene_version" : "5.5.0"
  },
  "tagline" : "You Know, for Search"
}

Now that elastic search is prepared to index your content,you can seed your database with the default content:

php artisan db:seed

Final Notes:

You will need to add blank-box.app to your /etc/hosts file in order to access it from the browser.

You will also need to set up an OAuth credentials for the application on the Google API console in order to be able to log in. When prompted what kind of credientials you want to create, select 'OAuth client id' with application type of 'Web application'. Then enter the following details: Name: Blank Box (or whatever you want really) Authorized JavaScript origins: http://blank-box.app Authorized redirect URIs: http://blank-box.app/login/callback

For OAuth to work, you will also need to enable the Google Contacts API and Google+ API from your API console (under Library).