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

Update installation docs

config/database.yml.example

-#
-# PRODUCTION
-#
-production:
-  adapter: mysql2
-  encoding: utf8
-  reconnect: false
-  database: gitlabhq_production
-  pool: 5
-  username: root
-  password: "secure password"
-  # host: localhost
-  # socket: /tmp/mysql.sock
-
-#
-# Development specific
-#
-development:
-  adapter: mysql2
-  encoding: utf8
-  reconnect: false
-  database: gitlabhq_development
-  pool: 5
-  username: root
-  password: "secure password"
-  # socket: /tmp/mysql.sock
-
-# Warning: The database defined as "test" will be erased and
-# re-generated from your development database when you run "rake".
-# Do not set this db to the same as development or production.
-test: &test
-  adapter: mysql2
-  encoding: utf8
-  reconnect: false
-  database: gitlabhq_test
-  pool: 5
-  username: root
-  password: "secure password"
-  # socket: /tmp/mysql.sock

doc/install/databases.md

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

doc/install/requirements.md

-## 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).