Fetching latest commit…
Cannot retrieve the latest commit at this time.
|Failed to load latest commit information.|
=== 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 firstname.lastname@example.org/gitorious/mainline.git It is very similar as operating over an SSH URL: git clone ssh://email@example.com/~/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