Installing Grebe

Instructions as of July 30, 2014.

Documenting the steps, which will lead to additional programming changes to make it simpler. These instructions include creating a subdomain, Nginx server block, and setting up MySql. Some of this info may be split out into another file.

DNS

With the hosting provider, add DNS information, if necessary.

Create a CNAME record if installing the code under a subdomain.
grebe CNAME @

May have to wait a while before DNS updates in order to use the new subdomain website.

Nginx

Log onto remote server.

Change to user root or use sudo ahead of each command. https://help.ubuntu.com/community/RootSudo

Change directory to web server config area. This example uses the Nginx web server, and it assumes that FastCGI has been installed.
cd /etc/nginx

Need to create a server block config file to support Grebe. http://wiki.nginx.org/ServerBlockExample

"VirtualHost" is an Apache term. Nginx does not have Virtual hosts, it has "Server Blocks" that use the server_name and listen directives to bind to tcp sockets.

This is an example of using Grebe under a subdomain.
cd sites-available
vim grebe.yourdomain.com

add the following lines and save the file:

########
# GREBE
########
server {
        listen   80;

        server_name grebe.yourdomain.com;

        location ~ ^/(css/|javascript/|images/) {
            root /home/grebe/Grebe/root;
            access_log off;
          expires max;
        }

        location /api/v1 {
             root /home/grebe/Grebe/root/api/v1;
             index grebeapi.pl;
             rewrite  ^/(.*)$ /grebeapi.pl?query=$1 break;
             fastcgi_pass  127.0.0.1:8999;
             fastcgi_index grebeapi.pl;
             fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
             include fastcgi_params;
        }

        location / {
            root /home/grebe/Grebe/root;
            index grebe.pl;
            rewrite  ^/(.*)$ /grebe.pl?query=$1 break;
            fastcgi_pass  127.0.0.1:8999;
            fastcgi_index grebe.pl;
            fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
            include fastcgi_params;
        }
}

Create a link to the new Nginx server block file.
ln -s /etc/nginx/sites-available/grebe.yourdomain.com /etc/nginx/sites-enabled/

Restart Nginx.
/etc/init.d/nginx restart

Create a home directory for Grebe.
mkdir /home/grebe

Change to Grebe directory.
cd /home/grebe

Create directories that will host markup and HTML template files that represent the posts created. These directories exist outside of document root, but they are used by the Grebe code.
mkdir posts
mkdir markup

Within the /home/grebe directory, download or copy over the gzipped tar file that contains the Grebe code, and unpack it. Example file: @Grebe-29Jul2014.tar.gz@ * unpack in two steps: @gunzip Grebe-29Jul2014.tar.gz@ @tar xvf Grebe29Jul2014.tar@ or unpack in one step: @tar zxvf Grebe29Jul2014.tar.gz@ * The unpacking creates a directory called @Grebe@.

• Change ownership of all contents under the Grebe directory to the owner (username) and group that Nginx operates under. ** @chown - R owner:group Grebe@

• While in @/home/grebe@ change directory to @Grebe@. ** @cd Grebe@

• For curiosity sake, show a listing of all files and subdirectories under Grebe: ** @ls -lR@

• The directory structure under Grebe: * lib API Client Config CPAN * Algorithm HTML JSON REST Text URI Escape XML YAML JRS * nginx root api v1 css images javascript splitscreen sql t tmpl * yaml

• While at @/home/grebe/Grebe@, change to the web root directory. ** @cd root@

• Edit the small file @grebe.pl@. Here is the entire file. Ensure of the proper directory structures after the @lib@ commands.

#!/usr/bin/perl -wT
use strict;
$|++;
use lib '/home/grebe/Grebe/lib';
use lib '/home/grebe/Grebe/lib/CPAN';
use Client::Dispatch;
Client::Dispatch::execute();

• While in @/home/grebe/Grebe/root@, change directory to the version one API directory. Since we're under the web root directory for the Nginx web server, this directory is part of the API URL. ** @cd api/v1@

• Edit the small file @grebeapi.pl@. Here is the entire file. Ensure of the proper directory structures after the @lib@ commands.

#!/usr/bin/perl -wT
use strict;
$|++;
use lib '/home/grebe/Grebe/lib';
use lib '/home/grebe/Grebe/lib/CPAN';
use API::DispatchAPI;
API::DispatchAPI::execute();

• Change to the directory that contains the database files. ** @cd /home/grebe/Grebe/sql@

• This assumes that MySQL is installed.

• Create a new database and database user for Grebe. If planning to use an existing database, then skip these steps.

• Enter this command to get into the mysql command line interface: (it will ask for the root password) ** @mysql -uroot -p@

• At the @mysql>@ prompt, enter the following commands, one at a time: * @create database grebe;@ create user 'grebe'@'localhost' identified by 'set_your_password_here'; grant all privileges on grebe. to 'grebe'@'localhost'; * @flush privileges;@ * @quit;@

• Create the Grebe database tables. * @mysql ugrebe -pyourpassword -D grebe < grebeusers.sql@ @mysql ugrebe -pyourpassword -D grebe < grebeposts.sql@ @mysql ugrebe -pyourpassword -D grebe < grebetags.sql@ * @mysql ugrebe -pyourpassword -D grebe < grebesessionids.sql@

• Change directory to the location of the Config module. ** @cd /home/grebe/Grebe/lib/Config@

• Edit @Config.pm@ and make the appropriate directory location change for the variable @$yml_file@ which points to the location of the Yaml configuration file. ** @my $yml_file = "/home/grebe/Grebe/yaml/grebe.yml";@

• Change directory to the Yaml config file location. * @cd /home/grebe/Grebe/yaml@ For testing, enable debug mode. ** @debug_mode: 1@

• Edit the file @grebe.yml@ and make the appropriate changes.

• If @read_template: 1@, then the following files need linked from the @Grebe/tmpl@ directory to the @posts@ directory. * @ln -s /home/grebe/Grebe/tmpl/header.tmpl /home/grebe/posts@ @ln -s /home/grebe/Grebe/tmpl/inc_headernav.tmpl /home/grebe/posts@ * @ln -s /home/grebe/Grebe/tmpl/footer.tmpl /home/grebe/posts@

• Open web browser and enter the following URL: ** @http://grebe.yourname.com@

• The site or blog app should load, displaying the default image header and other links.

• Create a user account: ** @http://grebe.yourname.com/signup@

• Login: ** @http://grebe.yourname.com/login@

To-do

• provide info for using MailGun to send e-mails for creating accounts and for using the no-password login feature.