Merge pull request #2188 from riyad/update-installation-docs

Update installation docs

3 files changed, 227 insertions, 172 deletions

diff --git a/doc/install/databases.md b/doc/install/databases.md
index 1a6f739ecdc..92011647f11 100644
--- a/doc/install/databases.md
+++ b/doc/install/databases.md
@@ -1,47 +1,63 @@
-# Databases:
+# Setup Database
 
-GitLab use MySQL as default database but you are free to use PostgreSQL.
+GitLab supports the following databases:
+
+* MySQL (preferred)
+* PostgreSQL
 
 
 ## MySQL
 
+    # Install the database packages
     sudo apt-get install -y mysql-server mysql-client libmysqlclient-dev
 
+    # Install only the necessary gems
+    sudo -u gitlab -H bundle install --deployment --without development test postgres 
+
     # Login to MySQL
     $ mysql -u root -p
 
+    # Create a user for GitLab. (change $password to a real password)
+    mysql> CREATE USER 'gitlab'@'localhost' IDENTIFIED BY '$password';
+
     # Create the GitLab production database
     mysql> CREATE DATABASE IF NOT EXISTS `gitlabhq_production` DEFAULT CHARACTER SET `utf8` COLLATE `utf8_unicode_ci`;
 
-    # Create the MySQL User change $password to a real password
-    mysql> CREATE USER 'gitlab'@'localhost' IDENTIFIED BY '$password';
-
-    # Grant proper permissions to the MySQL User
+    # Grant the GitLab user necessary permissopns on the table.
     mysql> GRANT SELECT, INSERT, UPDATE, DELETE, CREATE, DROP, INDEX, ALTER ON `gitlabhq_production`.* TO 'gitlab'@'localhost';
 
+    # Quit the database session
+    mysql> \q
+
+    # Try connecting to the new database with the new user
+    sudo -u gitlab -H mysql -u gitlab -p -D gitlabhq_production
 
 ## PostgreSQL
 
-    sudo apt-get install -y postgresql-9.1 postgresql-server-dev-9.1
+    # Install the database packages
+    sudo apt-get install -y postgresql-9.1 libpq-dev
+
+    # Install only the necessary gems
+    sudo -u gitlab -H bundle install --deployment --without development test mysql
 
-    # Connect to database server
+    # Login to PostgreSQL
     sudo -u postgres psql -d template1
 
-    # Add a user called gitlab. Change $password to a real password
+    # Create a user for GitLab. (change $password to a real password)
     template1=# CREATE USER gitlab WITH PASSWORD '$password';
 
     # Create the GitLab production database & grant all privileges on database
     template1=# CREATE DATABASE gitlabhq_production OWNER gitlab;
 
-    # Quit from PostgreSQL server
+    # Quit the database session
     template1=# \q
 
-    # Try connect to new database
-    sudo -u gitlab psql -d gitlabhq_production
+    # Try connecting to the new database with the new user
+    sudo -u gitlab -H psql -d gitlabhq_production
 
 
 
-#### Select the database you want to use
+# Configure GitLab
 
     # Mysql
     sudo -u gitlab cp config/database.yml.mysql config/database.yml
@@ -49,12 +65,4 @@ GitLab use MySQL as default database but you are free to use PostgreSQL.
     # PostgreSQL
     sudo -u gitlab cp config/database.yml.postgresql config/database.yml
 
-    # make sure to update username/password in config/database.yml
-
-#### Install gems 
-
-    # mysql
-    sudo -u gitlab -H bundle install --without development test postgres  --deployment
-
-    # or postgres
-    sudo -u gitlab -H bundle install --without development test mysql --deployment
+Make sure to update username/password in config/database.yml.
diff --git a/doc/install/installation.md b/doc/install/installation.md
index 6876a8756b1..697b82b40c1 100644
--- a/doc/install/installation.md
+++ b/doc/install/installation.md
@@ -1,283 +1,302 @@
-_This installation guide created for Debian/Ubuntu and properly tested._
+This installation guide was created for Debian/Ubuntu and tested on it.
 
-_Checkout requirements before setup_
+Please read doc/install/requirements.md for hardware andplatform requirements.
 
 
-### IMPORTANT
-
-Please make sure you have followed all the steps below before posting to the mailing list with installation and configuration questions.
-
-Only create a GitHub Issue if you want a specific part of this installation guide updated.
-
-Also read the [Read this before you submit an issue](https://github.com/gitlabhq/gitlabhq/wiki/Read-this-before-you-submit-an-issue) wiki page.
+**Important Note**
+The following steps have been known to work.
+If you deviate from this guide, do it with caution and make sure you don't
+violate any assumptions GitLab makes about its environment.
+If you find a bug/error in this guide please an issue or pull request following
+the contribution guide (see CONTRIBUTING.md).
 
 - - -
 
-# Basic setup
-
-The basic installation will provide you a GitLab setup with options:
-
-1. ruby 1.9.3
-2. mysql as main db
-3. gitolite v3 fork by gitlab
-4. nginx + unicorn
+# Overview
 
-The installation consists of next steps:
+The GitLab installation consists of setting up th following components:
 
-1. Packages / dependencies
+1. Packages / Dependencies
 2. Ruby
-3. Users
+3. System Users
 4. Gitolite
-5. Mysql
-6. GitLab.
-7. Nginx 
+5. Database
+6. GitLab
+7. Nginx
 
 
-# 1. Packages / dependencies
+# 1. Packages / Dependencies
 
 *Keep in mind that `sudo` is not installed on Debian by default. You should install it as root:*
 
     apt-get update && apt-get upgrade && apt-get install sudo
 
-Now install the required packages:
+Make sure your system is up-to-date:
 
     sudo apt-get update
     sudo apt-get upgrade
 
-    sudo apt-get install -y wget curl gcc checkinstall libxml2-dev libxslt-dev libcurl4-openssl-dev libreadline6-dev libc6-dev libssl-dev libmysql++-dev make build-essential zlib1g-dev libicu-dev redis-server openssh-server git-core python-dev python-pip libyaml-dev postfix libpq-dev
+Install the required packages:
+
+    sudo apt-get install -y wget curl build-essential checkinstall libxml2-dev libxslt-dev libcurl4-openssl-dev libreadline6-dev libc6-dev libssl-dev zlib1g-dev libicu-dev redis-server openssh-server git-core libyaml-dev postfix
+
+Make sure you have the right version of Python installed.
+
+    # Install Python
+    sudo apt-get install python
+
+    # Make sure that Python is 2.x (3.x is not supported at the moment)
+    python --version
 
-    sudo pip install pygments
+    # If it's Python 3 you might need to install Python 2 separately
+    sudo apt-get install python2.7
 
+    # Make sure you can access Python via `python2`
+    python2 --version
 
-# 2. Install Ruby
+    # If you get a "command not found" error create a link to the python binary
+    sudo ln -s /usr/bin/python /usr/bin/python2
 
-    wget http://ftp.ruby-lang.org/pub/ruby/1.9/ruby-1.9.3-p194.tar.gz
-    tar xfvz ruby-1.9.3-p194.tar.gz
-    cd ruby-1.9.3-p194
+
+# 2. Ruby
+
+    wget http://ftp.ruby-lang.org/pub/ruby/1.9/ruby-1.9.3-p327.tar.gz
+    tar xfvz ruby-1.9.3-p327.tar.gz
+    cd ruby-1.9.3-p327
     ./configure
     make
     sudo make install
 
-# 3. Users
 
-Create user for git:
+# 3. System Users
+
+Create a user for Git and Gitolite:
 
     sudo adduser \
       --system \
       --shell /bin/sh \
-      --gecos 'git version control' \
+      --gecos 'Git Version Control' \
       --group \
       --disabled-password \
       --home /home/git \
       git
 
-Create user for GitLab:
-
-    # ubuntu/debian
-    sudo adduser --disabled-login --gecos 'gitlab system' gitlab
-
-Add your users to groups:
+Create a user for GitLab:
 
-    sudo usermod -a -G git gitlab
-    sudo usermod -a -G gitlab git
+    sudo adduser --disabled-login --gecos 'GitLab' gitlab
 
-Generate key:
+    # Add it to the git group
+    sudo addmod -a -G git gitlab
 
-    sudo -H -u gitlab ssh-keygen -q -N '' -t rsa -f /home/gitlab/.ssh/id_rsa
+    # Generate the SSH key
+    sudo -u gitlab -H ssh-keygen -q -N '' -t rsa -f /home/gitlab/.ssh/id_rsa
 
 
 # 4. Gitolite
 
 Clone GitLab's fork of the Gitolite source code:
 
-    sudo -H -u git git clone -b gl-v304 https://github.com/gitlabhq/gitolite.git /home/git/gitolite
+    sudo -u git -H git clone -b gl-v304 https://github.com/gitlabhq/gitolite.git /home/git/gitolite
 
-Setup:
+Setup Gitolite with GitLab as its admin:
 
+**Important Note**
+GitLab assumes *full and unshared* control over this Gitolite installation.
+
+    # Add Gitolite scripts to $PATH
     cd /home/git
     sudo -u git -H mkdir bin
-    sudo -u git sh -c 'echo -e "PATH=\$PATH:/home/git/bin\nexport PATH" >> /home/git/.profile'
-    sudo -u git sh -c 'gitolite/install -ln /home/git/bin'
+    sudo -u git -H sh -c 'echo -e "PATH=\$PATH:/home/git/bin\nexport PATH" >> /home/git/.profile'
+    sudo -u git -H sh -c 'gitolite/install -ln /home/git/bin'
 
+    # Copy the gitlab user's (public) SSH key ...
     sudo cp /home/gitlab/.ssh/id_rsa.pub /home/git/gitlab.pub
     sudo chmod 0444 /home/git/gitlab.pub
 
+    # ... and use it as the Gitolite admin key for setup
     sudo -u git -H sh -c "PATH=/home/git/bin:$PATH; gitolite setup -pk /home/git/gitlab.pub"
- 
 
-Permissions:
+Fix the directory permissions for the repository:
 
-    sudo chmod -R g+rwX /home/git/repositories/
+    # Make sure the repositories dir is owned by git and it stays that way
+    sudo chmod -R ug+rwXs /home/git/repositories/
     sudo chown -R git:git /home/git/repositories/
 
-    # clone admin repo to add localhost to known_hosts
-    # & be sure your user has access to gitolite
+## Test if everything works so far
+
+    # Clone the admin repo so SSH adds localhost to known_hosts ...
+    # ... and to be sure your users have access to Gitolite
     sudo -u gitlab -H git clone git@localhost:gitolite-admin.git /tmp/gitolite-admin
 
-    # if succeed  you can remove it
+    # If it succeeded without errors you can remove the cloned repo
     sudo rm -rf /tmp/gitolite-admin
 
-**IMPORTANT! If you can't clone `gitolite-admin` repository - DO NOT PROCEED WITH INSTALLATION**
+**Impornant Note**
+If you can't clone the `gitolite-admin` repository: **DO NOT PROCEED WITH INSTALLATION**
 Check the [Trouble Shooting Guide](https://github.com/gitlabhq/gitlab-public-wiki/wiki/Trouble-Shooting-Guide)
-and ensure you have followed all of the above steps carefully.
-
-
-# 5. Mysql database
+and make sure you have followed all of the above steps carefully.
 
-    sudo apt-get install -y mysql-server mysql-client libmysqlclient-dev
 
-    # Login to MySQL
-    $ mysql -u root -p
+# 5. Database
 
-    # Create the GitLab production database
-    mysql> CREATE DATABASE IF NOT EXISTS `gitlabhq_production` DEFAULT CHARACTER SET `utf8` COLLATE `utf8_unicode_ci`;
-
-    # Create the MySQL User change $password to a real password
-    mysql> CREATE USER 'gitlab'@'localhost' IDENTIFIED BY '$password';
-
-    # Grant proper permissions to the MySQL User
-    mysql> GRANT SELECT, INSERT, UPDATE, DELETE, CREATE, DROP, INDEX, ALTER ON `gitlabhq_production`.* TO 'gitlab'@'localhost';
+See doc/install/databases.md
 
 
 # 6. GitLab
 
+    We'll install GitLab into the gitlab user's home directory
     cd /home/gitlab
 
+## Clone the Source
 
-#### Get source code
+    # Clone the latest stable release
+    sudo -u gitlab -H git clone -b stable https://github.com/gitlabhq/gitlabhq.git gitlab
 
-    # Get gitlab code. Use this for stable setup
-    sudo -H -u gitlab git clone -b stable https://github.com/gitlabhq/gitlabhq.git gitlab
+**Note***
+You can change `stable` to `master` if you want the *bleeding edge* version, but
+do so with caution!
 
-    # Skip this for stable setup.
-    # Master branch (recent changes, less stable)
-    sudo -H -u gitlab git clone -b master https://github.com/gitlabhq/gitlabhq.git gitlab
+## Configure it
 
+    cd /home/gitlab/gitlab
 
-#### Copy configs
- 
-    cd gitlab
+    # Copy the example GitLab config
+    sudo -u gitlab -H cp config/gitlab.yml.example config/gitlab.yml
 
-    # Rename config files
-    #
-    sudo -u gitlab cp config/gitlab.yml.example config/gitlab.yml
+    # Make sure to change "localhost" to the fully-qualified domain name of your
+    # host serving GitLab where necessary
+    sudo -u gitlab -H vim config/gitlab.yml
 
-    # Copy mysql db config
-    #
-    # make sure to update username/password in config/database.yml
-    #
-    sudo -u gitlab cp config/database.yml.mysql config/database.yml
+    # Copy the example Unicorn config
+    sudo -u gitlab -H cp config/unicorn.rb.example config/unicorn.rb
 
-    # Copy unicorn config
-    #
-    sudo -u gitlab cp config/unicorn.rb.example config/unicorn.rb
+**Important Note**
+Make sure to edit both files to match your setup.
 
-#### Install gems
+## Install Gems
 
     cd /home/gitlab/gitlab
 
     sudo gem install charlock_holmes --version '0.6.9'
     sudo gem install bundler
-    sudo -u gitlab -H bundle install --without development test postgres  --deployment
+    sudo -u gitlab -H bundle install --deployment --without development test 
 
-#### Configure git client
+## Configure Git
 
-Gitlab needs to be able to commit and push changes to gitolite.
-Git requires a username and email in order to be able to do that.
+GitLab needs to be able to commit and push changes to Gitolite. In order to do
+that Git requires a username and email. (Please use the `email.from` address
+for the email)
 
+    sudo -u gitlab -H git config --global user.name "GitLab"
     sudo -u gitlab -H git config --global user.email "gitlab@localhost"
-    sudo -u gitlab -H git config --global user.name "Gitlab"
 
-#### Setup application
+## Setup GitLab hooks
 
-    sudo -u gitlab bundle exec rake gitlab:app:setup RAILS_ENV=production
+    sudo cp ./lib/hooks/post-receive /home/git/.gitolite/hooks/common/post-receive
+    sudo chown git:git /home/git/.gitolite/hooks/common/post-receive
 
+## Initialise Database and Activate Advanced Features
 
-#### Setup GitLab hooks
+    sudo -u gitlab -H bundle exec rake gitlab:app:setup RAILS_ENV=production
 
-    sudo cp ./lib/hooks/post-receive /home/git/.gitolite/hooks/common/post-receive
-    sudo chown git:git /home/git/.gitolite/hooks/common/post-receive
 
-#### Check application status
+## Check Application Status
+
+Check if GitLab  and its environment is configured correctly:
+
+    sudo -u gitlab -H bundle exec rake gitlab:env:info RAILS_ENV=production
 
-Checking status:
+To make sure you didn't miss anything run a more thorough check with:
 
-    sudo -u gitlab bundle exec rake gitlab:app:status RAILS_ENV=production
+    sudo -u gitlab -H bundle exec rake gitlab:app:status RAILS_ENV=production
 
+```
+# OUTPUT EXAMPLE
+Starting diagnostic
+config/database.yml............exists
+config/gitlab.yml............exists
+/home/git/repositories/............exists
+/home/git/repositories/ is writable?............YES
+remote: Counting objects: 603, done.
+remote: Compressing objects: 100% (466/466), done.
+remote: Total 603 (delta 174), reused 0 (delta 0)
+Receiving objects: 100% (603/603), 53.29 KiB, done.
+Resolving deltas: 100% (174/174), done.
+Can clone gitolite-admin?............YES
+UMASK for .gitolite.rc is 0007? ............YES
+/home/git/share/gitolite/hooks/common/post-receive exists? ............YES
+```
 
-    # OUTPUT EXAMPLE
-    Starting diagnostic
-    config/database.yml............exists
-    config/gitlab.yml............exists
-    /home/git/repositories/............exists
-    /home/git/repositories/ is writable?............YES
-    remote: Counting objects: 603, done.
-    remote: Compressing objects: 100% (466/466), done.
-    remote: Total 603 (delta 174), reused 0 (delta 0)
-    Receiving objects: 100% (603/603), 53.29 KiB, done.
-    Resolving deltas: 100% (174/174), done.
-    Can clone gitolite-admin?............YES
-    UMASK for .gitolite.rc is 0007? ............YES
-    /home/git/share/gitolite/hooks/common/post-receive exists? ............YES
+If you are all green - congratulations! You run a GitLab now.
+But there are still a few steps to go.
 
-If you got all YES - congratulations! You can run a GitLab app.
 
-#### init script
+## Install Init Script
 
-Create init script in /etc/init.d/gitlab:
+Download the init script (will be /etc/init.d/gitlab):
 
     sudo wget https://raw.github.com/gitlabhq/gitlab-recipes/master/init.d/gitlab -P /etc/init.d/
     sudo chmod +x /etc/init.d/gitlab
 
-GitLab autostart:
+Make GitLab start on boot:
 
     sudo update-rc.d gitlab defaults 21
 
-#### Now you should start GitLab application:
+
+Start your GitLab instance:
 
     sudo service gitlab start
 
 
 # 7. Nginx
 
-    # Install first
+## Installation
     sudo apt-get install nginx
 
-    # Add GitLab to nginx sites & change with your host specific settings
+## Site Configuration
+
+Download an example site config:
+
     sudo wget https://raw.github.com/gitlabhq/gitlab-recipes/master/nginx/gitlab -P /etc/nginx/sites-available/
     sudo ln -s /etc/nginx/sites-available/gitlab /etc/nginx/sites-enabled/gitlab
 
+Make sure to edit the config file to match your setup:
+
     # Change **YOUR_SERVER_IP** and **YOUR_SERVER_FQDN**
     # to the IP address and fully-qualified domain name
-    # of the host serving GitLab.
+    # of your host serving GitLab
     sudo vim /etc/nginx/sites-enabled/gitlab
 
-    # Restart nginx:
+## Restart
+
     sudo /etc/init.d/nginx restart
 
 
-# Done!  Visit YOUR_SERVER for gitlab instance
+# Done!
 
-You can login via web using admin generated with setup:
+Visit YOUR_SERVER for your first GitLab login.
+The setup has created an admin account for you. You can use it to log in:
 
     admin@local.host
     5iveL!fe
 
+**Important Note**
+Please go over to your profile page and immediately chage the password, so
+nobody can access your GitLab by using this login information later on.
+
+**Enjoy!**
+
 
 - - -
 
 
 # Advanced setup tips:
 
-_Checkout databases.md for PostgreSQL_
-
-## Customizing Resque's Redis connection
+## Custom Redis connections
 
 If you'd like Resque to connect to a Redis server on a non-standard port or on
-a different host, you can configure its connection string in the
-**config/resque.yml** file:
-
-    production: redis.example.com:6379
+a different host, you can configure its connection string via the
+`config/resque.yml` file.
 
-**Ok - we have a working application now. **
-**But keep going - there are some things that should be done **
+    # example
+    production: redis.example.tld:6379
diff --git a/doc/install/requirements.md b/doc/install/requirements.md
index 75b02d6456f..ec5b013c5d8 100644
--- a/doc/install/requirements.md
+++ b/doc/install/requirements.md
@@ -1,28 +1,56 @@
-## Platform requirements:
+# Hardware
 
-**The project is designed for the Linux operating system.**
+We recommend you to run GitLab on a server with at least 1GB RAM.
 
-It may work on FreeBSD and Mac OS, but we don't test our application for these systems and can't guarantee stability and full functionality.
+The necessary hard disk space largely depends on the size of the repos you want
+to use GitLab with. But as a *rule of thumb* you should have at least as much
+free space as your all repos combined take up.
 
-We officially support (recent versions of) these Linux distributions:
+
+
+# Operating Systems
+
+## Linux
+
+GitLab is developed for the Linux operating system.
+
+GitLab officially supports (recent versions of) these Linux distributions:
 
 - Ubuntu Linux
 - Debian/GNU Linux
 
-It should work on:
+It should also work on (though they are not officially supported):
 
+- Arch
+- CentOS
 - Fedora
-- CentOs
+- Gentoo
 - RedHat
 
-You might have some luck using these, but no guarantees:
+## Other Unix Systems
+
+There is nothing that prevents GitLab from running on other Unix operating
+systems. This means you may get it to work on systems running FreeBSD or OS X.
+**If you want to try, please proceed with caution!**
+
+## Windows
+
+GitLab does **not** run on Windows and we have no plans of supporting it in the
+near future.
+
+
+
+# Rubies
 
-- FreeBSD will likely work, see https://github.com/gitlabhq/gitlabhq/issues/796
-- MacOS X will likely work, see https://groups.google.com/forum/#!topic/gitlabhq/5IXHbPkjKLA
+GitLab requires Ruby (MRI) 1.9.3 and several Gems with native components.
+While it is generally possible to use other Rubies (like
+[JRuby](http://jruby.org/) or [Rubinius](http://rubini.us/)) it might require
+some work on your part.
 
-GitLab does **not** run on Windows and we have no plans of making GitLab compatible.
 
 
-## Hardware: 
+# Installation troubles and reporting success or failure
 
-We recommend to use server with at least 1GB RAM for gitlab instance.
+If you have troubles installing GitLab following the official installation guide
+or want to share your experience installing GitLab on a not officially supported
+platform, please follow the the contribution guide (see CONTRIBUTING.md).