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.

=== Dependencies

First, install each of these Libraries/applications:

* Git                   (http://git-scm.org)
* Oniguruma C library   (http://www.geocities.jp/kosako3/oniguruma/)
* Sphinx                (http://sphinxsearch.com/)
* MySQL                 (or whatever)
* ImageMagick           (need version >= 6.3.0)
* libyadis-ruby
* aspell (optional)

Next, get the gitorious code itself:

  # mkdir /www/gitorious
  # cd    /www/gitorious
  # git clone git://gitorious.org/gitorious/repositories/mainline.git gitorious

Install each of these Ruby libraries/bindings/gems:

* mysql
* RedCloth      (http://redcloth.org/)
* mime-types    (http://rubyforge.org/projects/mime-types)
* oniguruma     (http://rubyforge.org/projects/oniguruma)
* textpow       (http://rubyforge.org/projects/textpow)
* chronic       (http://rubyforge.org/projects/chronic)
* rmagick       (http://rubyforge.org/projects/rmagick)
* geoip
* ultrasphinx
* rmagick       (in ubuntu I had to sudo apt-get install librmagick-ruby librmagick-ruby-doc)
* ruby-openid   
* ruby-iconv

  # gem install mysql RedCloth mime-types oniguruma textpow \
      chronic rmagick geoip ultrasphinx ruby-openid 

=== Database

First we need a database.  Use the mysql command line app, or phpMyAdmin, or
whatever to create first a user.  Referring to
http://www-css.fnal.gov/dsg/external/freeware/mysqlAdmin.html:

  # mysql -p  -u root -h localhost
  CREATE USER 'git'@'localhost' IDENTIFIED BY 'awesome_password';
  GRANT ALL PRIVILEGES ON `git\_%` . * TO 'git'@'localhost';
  FLUSH PRIVILEGES;
  CREATE DATABASE `git_dev`  DEFAULT CHARACTER SET utf8 COLLATE utf8_bin;
  CREATE DATABASE `git_test` DEFAULT CHARACTER SET utf8 COLLATE utf8_bin;
  CREATE DATABASE `git_prod` DEFAULT CHARACTER SET utf8 COLLATE utf8_bin;

If you haven't set a password for the root user, now's a good time for that, too.

---

Edit database.yml to reflect your local database connection.  This is a standard
Ruby on Rails config file, not specific to gitorious -- if you have questions
here they're answered on the web, or consult the rails IRC channel.  (One hint:
NO TABS AT ALL in a .yml file.)  Our example:

development: 
  adapter:      mysql
  username:     git
  password:     awesome_password
  host:         localhost
  database:     git_dev

# The 'test' database will be erased and re-generated from your development
# database when you run 'rake'.  Must be different than the others!!
test:
  adapter:      mysql
  username:     git
  password:     awesome_password
  host:         localhost
  database:     git_test

production:
  adapter:      mysql
  username:     git
  password:     awesome_password
  host:         localhost
  database:     git_prod

---

Use rake to create the databases, migrate each, and run the tests:

rake db:create:all
for RAILS_ENV in development test production ; do
  rake db:migrate
done
rake test

FTW!

=== Gitorious config
  
* Copy the config/gitorious.sample.yml file to config/gitorious.yml

* Create a directory to hold project files
 
  # sudo mkdir  /gitorious/repositories
  
* 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').

* Here's an example gitorious.yml (omitting comments) for local testing:

  cookie_secret: 26ee61bc4d6aa9870ab48d118a55e6ebcd11011dd6b61aa33536c024853c48d4e7c3d672aa57859
  repository_base_path:         "/gitorious/repositories"
  extra_html_head_data:
  system_message:
  gitorious_client_port:        3000
  gitorious_client_host:        localhost
  gitorious_host:               localhost       # gitorious.org
  gitorious_user:               gitslave
  

=== Get Sphinx going
for RAILS_ENV in development test production ; do
  RAILS_ENV=$RAILS_ENV rake ultrasphinx:configure
  RAILS_ENV=$RAILS_ENV rake ultrasphinx:index
done
RAILS_ENV=production rake ultrasphinx:daemon:start &

=== Tweak environment

* In environment.rb, uncomment config.action_controller.session -- choose a new
  session key string and generate your own secret key using something like
    (uptime; date) |sha1sum

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

  
=== Run the server

From the gitorious directory,

# ./script/server

# RAILS_ENV=production ./script/server

It should start up on port 3000, listening only to local connections.  Ue "ssh
-L 3000:127.0.0.1:3000 -N you@yourbox.com" for testing.

You can now visit the site, sign up with your OpenID, put in your ssh key, and
poke around!  Once you get bored, make a test repository, wonder why nothing is
there yet, and then....

=== Hand-start the task_performer 

Key adoption, repo generation and other tasks are handled by the
'task_performer' script, which must be run periodically or on demand.
Run the script/task_performer and let it create the repository for you.

  # ./script/task_performer

   
4. Get your git on!

Push something to that repository (cd to a git repository with commits and do
"git push path/to/the/bare/repository/you/just/created master").  The actual
(bare) repos live in repository_base_path/#{project.slug}/#{repository.name}.git
Ex: the fubar project's mainline fork sits in a directory called
  
    /gitorious/repositories/fubar/mainline/fubar.git

This will be a 'bare' git repo -- you won't see files in it.

=== 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.


=== More Help

* Consult the mailinglist (http://groups.google.com/group/gitorious) or drop in
  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.