=== UNDERSTANDING GITORIOUS ===

One of the main challenges in Gitorious is its installation process. It is

anything but trivial.

The main piece is a plain vanilla Ruby on Rails web application, and this is

the easiest part.

The purpose of the web front-end is to concentrate all Git projects in an easy 

to manage user interface, which also makes it easy to make clones, send merge 

requests, manage committers and participate through comments in the website 

itself. The user interface also provides a nice visualization of the commit log 

and the source tree. So this is a high quality website for Git project management.

It can be used for any number of Git workflows. It is easier to create a 

Centralized Workflow model, where you have one central Git repository and many 

committers added to it, as well as the Integration Workflow, where you have a 

"mainline" repository. Other developers can clone from it, keep pushing commits 

in their own cloned repositories and once they're done with some feature, they can 

easily send a merge request back to the maintainer of the original mainline.

Take a look at Scott Chacon's explanation on these workflows:

http://www.whygitisbetterthanx.com/#any-workflow

== THE MAIN PIECES ==

For all of this to work, we need more than a front-end web application. There are

backend pieces that we will have to understand and deal with.

I'll make a general explanation of the architecture and then you will find 

specific procedures at:

* doc/recipes/install-centos.txt

* doc/recipes/install-ubuntu.txt

First of all, we need Git installed in the machine. We also need a MySQL database

where the project metadata is stored.

All non-web operations goes through SSH, so we need that installed too. More

than that, Gitorious was kind of inspired by an older project called Gitosis. It

has a clever idea on which there is one local user (usually called "git"). And

every developer from any project use this same user.

That's how you clone a remote repository from what's called your "Push URL":

  git clone git@gitorious.org/gitorious/mainline.git

It is very similar as operating over an SSH URL:

  git clone ssh://git@gitorious.org/~gitorious/mainline.git

And that's exactly what happens. Let's break it down:

* git           - is the 'special' user on the server

* gitorious.org - is the server itself, which needs to have 

* ~             - (tilde) as all Unix users will know, it is the alias for the home 

                  directory, in this case it means "/home/git"

* gitorious     - is the project directory under the home directory of the user git.

                  And the neat thing about this is that every clone of the mainline

                  repository goes under this umbrella directory.

* mainline.git  - is the git repository directory under the project. 

But it would be odd if everybody had permission to login under the same username:

anyone could mess around any project's directories. But the advantage of using SSH is

that it is flexible enough to provide an infrastructure to disallow such a thing.

As a technical detail, whenever you log in either using a normal ssh client or the git

command line, it will read its local .ssh/authorized_keys file. Inside it you will find

something similar to this:

  ### START KEY 1 ###

  command="gitorious akitaonrails",no-port-forwarding,no-X11-forwarding,

  no-agent-forwarding,no-pty ssh-rsa AAAAB...MCay0w== fabioakita@MacHal9001.local

  ### END KEY 1 ###

I cut off the big ssh key for brevity. So whenever you try to login through ssh, you will

have your public key transferred and compared to those in this file. This allow for the

SSH server to find your entry and therefore, which 'command' it should run. Then it will

execute 'gitorious [your_login]' and it will check with the website's data if you do or

do not have access to the project you want to (it passes the SSH arguments through to the

gitorious command as well). That's how it determines your identity and your permissions

regardless of everybody logging into the same local user account (ex. 'git').

You do all this through what's called a "Push URL", meaning that you only use it if you 

have permission to push your changes back to the repository (you're either the owner of 

the project or someone added you as a committer).

If you don't have push permission, you will only see a "Public Clone URL" that resembles 

this one:

  git clone git://gitorious.org/gitorious/gitorious.git

Instead of going through the SSH port, this one will connect to port 9418 of your server

(if you have firewalls up, be sure to have this port open).

If there is an open port, there is a daemons. The Gitorious project also give your what's

called the "git-daemon" which keeps running and listening to this port. It allows for 

the git command to clone the remote repository but not to push stuff back. This is good 

for read-only scenarios.

== ASYNCHRONOUS OPERATIONS ==

Whenever you:

* Add a new ssh key to your account

* Create a new project

* Clone an existing project

Nothing will happen. Until you manually run the script/task_notifier task inside your

website's directory. This script will see what's queued and run those tasks. It would

be too time consuming to stay inside a Controller's Action, so they were correctly

detached into an asynchronous process that will run when it can. Usually people set it

up as a Cron Job.

These kinds of actions triggers notifications to the users, so e-mails are sent through

plain vanilla sendmail as well.

So that covers the main pieces.

== OPTIONAL PIECES ==

The website provides a search functionality that depends on Sphinx and the Ultrasphinx

plugin for Rails. It is way smarter than a plain "LIKE" operator from SQL, but it 

requires a living daemon and a task.

So you will need another daemon for Sphinx and you will also need another Cron Job

for Ultrasphinx's task that rebuilds the index to reflect recent changes. Those are

optional if you don't want or don't need the search functionality.

There is another task called script/graph_generator which depends on the Gruff and

RMagick rubygems as well as the native ImageMagick library. It generates a nice

graph on commits frequency through the days. When you run it, it will generate a

PNG static image. If you don't run it, Gitorious will simply ignore it. It is very

cumbersome to make this component work correctly.

== PRIVATE MODE ==

The original intent of Gitorious is for an open source public website where every 

project is open to the public.

But as Gitorious itself is an open source project, people can choose to have their

own installation (as you will, as you're reading this documentation).

Sometimes people want to install their own private Gitorious in a VPS server. And 

then host their company's internal projects, for example. But in this scenario, their

private Gitorious would be publicly exposed to the Internet.

Now you can change your config/gitorious.yml file and change this:

  public_mode: false

The default mode is 'true', which make your Gitorious public. But if you want your

own private server, change it to 'false'.

In private mode, the 'Register' page is also locked and you need to create a super

user manually. Do this in the server running the task 'script/create_admin'. It will

ask for the administrator's email and password and will create it for you.

== SUMMARY ==

So, the shopping list goes like this:

* install several operating system components, including Git and SSH

* set up a 'git' (or whatever other login name) local account

* install the Gitorious Rails-based website

* set up the git-daemon

* set up the sphinx daemon

* set up the task_notifier cron job

* set up the ultrasphinx cron job

* set up the graph_generator cron job