# Installation Instructions

The following are general guidelines to getting Giterary running. These
instructions are biased towards the Linux side of things, but there is no reason
an enterprising individual couldn't get them running on Mac OS or Windows. They
also assume you have a basic working knowledge of the components of the
Internet, how to configure your systems to run "services" or "daemons," or a
certain quantity of patience and a willingness to Google something if you don't
understand it.

## Requirements

*  **A computer capable of running [PHP 5.3][php] or greater and [git 1.7.X.X or
greater][git].**

   These are widely available from many different Linux distribution packaging
   mechanisms (Debian and Ubuntu's apt-get, Centos and Fedora's yum, etc.) Binary
   packages are also available from their respective sites for all operating
   systems.

*   **Web server software that supports running PHP**

    Numerous pieces of web server software support the use of PHP. Popular
    choices include:

    * [Apache][apache] (Available on Linux, Mac OS, and Windows)
    * [Nginx][nginx] (Available on Linux, Windows, probably Mac OS)
    * [IIS (Windows)][iis] (Available on Windows)

    You may not feel up to installing and configuring these yourself. I know:
    I've had those days, where the weight of the world dictates that you won't look
    at another config file. But don't despair: these are so popular and ubiquitous
    that many people sell services, construct virtual machines appliances, and make
    a ton of tools so that you can get off the ground with a web server and PHP
    easily. So much so that they've even given these types of setups a clever
    acronym: [LAMP][lamp] or [WAMP][wamp]  ("Linux/Windows, Apache, MySQL, and PHP",
    minus the MySQL in our case). Do a couple of Google queries for "LAMP server" or
    "LAMP appliance" and you'll see what I mean: tons of step by step guides,
    virtual machine appliances, and hosting services, all waiting for your time and
    patience (or money, potentially).

    Unfortunately, those steps are beyond the scope of this document. We provide
    verification steps later here to make sure things are working, but getting to
    that point has been documented and solved much better by smarter people than the
    author of this document. No matter if you're installing on your daily-driver
    laptop, or a fully-redundant cloud server, I would invite you to learn about
    such things, as they are valuable things to be knowledgeable about, will teach
    you about the underpinnings of the Internet at large, and makes you a blast at
    parties). 

*  **OPTIONAL: An SSH server program (if you are doing git-over-SSH
synchronization, which is recommended)**

   git has the ability to push and pull from multiple sources, and using
   multiple network protocols. The most reliable and conventionally accepted
   appears to be SSH, which provides encryption as well as authentication. If you
   plan on "synchronizing" another computer with your Giterary instance, you will
   want to have an SSH server or git-capable equivalent to provide access to your
   Giterary repository.

    * [OpenSSH][ssh] is widely supported on Linux, Mac OS, and on Windows.

*  **OPTIONAL: A git GUI client**

    You will need the command line git client installed. However, there are a
    number of GUI clients (graphical user interfaces) that are a lot more friendly
    to human eyes.

    It is highly recommended that you keep a git client handy, just in case you
    don't like how Giterary does something, or that you have to do something
    Giterary doesn't.  These tools let you interact with your Giterary repository in
    lots of nice ways. They also provide a more forgiving git learning tool than the
    command line, man pages, and frustrated Google searches. I recommend the
    following:

    * [TortoiseGit][tortoisegit] (for Windows)
    * [SourceTree][sourcetree] (for MacOS)


These requirements may seem out of control, but they're not so bad, and in fact,
are pretty common among web applications (though hidden by the fact that you
only need a web browser to use them successfully). I can give a few
recommendations, pointers, and places to get started with hosting your own
Giterary instance.

*(I'll always advocate running your own servers before "going to the cloud." It
means that you own your hardware and your data, and you have to worry slightly
less about how your novel will fare after the zombie apocalypse. However,
starting from scratch, the learning curve for "rolling your own" is admittedly
steep and having other services available to jumpstart your progress is too
useful to leave it unmentioned. Plus, setting up and maintaining highly
redundant, highly available server hardware is expensive and time consuming, and
some people just don't value geek cred as much as I do :) )*

Here are a few things to look into if you're a) installing your own server, b)
exploring options for your own server, or c) curious about how to become a hit
at parties:

* [Ubuntu][ubuntu] happens to be my favorite "I don't care about the details, I
just want to use something" flavor of Linux. Its package system tends to have
everything, and if you're wanting/needing it, it has a well-supported desktop
environment, and a large user community.
* [Amazon's EC2 (Elastic Compute Cloud)][amazonec2] is a cheap and quick way to
get hosted in the "cloud," and they can bill at cents per hour, if you're
wanting to be economical.
* [TurnKey Linux][turnkey] is a collection of tested, pre-configured virtual
machine appliances that can get you set up and running with what you want in
just a few minutes. They have a [pre-configured LAMP stack][lampstack], and
partner with Amazon's EC2 to provide cheap virtual machine hosting on their
[Turnkey Hub service][turnkeyhub].
* [prgrmr][prgrmr]'s tagline is *"We don't assume you are stupid."* Which is
pretty great. However, they aren't for the faint of heart. In fact, you may or
may not have to send in a photo of your neckbeard for verification before you
can be sold anything.

Another option is to call up or email that computer-savvy person you know, or,
make friends with one you don't. Honestly: we live for this stuff. Memorize the
following phrase (phonetically, if you have to): "I want to set up an Apache
server with git and SSH, and have it sync with my laptop." If you work in a
business that has an Information Technology department, you can walk into the
middle of their work area and shout that above the server noise. Any geek worth
their salt will venture out of their cube to ask further questions. Best case:
they set it up for you. Worst case: you learn who to talk to next time something
is really broken.

There are also [Linux User Groups][lugs] in pretty much every major city, state,
and university campus. They like to be able to serve their community, and
installing something like Giterary is an easy and straightforward task for them.

[lamp]: http://en.wikipedia.org/wiki/LAMP_(software_bundle)
[wamp]: http://en.wikipedia.org/wiki/WAMP
[lampstack]: http://www.turnkeylinux.org/lampstack
[turnkeyhub]: https://hub.turnkeylinux.org/
[prgrmr]: http://prgrmr.com
[ubuntu]: http://www.ubuntu.com/download/server
[amazonec2]: http://aws.amazon.com/ec2/
[lugs]: http://en.wikipedia.org/wiki/Linux_user_group

## Latest Version

Grab the latest version of Giterary from:

*   HTTP Download

    TODO: Hosting?

*   git clone

    TODO: Github? Bitbucket?

## Verify PHP versus Your Web Server

Every web server has a directory into which you can put files, and it will serve
those files, for better or for worse.

Much of the configuration headache for web servers is getting the names, access
rules, and pointers to the right directories into place. We leave it up to the
reader to maintain their own security, but take heed when we say that the intent
of a web server is to *put things on the Internet*. Be sure that you check to
see if things are exposed that should not be (for instance, if your Giterary
instance is exposed to whoever happens to be sitting next to your at the airport
terminal).

Most important to establishing this "hosted directory" is ensuring that PHP is
configured correctly. Within your "hosted" directory, place a file called
*test.php*, which has only these contents.

    <? phpinfo(); ?>

Afterwards, using your web browser, browse to a URL referencing your host and
the *test.php* file, for instance:

If you plan to be accessing Giterary from only your own machine:

    http://localhost/test.php

If you are installing to a separate server:

    http://myserver/test.php

If you are installing Giterary to a place other than the URL's "root" (referring
to the "/giterary/" portion of the URL not being at the "root" of the path after
the *myserver* host specification.)

    http://myserver/giterary/test.php

This page should contain an output from the *phpinfo* function that lists all of
the compilation, configuration, and dependency information for your PHP
installation. It will be purple.

If this is running successfully, then you have a working PHP configuration for
your web server. *Good job!*

## The Easy Way, or The Hard Way (install.sh)

There is Linux install script that tries to walk you through your various
configuration necessities (names, paths, usernames, passwords, etc.). It isn't
particularly sophisticated, and isn't particularly platform agnostic (has only
been ran on Ubuntu), but it's a lot easier than wading through all this mess.

It is located in the root directory of the source code, called *install.sh*.

If successful, it sets you up with a Giterary instance with:

*   A working git repository
*   Reasonable directory structure for git repository, cache, temp, draft, and
session information:
    
        /var/lib/giterary
        /var/lib/giterary/repos/your_repo_name
        /var/lib/giterary/caches/your_repo_name
        /var/lib/giterary/temps/your_repo_name
        /var/lib/giterary/temps/your_repo_name/drafts
        /var/lib/giterary/temps/your_repo_name/sessions

*   Initializes your git repository, sets an anonymous user for the repository
(required from operating from a web application like Giterary), and other small
git repository configurations.    
*   A "passfile.csv" configuration, where a special CSV is added to Giterary
that contains your username, git user information, and hashed password (pointed
to with the *config/auth.php* config file). It is then configured as a
"sensitive" file that only only be edited by the username your enter (with the
*config/permissions.php* config file).
*   Adds your DEFAULT_FILE to the repository with a welcoming message.

This is a fairly straightforward and secure configuration out of the box.

## Verify Git Is Working

From your operating system's command line (any terminal in Linux, Terminal in
MacOS, the *cmd* MS-DOS prompt in Windows), attempt to execute the following
command.

    git --version

It should print out something like this:

    git version 1.7.4.1

Alternatively, if your environment paths are somehow incorrect, you may need to
be explicit in the path to your git executable.

To find your explicit path on Linux and MacOSX, you can issue the following
command:

    which git

...which should return the explicit path. In my case, it returns this:

    /usr/local/git/bin/git

On Windows you may have to search the filesystem for *git.exe* and use the
explicit path it returns.

With your explicit path, run the following command (but with your explicit
path):

    /usr/local/git/bin/git --version

This should give you version information for your installation of git.

Verify the security configuration on your system for your git client. **It needs
to be executable by the user that is running your web server**. This is critical
for Giterary to function.

Note this path value, as this is the path you will need to use later in the
Giterary configuration.

## Create Giterary directories

Giterary needs a few directories to run:

1.  **The directory of the git repository.**

    This is a directory that will need to be readable/writable, and will store
    the git repository and its working directory. Recommended locations:

    Linux or MacOSX:

        /var/lib/giterary/repos/NAME_OF_YOUR_REPO

    On Windows:

        c:\programdata\giterary\repos\NAME_OF_YOUR_REPO

2.  **The directory for Giterary to store "cache" information to make the
application speedier.**

    This is a directory that will need to be readable/writable, and will store
    the Giterary cache files to help make browsing via Giterary speedier.
    Recommended locations:

    Linux or MacOSX:

        /var/lib/giterary/caches/NAME_OF_YOUR_REPO

    On Windows:

        c:\programdata\giterary\caches\NAME_OF_YOUR_REPO

3.  **The directory for Giterary to store "session" information that allows you
to be logged in to the application.**

    This is a directory that will need to be readable/writable, and will store
    the PHP session files that allow you to log in. Recommended locations:

    Linux or MacOSX:

        /var/lib/giterary/sessions/NAME_OF_YOUR_REPO

    On Windows:

        c:\programdata\giterary\sessions\NAME_OF_YOUR_REPO

4.  **The directory for Giterary to store "temp" data, like draft files and file
comparison inputs.**

    This is a directory that will need to be readable/writable, and will store
    the PHP session files that allow you to log in. Recommended locations:

    Linux or MacOSX:

        /var/lib/giterary/temp/NAME_OF_YOUR_REPO

    On Windows:

        c:\programdata\giterary\temp\NAME_OF_YOUR_REPO

These locations are relatively arbitrary, and you could potentially combine the
cache and session directories into one (but never the repository directory, that
must remain apart from everything).

## Oh, the config files...

There are a series of configuration files necessary to getting Giterary up and
running. They are all PHP files, and can be edited using any text editor. They
are located within the *include/config/* directory of the Giterary source. They
are situated such that one could have multiple instances of Giterary, but with
different *include/config* directories, and the instances would be able to run
simultaneously.

###### base.php

*  **base.php**

    *base.php* is the largest configuration file, as it contains references to
    the most basic portions of Giterary that are necessary to run ("Where is my
    repository?", "What is my name?", etc.). Below is a line-by-line description of
    the configuration values within *base.php*.

    The following are **required** fields.

    *SITE_NAME* and *SHORT_NAME* are display values for showing on the Giterary
    interface which instance of Giterary is running. This is where you put a name
    for the "title" of Giterary.

        define('SITE_NAME', "My New Story");
        define('SHORT_NAME', "New Story");

    The *BASE_URL* is the base HTTP URL that will be used to navigate to your
    Giterary instance. This is used in link generation.

        define('BASE_URL',"http://myserver/giterary/");

    The *DEFAULT_FILE* gives the name of the first file to be created within
    your Giterary instance, and the default file to be displayed when no file is
    specified (likely the first file that will be displayed with accessing your
    Giterary instance).

        define('DEFAULT_FILE', 'Home' );

    *SRC_DIR* is the filesystem location of the source files for Giterary.

        define('SRC_DIR',"/var/lib/wwwroot/giterary/");

    *GIT_PATH* is the filesystem path to the command line git client on your
    server.

        define('GIT_PATH',"/usr/local/bin/git");

    *GIT\_REPO\_DIR* is the path to the readable/writable directory that
    contains the git repository for this instance of Giterary.

        define('GIT_REPO_DIR',"/var/lib/giterary/repos/NAME_OF_YOUR_REPO/");

    *CACHE_DIR* is the readable/writable directory for maintaining caches of
    certain data within Giterary.

        define( 'CACHE_DIR','/var/lib/giterary/caches/NAME_OF_YOUR_REPO/' );

    *CACHE_ENABLE* is a value of 1 or 0, 1 being that use of the cache is
    enabled, 0 is that it is disabled.

        define( 'CACHE_ENABLE',   0 );

    *TMP_DIR* is the temporary directory for temporary files generated by
    Giterary. It can be under the same directory as the Giterary cache.

        define('TMP_DIR','/var/lib/giterary/temp/NAME_OF_YOUR_REPO/' );

    *DRAFT_DIR* is the directory for storing draft files within Giterary. It can
    be under the directory as the Giterary cache.

        define('DRAFT_DIR','/var/lib/giterary/temp/NAME_OF_YOUR_REPO/' );

    *SESS_PATH* is the directory for storing cookie information for interacting
    with your browser.

        define('SESS_PATH', '/var/lib/giterary/sessions/NAME_OF_YOUR_REPO/');

    The following are **optional** fields.
       
    *STYLESHEET* and *CSS_DIR* are relative URL references to the default CSS to
    be used by the Giterary application.

        define('STYLESHEET', "simpler.css");
        define('CSS_DIR', "css/");

    The following are variables for configuring cookie information for
    communicating login session information with your web browser.

        define('COOKIE_DOMAIN', 'www.YOUR_DOMAIN_HERE.com');
        define('COOKIE_PATH', '/');
        define('COOKIE_EXPR_TIME', 86400);
        define('SESS_NAME', 'GITERARYSESSION');

###### permissions.php

*  **permissions.php** and **permissions.lib.php**

    *permissions.php* is the configuration file for how users are permitted to
    perform certain actions within Giterary. *permissions.lib.php* is a set of
    common permission settings, defined as named classes, and usable as objects to
    be "registered" within *permissions.php*.

    A common, starting instance is "AllPlay", where all users can perform all
    functions without limit.

        <?
        require_once( dirname( __FILE__ ) . '/permissions.lib.php' );
        
        $registered_auth_calls = array();
        
        register_auth_call( new AllPlay(), "can" );

        ?>

    For a more "private" Giterary experience, the MustBeLoggedIn class defines
    that in order to view any portions of the site, you must have successfully
    logged in to the site.


        <?
        require_once( dirname( __FILE__ ) . '/permissions.lib.php' );
        
        $registered_auth_calls = array();
        
        register_auth_call( new MustBeLoggedIn(), "can" );
        
        ?>

    For a "mixed" Giterary experience, SensitiveFiles allows you to define
    certain files which are considered "sensitive," in that you must belong to a set
    of defined users otherwise you can neither read nor write to the files.

        <?
        require_once( dirname( __FILE__ ) . '/permissions.lib.php' );
        
        $registered_auth_calls = array();
        
        register_auth_call( 
            new SensitiveFiles( 
                array(
                    "passfile.csv"  => array( "jrhoades" )
                )
            ),
            "can"
        );

        ?>


###### auth.php

*  **auth.php** and **auth.lib.php**

    Similar to *permissions.php* and *permissions.lib.php*, *auth.php* and
    *auth.lib.php* provide the configuration and the common case library for
    defining *how people log in to Giterary*. Essentially, how the user list is
    determined, and how passwords will be stored.

    Currently there are two common configurations, *StaticUserList* and
    *PasswordFile*.

    In a *StaticUserList* configuration, a class is defined in *auth.lib.php*
    that describes the user list, their properties, and their passwords. Editing the
    StaticUserList class in *auth.lib.php* is necessary for this configuration. This
    method is not necessarily recommended, though, is common due to the ease of
    maintenance.

        <?

        require_once( dirname( __FILE__ ) . '/auth.lib.php' );
        
        $registered_login_calls = array();
        
        register_login_call( new StaticUserList(), "validate_login" );

        ?>

    In a *PasswordFile* configuration, a CSV is referenced that defines
    username, user git properties, and a
    [hashed](http://en.wikipedia.org/wiki/Hash_function#Hashing_with_cryptographic_hash_functions)
    password. This file can exist within your a repository (and be editable from the
    Giterary interface), or be outside of your repository and be edited manually, it
    is up to your security requirements. A *permissions.lib.php* class is defined
    specifically for this type of file called "SensitiveFiles," which requires
    specific user credentials to be able to edit a file.

        <?

        require_once( dirname( __FILE__ ) . '/auth.lib.php' );
        
        $registered_login_calls = array();
        
        register_login_call( 
            new PasswordFile( 
                '/var/lib/giterary/repos/my_repo/passfile.csv'
            ), 
            "validate_login" 
        );

        ?>

    A "passfile" is a CSV formatted file that contains names, emails, and
    password information for users to log in with. An example file might look like
    this:

        Username,GitUser,Password
        jimmy,"Jimmy <jimmy@jimmy.com>",6f1ed002ab5595859014ebf0951522d9

    The file is a CSV, and as such, can be edited using the Giterary interface
    (and will render as a table when viewing). However, you don't want just anyone
    on your Giterary instance viewing and/or editing your password file. In these
    cases, you want to use *permissions.php* to flag your *passfile.csv* as
    "Sensitive," and only viewable/editable by a small set of users.

    **WARNING:** Just because the Giterary interface restricts access to such a
    file doesn't mean that people with access to your git repository won't. Anyone
    who can read information from git can read your passfile. While efforts are
    taken to make sure your passwords are obfuscated, it's important to know that
    git itself doesn't do "security." If you want to use a passfile, but **not**
    have the file be located in your git repository, simple move your passfile to
    somewhere that isn't in your git repository. You will have to edit this file by
    hand.

    Finally, you might be asking yourself, "Who wants to enter in
    '6f1ed002ab5595859014ebf0951522d9' as a password?" The answer is: *absolutely
    nobody*. Nor do they. This is a "hash" of your password, a mathematical
    algorithm performed on your password to make it difficult to guess its original
    contents. When you log in to Giterary, the password you enter is ran through
    this same algorithm, and if the two "hashed" results are equal, you have
    successfully entered your password and you are allowed to log in. It's a clean
    and useful way of storing passwords without having to store them at all.

    However, the question becomes how to generate these password hashes. On
    Linux, the following commands are available:

        md5sum
        sha256sum
        sha512sum

    ...And others, which let you pipe in arbitrary text (ie, your password) and
    return a hashed result. For example, for the password "blah" (which is a
    terrible password which you should never use):

        echo -n "blah" | md5sum

    ...will return the following:

        6f1ed002ab5595859014ebf0951522d9  -

    **NOTE**: You **must** include the "-n" portion of the echo command,
    otherwise echo will emit a newline character, which will invalidate your hash
    value.

    The 6f1...22d9 value is what you paste into your Giterary *passfile.csv*.
    However, Giterary assumes that unless you specify your hashing algorithm, it
    will just use the MD5 algorithm. This is fine if you only ever generated hashes
    with MD5, but some people want a more cryptographically hardened hash value. If
    you want to do a SHA256 hash, you would have to put in the following:

       
        "sha256$8b7df143d91c716ecfa5fc1730022f6b421b05cedee8fd52b1fc65a96030ad52"

    Or, for SHA512:

        "sha512$39ca2b1f97...(long, long result )...1c2fa54b7"

    The important part being the "xxxx$" prefix. Anything before the "$" in the
    password fields is treated as a hashing *hint,* to suggest to Giterary which
    hashing algorithm is used. The "xxxx" hash hint can be anything that is
    supported by [PHP's hash() function][php.hash].

[php.hash]: http://php.net/manual/en/function.hash.php


###### dict.php

*   **dict.php**
    
    The *dict.php* file defines the path to the "dictionary" file, as well as
    sets of configurable groupings of words for calculating document metrics (the
    "Statistics" page).

    *DICTIONARY_PATH* is the path to a file that consists of 1 word per line. On
    Linux, this path is normally */usr/share/dict/words*.

        define( 'DICTIONARY_PATH', '/usr/share/dict/words' );

    The following are the lists that define the groupings for which words are to
    be considered conjunctions, "non-counted" words (common words you don't want
    counted as "words" for your stats), past tense verbs, and present tense verbs.
        
        $conjunctions = array(
            /* ...for, and, not, nor... */
        );
        
        # http://en.wikipedia.org/wiki/Most_common_words_in_English
        $non_counted_words = array(
            /* ...the, be, to, of... */
        );
        
        $past_tense_verbs = array(
            /* ...was, wasn't, did, didn't... */
        );
        
        $present_tense_verbs = array(
            /* ...is, isn't, am, are... */
        );

###### perf.php

*   **perf.php**
    
    A flag for whether to calculate performance stats and include a "performance
    report" in the HTML comments of every Giterary page. Enabled by default.

        <?
    
        define( 'PERF_STATS', 1 );

        ?>


*   **time.php**

    Defines the default timezone to be used when making changes from the
    Giterary interface.

        <?
    
        date_default_timezone_set ( 'America/Anchorage' );

        ?>

*   **conventions.php**

    The *conventions.php* file defines the basic "conventional" assumptions
    Giterary makes when defining things. Examples of conventions are:

    *   The suffix used for "dirified" directory names (*dir* by default).

            define( 'DIRIFY_SUFFIX', "dir" );
            
    *   Default character encoding for the Giterary instance (*UTF-8* by
    default).

            define( 'ENCODING', "UTF-8" );

    *   Regular expressions to determine the valid filename and file path
    patterns used on the site.
            
            $wikiname_pattern = '-_a-zA-Z0-9\.\s';
            
            $wikifile_pattern =
            "@^([$wikiname_pattern]+)(\\/[$wikiname_pattern]+)*$@";
            
            $wikilink_pattern =
            "@(\\\)?\[\[([$wikiname_pattern]+(\\/[$wikiname_pattern]+)*)(\|([\w\s\.\,\\/-]+))?\]\]@";
            
            $functionlink_pattern =
            "@(\\\)?\[\[([a-zA-Z]+):(([^\]|,]+=[^\]|,]+)(,[^\]|,]+=[^\]|,]+)*)?(\|([\w\s\.\,\"/-]+))\]\]@";

###### html.php

*   **html.php**

    *html.php* defines parameters for dealing with the HTML generation within
    Giterary.

    The *$allowed_tags* configuration variable defines which tags are allowed to
    be used for final rendering within Giterary.

        $allowed_tags = array(
            /* ...'<p>', '<h>', '<pre>', '<img>', '<table>'... */
        );

    The default list provided with Giterary is a good subset of HTML which
    provides a wide range of HTML dipslay elements while avoiding potential security
    risks by disallowing the inclusion of Javascript from a page. You, however, may
    want to change this at some point, which is entirely up to you and your security
    requirements. However, this is by no means recommended, and likely will be more
    of a pain to manage than the functionality gained by allowing such features to
    be embedded within documents. Proceed at your own risk.

###### themes.php

*   **themes.php**

    *themes.php* defines the names and paths responsible for rendering the
    various pieces of Giterary. This file is not necessary to edit in an initial
    configuration, but is important if you want to add your own elements as
    "overrides" to the default theme.
   
    *DEFAULT_THEME* is the name of the "default" theme to be used for your
    Giterary instance. This theme must be the name of a array key within the
    *$themes* configuration variable later on (and is by default).

        define('DEFAULT_THEME', 'default');
    
    The *$renderables* array is a list of name-to-path associations for
    'well-known' renderable files, responsible for rendering anything from page
    layouts to reusable widgets or error messages withing Giterary.

        $renderables = array(
            'default_layout'        => 
            'theme/default/renderable/layout/standard.php',
            'edit_layout'           => 
            'theme/default/renderable/layout/edit.php',
            'show_layout'           => 
            'theme/default/renderable/layout/show_layout.php',
            'note'                  =>  'theme/default/renderable/note.php',
            'gen_error'             => 
            'theme/default/renderable/gen_error.php',
            'gen_header'            => 
            'theme/default/renderable/gen_header.php',
            'gen_history'           => 
            'theme/default/renderable/gen_history.php',
            /* ... */
            'not_logged_in'         => 
            'theme/default/renderable/not_logged_in.php',
            'gen_csv'               =>  'theme/default/renderable/gen_csv.php'
        
        );

    The *$themes* array defines as the keys the names of available themes, and
    as the values of those keys, arrays that describe "overrides" of the
    *$renderables* definitions for the named renderables. This allows a theme author
    to make as much use of the default theme as possible, and only define their
    theme as "exceptions" to the default theme as necessary.

        $themes = array(
            'default'   =>  array(),
        );

    Note again that editing this file is not required, but we're just providing
    a description here for documentation purposes.

## Initialize your git repository

Your git repository needs to be "primed," so to speak, before being used by
Giterary. First off, within your repository directory (perhaps
*/var/lib/giterary/repos/your_repo*), do the following command:

    git init 

This will initialize an empty directory for you to work with (and creates the
"hidden" files that git uses alongside your own).

You also need to inform git "who you are," though, this isn't really your name,
as the Giterary application provides your committing information for you.
However, git still squawks when this is unavailable. To silence this, we set a
temporary, "anonymous" user for the repository. The name doesn't particularly
matter, nor does the email address have to be valid.

    git config user.name "Anonymous User"
    git config user.email "anonymous@anonymous.com"

*(Once the Giterary authors figure out how to get around this, we will likely be
able to skip this step.)*

## That was horrific. Am I done?

Well, I think so. At least the Giterary part anyway. You should browse to your
Giterary instance with your web browser, loading up *index.php* to see if it
displays the editing screen for the file indicated by the file name configured
with *DEFAULT_FILE* in *base.php*.

    http://localhost/giterary/index.php

If the page loads, and you're able to save your file successfully, then you've
succeeded in installing and configuring Giterary.

## It didn't work. I have shamed myself and my family.

*No!* Not at all. We are human, we must err, or, do things which cause error
messages.

As we get more people performing installations we will include "common" errors
and hopefully provide reasonable solutions.

## Optional Pieces

I say "optional," but really I mean "very cool, but if it's already 2am and
you've got stuff to do in the morning, it's alright if you come back later."

The following are the *cool things* around which Giterary was based: being able
to use your own favorite editing tools, and being able to synchronize from any
source, and in any direction.

### Being able to push/pull from Giterary

I can't recommend enough being able to push and pull from a setup external to
the one running your Giterary instance. This is bread and butter of why you
would use git for something like this in the first place. Unfortunately, unless
you've worked with a version control system before, or have written programs
collaboratively before, it's unlikely that you've been a part of this kind of
workflow.

The first part of being able to push/pull using git is probably to learn more
about git itself. There are a ton of sources out there to learn how to use Git.

* [gittutorial][gittutorial], git's own tutorial (admittedly dense).
* [git-scm's documentation and videos][git-scm], particularly their
["Distributed Git" section][dist]
* [Github's 15 minute tutorial][git-code-school]

Honestly, I learned git by way of Googling, man pages, and more furious
Googling. The resources are out there. [Stackoverflow][stackoverflow] is rife
with questions on git and its usage, and usually has great answers for some of
the more subtle use cases around git. They may not be obvious, and the verbs are
sometimes a little odd, but there are some amazing things you can do with git.
Pushing and pulling is just the start.

[gittutorial]: http://www.kernel.org/pub/software/scm/git/docs/gittutorial.html
[git-scm]: http://git-scm.com/documentation
[git-code-school]: http://try.github.com/levels/1/challenges/1
[dist]: http://git-scm.com/book/en/Distributed-Git
[stackoverflow]: http://stackoverflow.com/

What you first want to be able to do is use a git client to be able to *clone*
your Giterary repository, and use it as one of its "origins." From there, you
can see your Giterary files as they truly exist: in files and folders, named as
close as could get to how they're represented in Giterary.

From there, you can open any file in your git repository working directory in
your favorite text editor. You may or may not have the live-preview of Markdown,
or whichever file format you're editing, but you also have a suite of tools
available to you that are difficult or otherwise impossible to do from a web
interface (multiple selections, column edits, search and replace, pattern
recognition, intelligent spellchecking, etc.).

Save the file, and then use your git client to "commit." This is an important
step in the git workflow. Committing to your repository informs git that "Yes,
indeed, I intended to make those changes, and I think I'm ready to save these."
Certain git clients smooth this over, informing you of changes and automatically
adding them to your commit, which saves a bit of time. However, "true" git
considers your working directory to be just that: *a work in progress*. It may
be that you aren't done yet, but you may have *portions* of your work you want
to commit. Or, you can stage your changes and swap out your entire working
directory to focus on something else entirely. git, like Giterary, tries to help
you with the hard stuff, but also tries to get out of your way when you just
want to work.

After committing, you can "push" back to your Giterary origin. Depending on your
Giterary setup (and the presence of your *post-receive git server hook* (as
described later), you should see your updates reflected in the Giterary
interface. If not, be sure that you clear the cache of the edited documents in
question.

### Post-receive git server hook

git gives you the ability to push and pull from whatever repository you like. A
recommended setup with Giterary is to synchronize a copy of your Giterary
repository to a separate computer (your daily driver laptop, etc.), and
synchronize via SSH.

This creates a problem, however. Potentially, you can push to your Giterary
server repository, and while your push may succeed, the files in the working
directory on the server may be out of sync.

To solve this, we use a feature of git called "hooks." In particular, there is a
hook called the *post-receive* hook, which allows you to perform arbitrary user
action on the server after successfully receiving your commits.

Put the following into */path/to/your/repo/.git/hooks/post-receive* to enable
this feature:

    #!/bin/bash

    echo "Refreshing server's working tree";

    /usr/local/bin/git --git-dir=/path/to/your/repo/.git
    --work-tree=/path/to/your/repo/ reset --hard;

    exit 0;

Additionally, git takes issue with pushing into non-bare repositories. While
normally this would be for good reason, Giterary needs to be able to push into a
non-bare repository in order to synchronize its files for display on the
Giterary interface.

    git config receive.denyCurrentBranch ignore


----

[git]: http://git-scm.org/
[php]: http://php.net/
[apache]: http://httpd.apache.org/
[nginx]: http://nginx.org/
[iis]: http://www.iis.net/
[turnkey]: http://www.turnkeylinux.org/
[ssh]: http://openssh.com
[tortoisegit]: http://code.google.com/p/tortoisegit/wiki/Download
[sourcetree]: http://www.sourcetreeapp.com/