commit time author line
703e1e +11Y
# Installation Instructions
703e1e +11Y
9aa817 +11Y
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.
f74218 +11Y
f74218 +11Y
## Requirements
f74218 +11Y
f74218 +11Y
* **A computer capable of running [PHP 5.3][php] or greater and [git 1.7.X.X or greater][git].**
f74218 +11Y
f74218 +11Y
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.
f74218 +11Y
98c367 +11Y
* **Web server software that supports running PHP**
f74218 +11Y
98c367 +11Y
Numerous pieces of web server software support the use of PHP. Popular choices include:
f74218 +11Y
98c367 +11Y
* [Apache][apache] (Available on Linux, Mac OS, and Windows)
98c367 +11Y
* [Nginx][nginx] (Available on Linux, Windows, probably Mac OS)
98c367 +11Y
* [IIS (Windows)][iis] (Available on Windows)
f74218 +11Y
98c367 +11Y
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).
dd0fc1 +11Y
98c367 +11Y
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).
f74218 +11Y
94a0a0 +11Y
* **OPTIONAL: An SSH server program (if you are doing git-over-SSH synchronization, which is recommended)**
afbd8e +11Y
94a0a0 +11Y
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.
94a0a0 +11Y
94a0a0 +11Y
* [OpenSSH][ssh] is widely supported on Linux, Mac OS, and on Windows.
afbd8e +11Y
384c34 +11Y
* **OPTIONAL: A git GUI client**
548511 +11Y
384c34 +11Y
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.
384c34 +11Y
384c34 +11Y
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:
548511 +11Y
548511 +11Y
* [TortoiseGit][tortoisegit] (for Windows)
548511 +11Y
* [SourceTree][sourcetree] (for MacOS)
548511 +11Y
9b756d +11Y
aa5cb4 +11Y
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.
9b756d +11Y
ca43ad +11Y
*(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 :) )*
9b756d +11Y
9b756d +11Y
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:
9b756d +11Y
9b756d +11Y
* [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.
fd9998 +11Y
* [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.
9b756d +11Y
* [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].
9b756d +11Y
* [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.
9b756d +11Y
9b756d +11Y
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.
9b756d +11Y
9b756d +11Y
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.
9b756d +11Y
9b756d +11Y
[lamp]: http://en.wikipedia.org/wiki/LAMP_(software_bundle)
9b756d +11Y
[wamp]: http://en.wikipedia.org/wiki/WAMP
9b756d +11Y
[lampstack]: http://www.turnkeylinux.org/lampstack
9b756d +11Y
[turnkeyhub]: https://hub.turnkeylinux.org/
9b756d +11Y
[prgrmr]: http://prgrmr.com
9b756d +11Y
[ubuntu]: http://www.ubuntu.com/download/server
9b756d +11Y
[amazonec2]: http://aws.amazon.com/ec2/
9b756d +11Y
[lugs]: http://en.wikipedia.org/wiki/Linux_user_group
9b756d +11Y
f74218 +11Y
## Latest Version
f74218 +11Y
f74218 +11Y
Grab the latest version of Giterary from:
f74218 +11Y
317684 +11Y
* HTTP Download
317684 +11Y
317684 +11Y
TODO: Hosting?
317684 +11Y
317684 +11Y
* git clone
317684 +11Y
317684 +11Y
TODO: Github? Bitbucket?
f74218 +11Y
07fbec +11Y
## Verify PHP versus Your Web Server
f74218 +11Y
07fbec +11Y
Every web server has a directory into which you can put files, and it will serve those files, for better or for worse.
a0e5a2 +11Y
60494e +11Y
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).
07fbec +11Y
07fbec +11Y
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.
a0e5a2 +11Y
a875c3 +11Y
<? phpinfo(); ?>
a0e5a2 +11Y
07fbec +11Y
Afterwards, using your web browser, browse to a URL referencing your host and the *test.php* file, for instance:
07fbec +11Y
7aace3 +11Y
If you plan to be accessing Giterary from only your own machine:
7aace3 +11Y
7aace3 +11Y
http://localhost/test.php
7aace3 +11Y
7aace3 +11Y
If you are installing to a separate server:
7aace3 +11Y
7aace3 +11Y
http://myserver/test.php
7aace3 +11Y
7aace3 +11Y
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.)
7aace3 +11Y
7aace3 +11Y
http://myserver/giterary/test.php
07fbec +11Y
07fbec +11Y
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.
07fbec +11Y
07fbec +11Y
If this is running successfully, then you have a working PHP configuration for your web server. *Good job!*
07fbec +11Y
3b7817 +11Y
## The Easy Way, or The Hard Way (install.sh)
2cb36f +11Y
2cb36f +11Y
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.
2cb36f +11Y
2cb36f +11Y
It is located in the root directory of the source code, called *install.sh*.
2cb36f +11Y
10d54e +11Y
If successful, it sets you up with a Giterary instance with:
10d54e +11Y
10d54e +11Y
* A working git repository
10d54e +11Y
* Reasonable directory structure for git repository, cache, temp, draft, and session information:
10d54e +11Y
10d54e +11Y
/var/lib/giterary
10d54e +11Y
/var/lib/giterary/repos/your_repo_name
10d54e +11Y
/var/lib/giterary/caches/your_repo_name
10d54e +11Y
/var/lib/giterary/temps/your_repo_name
10d54e +11Y
/var/lib/giterary/temps/your_repo_name/drafts
10d54e +11Y
/var/lib/giterary/temps/your_repo_name/sessions
10d54e +11Y
10d54e +11Y
* 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.
10d54e +11Y
* 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).
10d54e +11Y
* Adds your DEFAULT_FILE to the repository with a welcoming message.
10d54e +11Y
10d54e +11Y
This is a fairly straightforward and secure configuration out of the box.
10d54e +11Y
07fbec +11Y
## Verify Git Is Working
07fbec +11Y
103e9e +11Y
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.
384c34 +11Y
384c34 +11Y
git --version
384c34 +11Y
384c34 +11Y
It should print out something like this:
384c34 +11Y
384c34 +11Y
git version 1.7.4.1
384c34 +11Y
384c34 +11Y
Alternatively, if your environment paths are somehow incorrect, you may need to be explicit in the path to your git executable.
384c34 +11Y
384c34 +11Y
To find your explicit path on Linux and MacOSX, you can issue the following command:
384c34 +11Y
384c34 +11Y
which git
384c34 +11Y
384c34 +11Y
...which should return the explicit path. In my case, it returns this:
384c34 +11Y
384c34 +11Y
/usr/local/git/bin/git
384c34 +11Y
c656e0 +11Y
On Windows you may have to search the filesystem for *git.exe* and use the explicit path it returns.
c656e0 +11Y
384c34 +11Y
With your explicit path, run the following command (but with your explicit path):
384c34 +11Y
384c34 +11Y
/usr/local/git/bin/git --version
384c34 +11Y
384c34 +11Y
This should give you version information for your installation of git.
384c34 +11Y
7aace3 +11Y
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.
7aace3 +11Y
384c34 +11Y
Note this path value, as this is the path you will need to use later in the Giterary configuration.
a0e5a2 +11Y
a0e5a2 +11Y
## Create Giterary directories
a0e5a2 +11Y
a0e5a2 +11Y
Giterary needs a few directories to run:
a0e5a2 +11Y
103e9e +11Y
1. **The directory of the git repository.**
103e9e +11Y
103e9e +11Y
This is a directory that will need to be readable/writable, and will store the git repository and its working directory. Recommended locations:
103e9e +11Y
64ce38 +11Y
Linux or MacOSX:
103e9e +11Y
64ce38 +11Y
/var/lib/giterary/repos/NAME_OF_YOUR_REPO
103e9e +11Y
64ce38 +11Y
On Windows:
103e9e +11Y
64ce38 +11Y
c:\programdata\giterary\repos\NAME_OF_YOUR_REPO
103e9e +11Y
64ce38 +11Y
2. **The directory for Giterary to store "cache" information to make the application speedier.**
103e9e +11Y
103e9e +11Y
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:
103e9e +11Y
64ce38 +11Y
Linux or MacOSX:
103e9e +11Y
64ce38 +11Y
/var/lib/giterary/caches/NAME_OF_YOUR_REPO
103e9e +11Y
64ce38 +11Y
On Windows:
103e9e +11Y
64ce38 +11Y
c:\programdata\giterary\caches\NAME_OF_YOUR_REPO
103e9e +11Y
64ce38 +11Y
3. **The directory for Giterary to store "session" information that allows you to be logged in to the application.**
a0e5a2 +11Y
103e9e +11Y
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:
103e9e +11Y
64ce38 +11Y
Linux or MacOSX:
103e9e +11Y
64ce38 +11Y
/var/lib/giterary/sessions/NAME_OF_YOUR_REPO
103e9e +11Y
64ce38 +11Y
On Windows:
103e9e +11Y
64ce38 +11Y
c:\programdata\giterary\sessions\NAME_OF_YOUR_REPO
103e9e +11Y
37f632 +11Y
4. **The directory for Giterary to store "temp" data, like draft files and file comparison inputs.**
37f632 +11Y
37f632 +11Y
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:
37f632 +11Y
37f632 +11Y
Linux or MacOSX:
37f632 +11Y
37f632 +11Y
/var/lib/giterary/temp/NAME_OF_YOUR_REPO
37f632 +11Y
37f632 +11Y
On Windows:
37f632 +11Y
37f632 +11Y
c:\programdata\giterary\temp\NAME_OF_YOUR_REPO
37f632 +11Y
103e9e +11Y
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).
a0e5a2 +11Y
103e9e +11Y
## Oh, the config files...
a0e5a2 +11Y
74d6ad +11Y
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.
65ae54 +11Y
7b04bd +11Y
###### base.php
7b04bd +11Y
7b04bd +11Y
* **base.php**
65ae54 +11Y
74d6ad +11Y
*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*.
65ae54 +11Y
74d6ad +11Y
The following are **required** fields.
65ae54 +11Y
74d6ad +11Y
*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.
65ae54 +11Y
74d6ad +11Y
define('SITE_NAME', "My New Story");
74d6ad +11Y
define('SHORT_NAME', "New Story");
65ae54 +11Y
74d6ad +11Y
The *BASE_URL* is the base HTTP URL that will be used to navigate to your Giterary instance. This is used in link generation.
65ae54 +11Y
74d6ad +11Y
define('BASE_URL',"http://myserver/giterary/");
65ae54 +11Y
ebcce2 +11Y
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).
ebcce2 +11Y
ebcce2 +11Y
define('DEFAULT_FILE', 'Home' );
ebcce2 +11Y
74d6ad +11Y
*SRC_DIR* is the filesystem location of the source files for Giterary.
74d6ad +11Y
74d6ad +11Y
define('SRC_DIR',"/var/lib/wwwroot/giterary/");
74d6ad +11Y
74d6ad +11Y
*GIT_PATH* is the filesystem path to the command line git client on your server.
74d6ad +11Y
74d6ad +11Y
define('GIT_PATH',"/usr/local/bin/git");
74d6ad +11Y
77a588 +11Y
*GIT\_REPO\_DIR* is the path to the readable/writable directory that contains the git repository for this instance of Giterary.
74d6ad +11Y
37f632 +11Y
define('GIT_REPO_DIR',"/var/lib/giterary/repos/NAME_OF_YOUR_REPO/");
74d6ad +11Y
74d6ad +11Y
*CACHE_DIR* is the readable/writable directory for maintaining caches of certain data within Giterary.
74d6ad +11Y
37f632 +11Y
define( 'CACHE_DIR','/var/lib/giterary/caches/NAME_OF_YOUR_REPO/' );
74d6ad +11Y
74d6ad +11Y
*CACHE_ENABLE* is a value of 1 or 0, 1 being that use of the cache is enabled, 0 is that it is disabled.
1e6462 +11Y
74d6ad +11Y
define( 'CACHE_ENABLE', 0 );
74d6ad +11Y
74d6ad +11Y
*TMP_DIR* is the temporary directory for temporary files generated by Giterary. It can be under the same directory as the Giterary cache.
1e6462 +11Y
37f632 +11Y
define('TMP_DIR','/var/lib/giterary/temp/NAME_OF_YOUR_REPO/' );
74d6ad +11Y
74d6ad +11Y
*DRAFT_DIR* is the directory for storing draft files within Giterary. It can be under the directory as the Giterary cache.
1e6462 +11Y
37f632 +11Y
define('DRAFT_DIR','/var/lib/giterary/temp/NAME_OF_YOUR_REPO/' );
74d6ad +11Y
1e6462 +11Y
*SESS_PATH* is the directory for storing cookie information for interacting with your browser.
1e6462 +11Y
37f632 +11Y
define('SESS_PATH', '/var/lib/giterary/sessions/NAME_OF_YOUR_REPO/');
74d6ad +11Y
74d6ad +11Y
The following are **optional** fields.
74d6ad +11Y
341e3e +11Y
*STYLESHEET* and *CSS_DIR* are relative URL references to the default CSS to be used by the Giterary application.
74d6ad +11Y
74d6ad +11Y
define('STYLESHEET', "simpler.css");
74d6ad +11Y
define('CSS_DIR', "css/");
74d6ad +11Y
74d6ad +11Y
The following are variables for configuring cookie information for communicating login session information with your web browser.
74d6ad +11Y
74d6ad +11Y
define('COOKIE_DOMAIN', 'www.YOUR_DOMAIN_HERE.com');
74d6ad +11Y
define('COOKIE_PATH', '/');
74d6ad +11Y
define('COOKIE_EXPR_TIME', 86400);
74d6ad +11Y
define('SESS_NAME', 'GITERARYSESSION');
74d6ad +11Y
7b04bd +11Y
###### permissions.php
7b04bd +11Y
7b04bd +11Y
* **permissions.php** and **permissions.lib.php**
74d6ad +11Y
74d6ad +11Y
*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*.
74d6ad +11Y
74d6ad +11Y
A common, starting instance is "AllPlay", where all users can perform all functions without limit.
74d6ad +11Y
ce0db6 +11Y
<?
74d6ad +11Y
require_once( dirname( __FILE__ ) . '/permissions.lib.php' );
74d6ad +11Y
74d6ad +11Y
$registered_auth_calls = array();
74d6ad +11Y
74d6ad +11Y
register_auth_call( new AllPlay(), "can" );
74d6ad +11Y
ce0db6 +11Y
?>
74d6ad +11Y
74d6ad +11Y
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.
74d6ad +11Y
74d6ad +11Y
ce0db6 +11Y
<?
74d6ad +11Y
require_once( dirname( __FILE__ ) . '/permissions.lib.php' );
74d6ad +11Y
74d6ad +11Y
$registered_auth_calls = array();
74d6ad +11Y
74d6ad +11Y
register_auth_call( new MustBeLoggedIn(), "can" );
74d6ad +11Y
ce0db6 +11Y
?>
74d6ad +11Y
74d6ad +11Y
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.
74d6ad +11Y
ce0db6 +11Y
<?
74d6ad +11Y
require_once( dirname( __FILE__ ) . '/permissions.lib.php' );
74d6ad +11Y
74d6ad +11Y
$registered_auth_calls = array();
74d6ad +11Y
74d6ad +11Y
register_auth_call(
74d6ad +11Y
new SensitiveFiles(
74d6ad +11Y
array(
74d6ad +11Y
"passfile.csv" => array( "jrhoades" )
74d6ad +11Y
)
74d6ad +11Y
),
74d6ad +11Y
"can"
74d6ad +11Y
);
74d6ad +11Y
ce0db6 +11Y
?>
74d6ad +11Y
74d6ad +11Y
7b04bd +11Y
###### auth.php
7b04bd +11Y
7b04bd +11Y
* **auth.php** and **auth.lib.php**
74d6ad +11Y
f87d6a +11Y
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.
f87d6a +11Y
f87d6a +11Y
Currently there are two common configurations, *StaticUserList* and *PasswordFile*.
f87d6a +11Y
f87d6a +11Y
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.
f87d6a +11Y
f87d6a +11Y
<?
f87d6a +11Y
f87d6a +11Y
require_once( dirname( __FILE__ ) . '/auth.lib.php' );
f87d6a +11Y
f87d6a +11Y
$registered_login_calls = array();
f87d6a +11Y
f87d6a +11Y
register_login_call( new StaticUserList(), "validate_login" );
f87d6a +11Y
f87d6a +11Y
?>
f87d6a +11Y
f87d6a +11Y
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.
f87d6a +11Y
f87d6a +11Y
<?
f87d6a +11Y
f87d6a +11Y
require_once( dirname( __FILE__ ) . '/auth.lib.php' );
f87d6a +11Y
f87d6a +11Y
$registered_login_calls = array();
f87d6a +11Y
80c9e8 +11Y
register_login_call(
80c9e8 +11Y
new PasswordFile(
80c9e8 +11Y
'/var/lib/giterary/repos/my_repo/passfile.csv'
80c9e8 +11Y
),
80c9e8 +11Y
"validate_login"
80c9e8 +11Y
);
f87d6a +11Y
f87d6a +11Y
?>
f87d6a +11Y
cdd6ee +11Y
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:
cdd6ee +11Y
cdd6ee +11Y
Username,GitUser,Password
cdd6ee +11Y
jimmy,"Jimmy <jimmy@jimmy.com>",6f1ed002ab5595859014ebf0951522d9
cdd6ee +11Y
cdd6ee +11Y
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.
cdd6ee +11Y
cdd6ee +11Y
**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.
cdd6ee +11Y
6433ec +11Y
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.
cdd6ee +11Y
6433ec +11Y
However, the question becomes how to generate these password hashes. On Linux, the following commands are available:
cdd6ee +11Y
cdd6ee +11Y
md5sum
cdd6ee +11Y
sha256sum
6433ec +11Y
sha512sum
cdd6ee +11Y
cdd6ee +11Y
...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):
cdd6ee +11Y
cdd6ee +11Y
echo -n "blah" | md5sum
cdd6ee +11Y
cdd6ee +11Y
...will return the following:
cdd6ee +11Y
cdd6ee +11Y
6f1ed002ab5595859014ebf0951522d9 -
cdd6ee +11Y
6433ec +11Y
**NOTE**: You **must** include the "-n" portion of the echo command, otherwise echo will emit a newline character, which will invalidate your hash value.
6433ec +11Y
82f6a6 +11Y
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:
cdd6ee +11Y
cdd6ee +11Y
"sha256$8b7df143d91c716ecfa5fc1730022f6b421b05cedee8fd52b1fc65a96030ad52"
cdd6ee +11Y
cdd6ee +11Y
Or, for SHA512:
cdd6ee +11Y
cdd6ee +11Y
"sha512$39ca2b1f97...(long, long result )...1c2fa54b7"
cdd6ee +11Y
5195bb +11Y
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].
cdd6ee +11Y
cdd6ee +11Y
[php.hash]: http://php.net/manual/en/function.hash.php
cdd6ee +11Y
8e2a79 +11Y
7b04bd +11Y
###### dict.php
f87d6a +11Y
7b04bd +11Y
* **dict.php**
6d1e10 +11Y
6d1e10 +11Y
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).
6d1e10 +11Y
6d1e10 +11Y
*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*.
6d1e10 +11Y
6d1e10 +11Y
define( 'DICTIONARY_PATH', '/usr/share/dict/words' );
6d1e10 +11Y
6d1e10 +11Y
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.
6d1e10 +11Y
6d1e10 +11Y
$conjunctions = array(
6d1e10 +11Y
/* ...for, and, not, nor... */
6d1e10 +11Y
);
6d1e10 +11Y
6d1e10 +11Y
# http://en.wikipedia.org/wiki/Most_common_words_in_English
6d1e10 +11Y
$non_counted_words = array(
6d1e10 +11Y
/* ...the, be, to, of... */
6d1e10 +11Y
);
6d1e10 +11Y
6d1e10 +11Y
$past_tense_verbs = array(
6d1e10 +11Y
/* ...was, wasn't, did, didn't... */
6d1e10 +11Y
);
6d1e10 +11Y
6d1e10 +11Y
$present_tense_verbs = array(
6d1e10 +11Y
/* ...is, isn't, am, are... */
6d1e10 +11Y
);
74d6ad +11Y
7b04bd +11Y
###### perf.php
7b04bd +11Y
7b04bd +11Y
* **perf.php**
6d1e10 +11Y
6d1e10 +11Y
A flag for whether to calculate performance stats and include a "performance report" in the HTML comments of every Giterary page. Enabled by default.
6d1e10 +11Y
6d1e10 +11Y
<?
6d1e10 +11Y
6d1e10 +11Y
define( 'PERF_STATS', 1 );
6d1e10 +11Y
6d1e10 +11Y
?>
6d1e10 +11Y
74d6ad +11Y
7b04bd +11Y
* **time.php**
74d6ad +11Y
6d1e10 +11Y
Defines the default timezone to be used when making changes from the Giterary interface.
6d1e10 +11Y
6d1e10 +11Y
<?
6d1e10 +11Y
6d1e10 +11Y
date_default_timezone_set ( 'America/Anchorage' );
6d1e10 +11Y
6d1e10 +11Y
?>
6d1e10 +11Y
7b04bd +11Y
* **conventions.php**
74d6ad +11Y
6d1e10 +11Y
The *conventions.php* file defines the basic "conventional" assumptions Giterary makes when defining things. Examples of conventions are:
6d1e10 +11Y
6d1e10 +11Y
* The suffix used for "dirified" directory names (*dir* by default).
1f4d1a +11Y
0960c9 +11Y
define( 'DIRIFY_SUFFIX', "dir" );
0960c9 +11Y
d741ed +11Y
* Default character encoding for the Giterary instance (*UTF-8* by default).
d741ed +11Y
0960c9 +11Y
define( 'ENCODING', "UTF-8" );
d741ed +11Y
d741ed +11Y
* Regular expressions to determine the valid filename and file path patterns used on the site.
0960c9 +11Y
0960c9 +11Y
$wikiname_pattern = '-_a-zA-Z0-9\.\s';
0960c9 +11Y
0960c9 +11Y
$wikifile_pattern = "@^([$wikiname_pattern]+)(\\/[$wikiname_pattern]+)*$@";
0960c9 +11Y
0960c9 +11Y
$wikilink_pattern = "@(\\\)?\[\[([$wikiname_pattern]+(\\/[$wikiname_pattern]+)*)(\|([\w\s\.\,\\/-]+))?\]\]@";
0960c9 +11Y
0960c9 +11Y
$functionlink_pattern = "@(\\\)?\[\[([a-zA-Z]+):(([^\]|,]+=[^\]|,]+)(,[^\]|,]+=[^\]|,]+)*)?(\|([\w\s\.\,\"/-]+))\]\]@";
0960c9 +11Y
7b04bd +11Y
###### html.php
7b04bd +11Y
7b04bd +11Y
* **html.php**
74d6ad +11Y
6d1e10 +11Y
*html.php* defines parameters for dealing with the HTML generation within Giterary.
6d1e10 +11Y
6d1e10 +11Y
The *$allowed_tags* configuration variable defines which tags are allowed to be used for final rendering within Giterary.
6d1e10 +11Y
6d1e10 +11Y
$allowed_tags = array(
6d1e10 +11Y
/* ...'<p>', '<h>', '<pre>', '<img>', '<table>'... */
6d1e10 +11Y
);
6d1e10 +11Y
9c19e2 +11Y
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.
9c19e2 +11Y
7b04bd +11Y
###### themes.php
7b04bd +11Y
7b04bd +11Y
* **themes.php**
65ae54 +11Y
b10118 +11Y
*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.
e9eae7 +11Y
d324f0 +11Y
*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).
e9eae7 +11Y
e9eae7 +11Y
define('DEFAULT_THEME', 'default');
6d1e10 +11Y
e9eae7 +11Y
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.
e9eae7 +11Y
e9eae7 +11Y
$renderables = array(
e9eae7 +11Y
'default_layout' => 'theme/default/renderable/layout/standard.php',
e9eae7 +11Y
'edit_layout' => 'theme/default/renderable/layout/edit.php',
e9eae7 +11Y
'show_layout' => 'theme/default/renderable/layout/show_layout.php',
e9eae7 +11Y
'note' => 'theme/default/renderable/note.php',
e9eae7 +11Y
'gen_error' => 'theme/default/renderable/gen_error.php',
e9eae7 +11Y
'gen_header' => 'theme/default/renderable/gen_header.php',
e9eae7 +11Y
'gen_history' => 'theme/default/renderable/gen_history.php',
e9eae7 +11Y
/* ... */
e9eae7 +11Y
'not_logged_in' => 'theme/default/renderable/not_logged_in.php',
e9eae7 +11Y
'gen_csv' => 'theme/default/renderable/gen_csv.php'
e9eae7 +11Y
e9eae7 +11Y
);
6d1e10 +11Y
e9eae7 +11Y
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.
e9eae7 +11Y
e9eae7 +11Y
$themes = array(
e9eae7 +11Y
'default' => array(),
e9eae7 +11Y
);
65ae54 +11Y
b10118 +11Y
Note again that editing this file is not required, but we're just providing a description here for documentation purposes.
b10118 +11Y
654013 +11Y
## Initialize your git repository
654013 +11Y
d5639e +11Y
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:
d5639e +11Y
d5639e +11Y
git init
d5639e +11Y
d5639e +11Y
This will initialize an empty directory for you to work with (and creates the "hidden" files that git uses alongside your own).
d5639e +11Y
d5639e +11Y
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.
5b24c2 +11Y
5b24c2 +11Y
git config user.name "Anonymous User"
5b24c2 +11Y
git config user.email "anonymous@anonymous.com"
654013 +11Y
d5639e +11Y
*(Once the Giterary authors figure out how to get around this, we will likely be able to skip this step.)*
d5639e +11Y
ebcce2 +11Y
## That was horrific. Am I done?
ebcce2 +11Y
794ce0 +11Y
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*.
8bf680 +11Y
8bf680 +11Y
http://localhost/giterary/index.php
8bf680 +11Y
8bf680 +11Y
If the page loads, and you're able to save your file successfully, then you've succeeded in installing and configuring Giterary.
ebcce2 +11Y
f4cb44 +11Y
## It didn't work. I have shamed myself and my family.
c2d227 +11Y
a93741 +11Y
*No!* Not at all. We are human, we must err, or, do things which cause error messages.
c2d227 +11Y
a93741 +11Y
As we get more people performing installations we will include "common" errors and hopefully provide reasonable solutions.
794ce0 +11Y
794ce0 +11Y
## Optional Pieces
794ce0 +11Y
8b4c32 +11Y
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."
8b4c32 +11Y
8b4c32 +11Y
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.
8b4c32 +11Y
794ce0 +11Y
### Being able to push/pull from Giterary
794ce0 +11Y
8b4c32 +11Y
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.
8b4c32 +11Y
8b4c32 +11Y
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.
5b24c2 +11Y
5b24c2 +11Y
* [gittutorial][gittutorial], git's own tutorial (admittedly dense).
adf2d8 +11Y
* [git-scm's documentation and videos][git-scm], particularly their ["Distributed Git" section][dist]
adf2d8 +11Y
* [Github's 15 minute tutorial][git-code-school]
5b24c2 +11Y
9d96f3 +11Y
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.
5b24c2 +11Y
5b24c2 +11Y
[gittutorial]: http://www.kernel.org/pub/software/scm/git/docs/gittutorial.html
adf2d8 +11Y
[git-scm]: http://git-scm.com/documentation
adf2d8 +11Y
[git-code-school]: http://try.github.com/levels/1/challenges/1
adf2d8 +11Y
[dist]: http://git-scm.com/book/en/Distributed-Git
b3d41b +11Y
[stackoverflow]: http://stackoverflow.com/
adf2d8 +11Y
9d96f3 +11Y
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.
794ce0 +11Y
d0788d +11Y
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.).
d0788d +11Y
d0788d +11Y
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.
d0788d +11Y
d0788d +11Y
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.
80802f +11Y
794ce0 +11Y
### Post-receive git server hook
794ce0 +11Y
5b24c2 +11Y
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.
5b24c2 +11Y
5b24c2 +11Y
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.
5b24c2 +11Y
5b24c2 +11Y
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.
5b24c2 +11Y
5b24c2 +11Y
Put the following into */path/to/your/repo/.git/hooks/post-receive* to enable this feature:
5b24c2 +11Y
5b24c2 +11Y
#!/bin/bash
5b24c2 +11Y
98caf3 +11Y
echo "Refreshing server's working tree";
5b24c2 +11Y
5b24c2 +11Y
/usr/local/bin/git --git-dir=/path/to/your/repo/.git --work-tree=/path/to/your/repo/ reset --hard;
5b24c2 +11Y
5b24c2 +11Y
exit 0;
5b24c2 +11Y
5b24c2 +11Y
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.
5b24c2 +11Y
5b24c2 +11Y
git config receive.denyCurrentBranch ignore
5b24c2 +11Y
c2d227 +11Y
e9eae7 +11Y
----
f74218 +11Y
f74218 +11Y
[git]: http://git-scm.org/
f74218 +11Y
[php]: http://php.net/
f74218 +11Y
[apache]: http://httpd.apache.org/
f74218 +11Y
[nginx]: http://nginx.org/
dd0fc1 +11Y
[iis]: http://www.iis.net/
94a0a0 +11Y
[turnkey]: http://www.turnkeylinux.org/
548511 +11Y
[ssh]: http://openssh.com
548511 +11Y
[tortoisegit]: http://code.google.com/p/tortoisegit/wiki/Download
55f65f +11Y
[sourcetree]: http://www.sourcetreeapp.com/