README

Gitorious.org
=============

Contributing
============

Please see HACKING


License
=======

Please see the LICENSE file


Further documentation
=====================
Also see the files in the doc/ folder, they contain further detailed information
about setting up the application for specific linux distributions such as 
CenOS and Ubuntu/Debian


Installation to a production environment -- a partial walkthrough.
==================================================================

Make ready
==========

You may want to make separate directories, away from everything, to hold the
site code and the git repository respectively.  In production, you'll be setting
up a special user account too, but don't worry about that yet.

For this intro we're going to use, as examples,

* /www/gitorious           -- directory for the website code
* /gitorious/repositories  -- root directory for the git repositories
* a MySQL database on localhost at port 3306 with a _mysql_ user 'gitorious'
* eventually, a system account named 'gitslave'

All of these can be adjusted to suit: specifically, dirs within your home
directory are fine, and (though MySQL has the best development coverage), the
website code should be free of mysql-isms/quirks.

Prerequisites
=============

First of all, **we assume you have a working Ruby on Rails installation on
your machine**. The Rails project has several resources about getting up and
running with Rails, have a look at [getting started on
rubyonrails.org](http://rubyonrails.org/download). Please ensure you're able
to create a Rails project that uses your database of choice; this guide
assumes your machine is ready to run Rails.

Gitorious itself runs on either Ruby 1.8 or 1.9. Gitorious.org itself uses
Ruby 1.9 and we recommend you do the same.


Dependencies
============

First, install each of these Libraries/applications:

* Git                   (http://git-scm.org)
* Sphinx                (http://sphinxsearch.com/)
* MySQL                 (or whatever)
* ImageMagick           (need version >= 6.3.0)
* aspell (optional)

An ActiveMessaging (http://code.google.com/p/activemessaging/wiki/Installation) compatible queue
server. Gitorious.org runs ActiveMQ and STOMP, stompserver might be a nice
flyweight alternative for your needs


Getting the code
================

Next, get the gitorious code itself:

  # mkdir /www/gitorious ;# or another location of your choice
  # cd    /www/gitorious
  # git clone git://gitorious.org/gitorious/mainline.git gitorious

Now you need edit a couple of configuration files.

config/database.yml
------------------

This file contains settings for the databases used for Gitorious. The
Gitorious distribution provides a sample config file - database.sample.yml -
that you could copy to config/database.yml.

Gitorious should be database agnostic, so feel free to use your database of
choice. Gitorious.org uses MySQL, but there shouldn't be any MySQL specific
code in Gitorious, so use whatever you're most comfortable with.

config/gitorious.yml
--------------------

This file holds Gitorious specific configuration for each Rails environment.
There's a sample file in config/gitorious.sample.yml that describes what each
instruction means. Do make sure you have a section for each Rails environment,
especially if you're upgrading an existing Gitorious installation.

* Create a directory to hold project files
 
  # sudo mkdir  /gitorious/repositories
  
* Add the path to this directory under repository_base_path in gitorious.yml
* Make a long, complicated string. You can run "apg -m 64", or if you lack 'apg'
    `dd if=/dev/random count=1 | md5sum` ,
  and put that on the 'cookie_secret' line (replacing the 'ssssht').


config/broker.yml
-----------------

This file contains information about the Message Queing system used in your
Gitorious installation. There's a section about this further down in this
document, but as a starting point you can use the supplied sample file in
config/broker.yml.example (cp config/broker.yml.example config/broker.yml)

Install the gems required by Gitorious
======================================

Next, you need to install a couple of gems:

  * chronic
  * daemons
  * diff-lcs
  * echoe
  * fastthread
  * geoip
  * highline
  * hoe
  * mime-types
  * oauth
  * rack >= 1.0.0
  * rake
  * rdiscount >= 1.3.1.1
  * RedCloth
  * rmagick
  * ruby-hmac
  * ruby-openid
  * ruby-yadis
  * stomp >= 1.1

Most of these can be installed using 
    $ [sudo] rake gems:install


Create your database
====================

It is now time for creating the Gitorious database. 

  rake db:create:all
  
will create an empty database for you.


Migrate your database
=====================

Now that you have a database, it's time to add the database schema

  rake db:migrate
  
will take care of this for you


Run the tests
=============

Running all the tests will ensure your Gitorious installation is correctly set
up. It takes less than a minute to run all the tests, and gives confidence
that the code is working as intended.

There is at the time being one gem that's required to run the tests, so start
out with

  [sudo] rake gems:install RAILS_ENV=test
  
to make sure the test specific gems are installed. Then run the entire test
suite:

  rake test
  
Once all the tests pass, you're almost ready.

Messaging server
================

Gitorious uses the ActiveMessaging plugin, which supports a range of different
messaging platforms, for sending demanding tasks for asynchronous processing.
In order to these events to be processed, you need to run a messaging server
when running Gitorious.

A pretty reliable solution is to use Apache's ActiveMQ messaging queue system,
located at http://activemq.apache.org/ . Download a version for you operating
system, unpack, and follow the instructions to get running. On Unix-like
systems, this is as easy as unpacking the tarball, going into it and running

  bin/activemq
  
This will start the ActiveMQ server in a default setup, probably pretty well
suited for development purposes. The ActiveMessaging plugin needs to know how
to contact your MQ server, so it needs a config/broker.yml file. The Gitorious
distribution provides an example (again, the defaults should work in a
development environment). Just copy the config/broker.yml.example to
config/broker.yml and start your server.

The messages are sent to the server, in order to "consume" the messages, there
is a script in scripts/poller that will run all registered "processors" (found
in app/processors) that consume messages. In order to have eg. creation of
repositories done automatically run

  script/poller start
  
and the script will be started and daemonized.

You're free to use other messaging protocols than the default Stomp protocol,
which is required in config/environment.rb. The ActiveMessaging website
(http://code.google.com/p/activemessaging/wiki/ActiveMessaging) has more
information about how to set this up.


Get Sphinx going
================

    $ env RAILS_ENV=production rake ultrasphinx:configure
    $ env RAILS_ENV=production rake ultrasphinx:index
    $ env RAILS_ENV=production rake ultrasphinx:daemon:start
    
This sequence of commands will configure, index the database and start the
sphinx daemon
  

Tweak environment
=================

* If you haven't set up your mailer, production mode will fail on login. Set
    config.action_mailer.delivery_method = :test
  for immediate gratification.



Start the server
================

Now that you have all the components running, it's time to try Gitorious on
your local machine:

  ruby script/server    (for Mongrel/Webrick)
  thin start            (for Thin)

Remember the values you put for gitorious_host and gitorious_port in
config/gitorious.yml? Go to http://<gitorious_host>:<gitorious_port> to see
the main page of your local Gitorious. You are now officially up and running,
congratulations!

Production setup
================

In a production environment, you'll want to automate as much as possible. We
use Capistrano for deploying to gitorious.org, and use custom Capistrano
recipes for starting and stopping the various tasks in Gitorious.

The doc/recipies directory contains instructions for setting up init scripts
for these tasks for various platforms. Please consult these, and feel free to
contribute your own!

Sphinx
------

The sphinx daemon needs to be running in order for full text search to work.

Git-daemon
----------

For cloning over the Git protocol, Gitorious includes a custom git daemon
found in script/git-daemon. 

script/poller
-------------

The script/poller script needs to be kept running. 

Web/application server
----------------------

While Mongrel/thin is great for trying out Gitorious on a local install, in a
production environment you'll probably want something a little more robust.
Most Rails folks use Passenger with Apache or Nginx these days, Gitorious will
play happily in such an environment. 

Support for pushing via SSH
===========================

In order for people to be able to push to your repositories, you need an SSH
daemon running. You'll also need a system user account that's used for git
connections through SSH. Consult the recipies in doc/recipies for instructions
on how to set this up. Until you've done this, the web frontend will work, but
users won't be able to push their changes.

Button up
=========

* In production, you'll want to have a limited-privileges user to run the git
  processes, just as you do for your webserver

* Make the tree invisible to any other non-root user; make the tree read-only
  by that user; but grant write access to the /tmp and /public/cache
  directories.

* Consider setting up the standard (lighttpd|nginx|apache) 
  frontend <=> mongrel backend if you see traffic (or configure 
  mod_passenger for apache2).


More Help
=========

* Consult the mailinglist (http://groups.google.com/group/gitorious) or drop 
  by #gitorious on irc.freenode.net if you have questions.

Gotchas
=======

Gitorious will add a 'forced command' to your ~/.ssh/authorized_keys file for
the target host: if you start finding ssh oddities suspect this first.  Don't
log out until you've ensured you can still log in remotely.