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. Many LAMP setups are pre-configured simply for this ("Linux, Apache, MySQL, and PHP").
* [Apache][apache] (Available on Linux, Mac OS, and Windows)
* [Nginx][nginx] (Available on Linux, Windows, probably Mac OS)
* [IIS (Windows)][iis] (Available on Windows)
While installing these HTTP servers you should ensure that the steps taken to enable PHP have been taken before proceeding. Those steps are beyond the scope of this document, but are well documented elsewhere. There are also numerous "appliance" virutal machines available on the web, pre-configured to support your flavor of HTTP server. If you are installing to "the cloud," this may be an easier route than configuring your own HTTP server (though, we would invite you to learn about such things, as they are valuable things to be knowledgeable about).
* [TurnKey Linux][turnkey]
* **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)
## Latest Version
Grab the latest version of Giterary from:
* HTTP Download TODO
* git clone TODO
## 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 you 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!*
## 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
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.
1. **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/");
*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/my_repo/");
*CACHE_DIR* is the readable/writable directory for maintaining caches of certain data within Giterary.
define( 'CACHE_DIR','/var/lib/giterary/caches/my_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/caches/my_repo/temp/' );
*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/caches/my_repo/drafts/' );
*SESS_PATH* is the directory for storing cookie information for interacting with your browser.
define('SESS_PATH', '/var/lib/giterary/caches/my_repo/sessions/');
The following are **optional** fields.
*STYLESHEET* and *CSS_DIR* arare 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');
2. **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"
);
?>
3. **auth.php** and **auth.lib.php**
4. **dict.php**
5. **perf.php**
6. **time.php**
7. **conventions.php**
8. **html.php**
9. **themes.php**
[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/