move installation docs under separate dir

4 files changed, 694 insertions, 0 deletions

diff --git a/doc/install/:w b/doc/install/:w
new file mode 100644
index 00000000000..9bc0c211aaa
--- /dev/null
+++ b/doc/install/:w
@@ -0,0 +1,295 @@
+_This installation guide created for Debian/Ubuntu and properly tested._
+
+_Checkout requirements before setup_
+
+### 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.
+
+- - -
+
+# 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
+
+The installation consists of next steps:
+
+1. Packages / dependencies
+2. Ruby
+3. Users
+4. Gitolite
+5. Mysql
+6. GitLab.
+7. Nginx 
+
+
+# 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:
+
+    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
+
+    sudo pip install pygments
+
+
+# 2. Install Ruby
+
+    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
+    ./configure
+    make
+    sudo make install
+
+# 3. Users
+
+Create user for git:
+
+    sudo adduser \
+      --system \
+      --shell /bin/sh \
+      --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:
+
+    sudo usermod -a -G git gitlab
+    sudo usermod -a -G gitlab git
+
+Generate key:
+
+    sudo -H -u gitlab 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
+
+Setup:
+
+    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 cp /home/gitlab/.ssh/id_rsa.pub /home/git/gitlab.pub
+    sudo chmod 0444 /home/git/gitlab.pub
+
+    sudo -u git -H sh -c "PATH=/home/git/bin:$PATH; gitolite setup -pk /home/git/gitlab.pub"
+    sudo -u git -H sed -i 's/0077/0007/g' /home/git/.gitolite.rc
+    sudo -u git -H sed -i "s/\(GIT_CONFIG_KEYS\s*=>*\s*\).\{2\}/\1'\.\*'/g" /home/git/.gitolite.rc
+
+Permissions:
+
+    sudo chmod -R g+rwX /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
+    sudo -u gitlab -H git clone git@localhost:gitolite-admin.git /tmp/gitolite-admin
+
+    # if succeed  you can remove it
+    sudo rm -rf /tmp/gitolite-admin
+
+**IMPORTANT! If you can't clone `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
+
+    sudo apt-get install -y mysql-server mysql-client libmysqlclient-dev
+
+    # Login to MySQL
+    $ mysql -u root -p
+
+    # 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';
+
+
+# 6. GitLab
+
+    cd /home/gitlab
+
+
+#### Get source code
+
+    # Get gitlab code. Use this for stable setup
+    sudo -H -u gitlab git clone -b stable https://github.com/gitlabhq/gitlabhq.git gitlab
+
+    # 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
+
+
+#### Copy configs
+ 
+    cd gitlab
+
+    # Rename config files
+    #
+    sudo -u gitlab cp config/gitlab.yml.example 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 unicorn config
+    #
+    sudo -u gitlab cp config/unicorn.rb.example config/unicorn.rb
+
+#### Install gems
+
+    cd /home/gitlab/gitlab
+
+    sudo gem install charlock_holmes --version '0.6.8'
+    sudo gem install bundler
+    sudo -u gitlab -H bundle install --without development test sqlite postgres  --deployment
+
+#### Setup application
+
+    sudo -u gitlab bundle exec rake gitlab:app:setup RAILS_ENV=production
+
+
+#### Setup GitLab hooks
+
+    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
+
+Checking status:
+
+    sudo -u gitlab 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
+
+If you got all YES - congratulations! You can run a GitLab app.
+
+#### init script
+
+Create init script in /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:
+
+    sudo update-rc.d gitlab defaults 21
+
+#### Now you should start GitLab application:
+
+    sudo service gitlab start
+
+
+# 7. Nginx
+
+    # Install first
+    sudo apt-get install nginx
+
+    # Add GitLab to nginx sites & change with your host specific settings
+    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
+
+    # Change **YOUR_SERVER_IP** and **YOUR_SERVER_FQDN**
+    # to the IP address and fully-qualified domain name
+    # of the host serving GitLab.
+    sudo vim /etc/nginx/sites-enabled/gitlab
+
+    # Restart nginx:
+    sudo /etc/init.d/nginx restart
+
+
+# Done!  Visit YOUR_SERVER for gitlab instance
+
+You can login via web using admin generated with setup:
+
+    admin@local.host
+    5iveL!fe
+
+
+- - -
+
+
+# Advanced setup tips:
+
+
+## Quick setup
+
+> - - -
+> The first 3 steps of this guide can be easily skipped by executing an install script:
+>
+>     # Install curl and sudo
+>     apt-get install curl sudo
+>
+>     # 3 steps in 1 command :)
+>     curl https://raw.github.com/gitlabhq/gitlab-recipes/master/install/debian_ubuntu.sh | sh
+>
+> Now you can go to [Step 4](#4-install-gitlab-and-configuration-check-status-configuration)
+>
+> Or if you are installing on Amazon Web Services using Ubuntu 12.04 you can do all steps (1 to 6) at once with:
+>
+>     curl https://raw.github.com/gitlabhq/gitlab-recipes/master/install/debian_ubuntu_aws.sh | sh
+>
+> for more detailed instructions read the HOWTO section of [the script](https://github.com/gitlabhq/gitlab-recipes/blob/master/install/debian_ubuntu_aws.sh)
+> - - -
+
+
+## Customizing Resque's Redis connection
+
+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
+
+**Ok - we have a working application now. **
+**But keep going - there are some things that should be done **
diff --git a/doc/install/databases.md b/doc/install/databases.md
new file mode 100644
index 00000000000..8ca3d8fe51f
--- /dev/null
+++ b/doc/install/databases.md
@@ -0,0 +1,75 @@
+# Databases:
+
+GitLab use mysql as default database but you are free to use PostgreSQL or SQLite.
+
+
+## SQLite
+
+    sudo apt-get install -y sqlite3 libsqlite3-dev 
+
+## MySQL
+
+    sudo apt-get install -y mysql-server mysql-client libmysqlclient-dev
+
+    # Login to MySQL
+    $ mysql -u root -p
+
+    # 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';
+
+
+## PostgreSQL
+
+    sudo apt-get install -y postgresql-9.2 postgresql-server-dev-9.2
+
+    # Connect to database server
+    sudo -u postgres psql -d template1
+
+    # Add a user called gitlab. Change $password to a real password
+    template1=# CREATE USER gitlab WITH PASSWORD '$password';
+
+    # Create the GitLab production database
+    template1=# CREATE DATABASE IF NOT EXISTS gitlabhq_production;
+
+    # Grant all privileges on database
+    template1=# GRANT ALL PRIVILEGES ON DATABASE gitlabhq_production to gitlab;
+
+    # Quit from PostgreSQL server
+    template1=# \q
+
+    # Try connect to new database
+    $ su - gitlab
+    $ psql -d gitlabhq_production -U gitlab
+
+
+
+#### Select the database you want to use
+
+    # SQLite
+    sudo -u gitlab cp config/database.yml.sqlite config/database.yml
+
+    # Mysql
+    sudo -u gitlab cp config/database.yml.mysql config/database.yml
+
+    # PostgreSQL
+    sudo -u gitlab cp config/database.yml.postgres 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 sqlite postgres  --deployment
+
+    # or postgres
+    sudo -u gitlab -H bundle install --without development test sqlite mysql --deployment
+
+    # or sqlite
+    sudo -u gitlab -H bundle install --without development test mysql postgres  --deployment
+
diff --git a/doc/install/installation.md b/doc/install/installation.md
new file mode 100644
index 00000000000..5e631288489
--- /dev/null
+++ b/doc/install/installation.md
@@ -0,0 +1,296 @@
+_This installation guide created for Debian/Ubuntu and properly tested._
+
+_Checkout requirements before setup_
+
+
+### 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.
+
+- - -
+
+# 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
+
+The installation consists of next steps:
+
+1. Packages / dependencies
+2. Ruby
+3. Users
+4. Gitolite
+5. Mysql
+6. GitLab.
+7. Nginx 
+
+
+# 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:
+
+    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
+
+    sudo pip install pygments
+
+
+# 2. Install Ruby
+
+    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
+    ./configure
+    make
+    sudo make install
+
+# 3. Users
+
+Create user for git:
+
+    sudo adduser \
+      --system \
+      --shell /bin/sh \
+      --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:
+
+    sudo usermod -a -G git gitlab
+    sudo usermod -a -G gitlab git
+
+Generate key:
+
+    sudo -H -u gitlab 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
+
+Setup:
+
+    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 cp /home/gitlab/.ssh/id_rsa.pub /home/git/gitlab.pub
+    sudo chmod 0444 /home/git/gitlab.pub
+
+    sudo -u git -H sh -c "PATH=/home/git/bin:$PATH; gitolite setup -pk /home/git/gitlab.pub"
+    sudo -u git -H sed -i 's/0077/0007/g' /home/git/.gitolite.rc
+    sudo -u git -H sed -i "s/\(GIT_CONFIG_KEYS\s*=>*\s*\).\{2\}/\1'\.\*'/g" /home/git/.gitolite.rc
+
+Permissions:
+
+    sudo chmod -R g+rwX /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
+    sudo -u gitlab -H git clone git@localhost:gitolite-admin.git /tmp/gitolite-admin
+
+    # if succeed  you can remove it
+    sudo rm -rf /tmp/gitolite-admin
+
+**IMPORTANT! If you can't clone `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
+
+    sudo apt-get install -y mysql-server mysql-client libmysqlclient-dev
+
+    # Login to MySQL
+    $ mysql -u root -p
+
+    # 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';
+
+
+# 6. GitLab
+
+    cd /home/gitlab
+
+
+#### Get source code
+
+    # Get gitlab code. Use this for stable setup
+    sudo -H -u gitlab git clone -b stable https://github.com/gitlabhq/gitlabhq.git gitlab
+
+    # 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
+
+
+#### Copy configs
+ 
+    cd gitlab
+
+    # Rename config files
+    #
+    sudo -u gitlab cp config/gitlab.yml.example 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 unicorn config
+    #
+    sudo -u gitlab cp config/unicorn.rb.example config/unicorn.rb
+
+#### Install gems
+
+    cd /home/gitlab/gitlab
+
+    sudo gem install charlock_holmes --version '0.6.8'
+    sudo gem install bundler
+    sudo -u gitlab -H bundle install --without development test sqlite postgres  --deployment
+
+#### Setup application
+
+    sudo -u gitlab bundle exec rake gitlab:app:setup RAILS_ENV=production
+
+
+#### Setup GitLab hooks
+
+    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
+
+Checking status:
+
+    sudo -u gitlab 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
+
+If you got all YES - congratulations! You can run a GitLab app.
+
+#### init script
+
+Create init script in /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:
+
+    sudo update-rc.d gitlab defaults 21
+
+#### Now you should start GitLab application:
+
+    sudo service gitlab start
+
+
+# 7. Nginx
+
+    # Install first
+    sudo apt-get install nginx
+
+    # Add GitLab to nginx sites & change with your host specific settings
+    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
+
+    # Change **YOUR_SERVER_IP** and **YOUR_SERVER_FQDN**
+    # to the IP address and fully-qualified domain name
+    # of the host serving GitLab.
+    sudo vim /etc/nginx/sites-enabled/gitlab
+
+    # Restart nginx:
+    sudo /etc/init.d/nginx restart
+
+
+# Done!  Visit YOUR_SERVER for gitlab instance
+
+You can login via web using admin generated with setup:
+
+    admin@local.host
+    5iveL!fe
+
+
+- - -
+
+
+# Advanced setup tips:
+
+
+## Quick setup
+
+> - - -
+> The first 3 steps of this guide can be easily skipped by executing an install script:
+>
+>     # Install curl and sudo
+>     apt-get install curl sudo
+>
+>     # 3 steps in 1 command :)
+>     curl https://raw.github.com/gitlabhq/gitlab-recipes/master/install/debian_ubuntu.sh | sh
+>
+> Now you can go to [Step 4](#4-install-gitlab-and-configuration-check-status-configuration)
+>
+> Or if you are installing on Amazon Web Services using Ubuntu 12.04 you can do all steps (1 to 6) at once with:
+>
+>     curl https://raw.github.com/gitlabhq/gitlab-recipes/master/install/debian_ubuntu_aws.sh | sh
+>
+> for more detailed instructions read the HOWTO section of [the script](https://github.com/gitlabhq/gitlab-recipes/blob/master/install/debian_ubuntu_aws.sh)
+> - - -
+
+
+## Customizing Resque's Redis connection
+
+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
+
+**Ok - we have a working application now. **
+**But keep going - there are some things that should be done **
diff --git a/doc/install/requirements.md b/doc/install/requirements.md
new file mode 100644
index 00000000000..955f99a5ac9
--- /dev/null
+++ b/doc/install/requirements.md
@@ -0,0 +1,28 @@
+## Platform requirements:
+
+**The project is designed for the Linux operating system.**
+
+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.
+
+We officially support (recent versions of) these Linux distributions:
+
+- Ubuntu Linux
+- Debian/GNU Linux
+
+It should work on:
+
+- Fedora
+- CentOs
+- RedHat
+
+You might have some luck using these, but no guarantees:
+
+ - MacOS X
+ - FreeBSD
+
+GitLab does **not** run on Windows and we have no plans of making GitLab compatible.
+
+
+## Hardware: 
+
+We recommend to use server with at least 1GB RAM for gitlab instance.