deac/gitlabhq
1
0
Fork 0
Code Issues Pull requests Releases Wiki Activity

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

Browse source 
Update installation docs
This commit is contained in:
Dmitriy Zaporozhets 2012-12-07 12:43:25 -08:00
parent 12b4bb5946 d8a239e4b1
commit dfc5adfc23
4 changed files with 229 additions and 213 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

39
config/database.yml.example
View file

@ -1,39 +0,0 @@
#
# 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

52
doc/install/databases.md
View file

@ -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 ## MySQL
# Install the database packages
sudo apt-get install -y mysql-server mysql-client libmysqlclient-dev 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 # Login to MySQL
$ mysql -u root -p $ 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 # Create the GitLab production database
mysql> CREATE DATABASE IF NOT EXISTS `gitlabhq_production` DEFAULT CHARACTER SET `utf8` COLLATE `utf8_unicode_ci`; 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 # Grant the GitLab user necessary permissopns on the table.
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'; 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 ## 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
# Connect to database server # Install only the necessary gems
sudo -u gitlab -H bundle install --deployment --without development test mysql
# Login to PostgreSQL
sudo -u postgres psql -d template1 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'; template1=# CREATE USER gitlab WITH PASSWORD '$password';
# Create the GitLab production database & grant all privileges on database # Create the GitLab production database & grant all privileges on database
template1=# CREATE DATABASE gitlabhq_production OWNER gitlab; template1=# CREATE DATABASE gitlabhq_production OWNER gitlab;
# Quit from PostgreSQL server # Quit the database session
template1=# \q template1=# \q
# Try connect to new database # Try connecting to the new database with the new user
sudo -u gitlab psql -d gitlabhq_production sudo -u gitlab -H psql -d gitlabhq_production
#### Select the database you want to use # Configure GitLab
# Mysql # Mysql
sudo -u gitlab cp config/database.yml.mysql config/database.yml 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 # PostgreSQL
sudo -u gitlab cp config/database.yml.postgresql config/database.yml sudo -u gitlab cp config/database.yml.postgresql config/database.yml
# make sure to update username/password in 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

297
doc/install/installation.md
View file

@ -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 **Important Note**
The following steps have been known to work.
Please make sure you have followed all the steps below before posting to the mailing list with installation and configuration questions. If you deviate from this guide, do it with caution and make sure you don't
violate any assumptions GitLab makes about its environment.
Only create a GitHub Issue if you want a specific part of this installation guide updated. If you find a bug/error in this guide please an issue or pull request following
the contribution guide (see CONTRIBUTING.md).
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 # Overview
The basic installation will provide you a GitLab setup with options: The GitLab installation consists of setting up th following components:
1. ruby 1.9.3 1. Packages / Dependencies
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 2. Ruby
3. Users 3. System Users
4. Gitolite 4. Gitolite
5. Mysql 5. Database
6. GitLab. 6. GitLab
7. Nginx 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:* *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 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 update
sudo apt-get upgrade 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 pip install pygments 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
# 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
# If you get a "command not found" error create a link to the python binary
sudo ln -s /usr/bin/python /usr/bin/python2
# 2. Install Ruby # 2. Ruby
wget http://ftp.ruby-lang.org/pub/ruby/1.9/ruby-1.9.3-p194.tar.gz wget http://ftp.ruby-lang.org/pub/ruby/1.9/ruby-1.9.3-p327.tar.gz
tar xfvz ruby-1.9.3-p194.tar.gz tar xfvz ruby-1.9.3-p327.tar.gz
cd ruby-1.9.3-p194 cd ruby-1.9.3-p327
./configure ./configure
make make
sudo make install sudo make install
# 3. Users
Create user for git: # 3. System Users
Create a user for Git and Gitolite:
sudo adduser \ sudo adduser \
--system \ --system \
--shell /bin/sh \ --shell /bin/sh \
--gecos 'git version control' \ --gecos 'Git Version Control' \
--group \ --group \
--disabled-password \ --disabled-password \
--home /home/git \ --home /home/git \
git git
Create user for GitLab: Create a user for GitLab:
# ubuntu/debian sudo adduser --disabled-login --gecos 'GitLab' gitlab
sudo adduser --disabled-login --gecos 'gitlab system' gitlab
Add your users to groups: # Add it to the git group
sudo addmod -a -G git gitlab
sudo usermod -a -G git gitlab # Generate the SSH key
sudo usermod -a -G gitlab git sudo -u gitlab -H ssh-keygen -q -N '' -t rsa -f /home/gitlab/.ssh/id_rsa
Generate key:
sudo -H -u gitlab ssh-keygen -q -N '' -t rsa -f /home/gitlab/.ssh/id_rsa
# 4. Gitolite # 4. Gitolite
Clone GitLab's fork of the Gitolite source code: 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 cd /home/git
sudo -u git -H mkdir bin 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 -H 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 '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 cp /home/gitlab/.ssh/id_rsa.pub /home/git/gitlab.pub
sudo chmod 0444 /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" sudo -u git -H sh -c "PATH=/home/git/bin:$PATH; gitolite setup -pk /home/git/gitlab.pub"
Fix the directory permissions for the repository:
Permissions: # Make sure the repositories dir is owned by git and it stays that way
sudo chmod -R ug+rwXs /home/git/repositories/
sudo chmod -R g+rwX /home/git/repositories/
sudo chown -R git:git /home/git/repositories/ sudo chown -R git:git /home/git/repositories/
# clone admin repo to add localhost to known_hosts ## Test if everything works so far
# & be sure your user has access to gitolite
# 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 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 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) 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. and make sure you have followed all of the above steps carefully.
# 5. Mysql database # 5. Database
sudo apt-get install -y mysql-server mysql-client libmysqlclient-dev See doc/install/databases.md
# 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 # 6. GitLab
We'll install GitLab into the gitlab user's home directory
cd /home/gitlab 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 **Note***
sudo -H -u gitlab git clone -b stable https://github.com/gitlabhq/gitlabhq.git gitlab You can change `stable` to `master` if you want the *bleeding edge* version, but
do so with caution!
# Skip this for stable setup. ## Configure it
# Master branch (recent changes, less stable)
sudo -H -u gitlab git clone -b master https://github.com/gitlabhq/gitlabhq.git gitlab
cd /home/gitlab/gitlab
#### Copy configs # Copy the example GitLab config
sudo -u gitlab -H cp config/gitlab.yml.example config/gitlab.yml
cd gitlab # 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
# Rename config files # Copy the example Unicorn config
# sudo -u gitlab -H cp config/unicorn.rb.example config/unicorn.rb
sudo -u gitlab cp config/gitlab.yml.example config/gitlab.yml
# Copy mysql db config **Important Note**
# Make sure to edit both files to match your setup.
# make sure to update username/password in config/database.yml
#
sudo -u gitlab cp config/database.yml.mysql config/database.yml
# Copy unicorn config ## Install Gems
#
sudo -u gitlab cp config/unicorn.rb.example config/unicorn.rb
#### Install gems
cd /home/gitlab/gitlab cd /home/gitlab/gitlab
sudo gem install charlock_holmes --version '0.6.9' sudo gem install charlock_holmes --version '0.6.9'
sudo gem install bundler 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. GitLab needs to be able to commit and push changes to Gitolite. In order to do
Git requires a username and email in order to be able to do that. 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.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
#### Setup GitLab hooks
sudo cp ./lib/hooks/post-receive /home/git/.gitolite/hooks/common/post-receive sudo cp ./lib/hooks/post-receive /home/git/.gitolite/hooks/common/post-receive
sudo chown git:git /home/git/.gitolite/hooks/common/post-receive sudo chown git:git /home/git/.gitolite/hooks/common/post-receive
#### Check application status ## Initialise Database and Activate Advanced Features
Checking status: sudo -u gitlab -H bundle exec rake gitlab:app:setup RAILS_ENV=production
sudo -u gitlab bundle exec rake gitlab:app:status RAILS_ENV=production
# OUTPUT EXAMPLE ## Check Application Status
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. Check if GitLab and its environment is configured correctly:
#### init script sudo -u gitlab -H bundle exec rake gitlab:env:info RAILS_ENV=production
Create init script in /etc/init.d/gitlab: To make sure you didn't miss anything run a more thorough check with:
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
```
If you are all green - congratulations! You run a GitLab now.
But there are still a few steps to go.
## Install Init Script
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 wget https://raw.github.com/gitlabhq/gitlab-recipes/master/init.d/gitlab -P /etc/init.d/
sudo chmod +x /etc/init.d/gitlab sudo chmod +x /etc/init.d/gitlab
GitLab autostart: Make GitLab start on boot:
sudo update-rc.d gitlab defaults 21 sudo update-rc.d gitlab defaults 21
#### Now you should start GitLab application:
Start your GitLab instance:
sudo service gitlab start sudo service gitlab start
# 7. Nginx # 7. Nginx
# Install first ## Installation
sudo apt-get install nginx 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 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 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** # Change **YOUR_SERVER_IP** and **YOUR_SERVER_FQDN**
# to the IP address and fully-qualified domain name # 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 sudo vim /etc/nginx/sites-enabled/gitlab
# Restart nginx: ## Restart
sudo /etc/init.d/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 admin@local.host
5iveL!fe 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: # Advanced setup tips:
_Checkout databases.md for PostgreSQL_ ## Custom Redis connections
## Customizing Resque's Redis connection
If you'd like Resque to connect to a Redis server on a non-standard port or on 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 a different host, you can configure its connection string via the
**config/resque.yml** file: `config/resque.yml` file.
production: redis.example.com:6379 # example
production: redis.example.tld:6379
**Ok - we have a working application now. **
**But keep going - there are some things that should be done **

52
doc/install/requirements.md
View file

@ -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 - Ubuntu Linux
- Debian/GNU Linux - Debian/GNU Linux
It should work on: It should also work on (though they are not officially supported):
- Arch
- CentOS
- Fedora - Fedora
- CentOs - Gentoo
- RedHat - RedHat
You might have some luck using these, but no guarantees: ## Other Unix Systems
- FreeBSD will likely work, see https://github.com/gitlabhq/gitlabhq/issues/796 There is nothing that prevents GitLab from running on other Unix operating
- MacOS X will likely work, see https://groups.google.com/forum/#!topic/gitlabhq/5IXHbPkjKLA 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!**
GitLab does **not** run on Windows and we have no plans of making GitLab compatible. ## Windows
GitLab does **not** run on Windows and we have no plans of supporting it in the
near future.
## Hardware:
We recommend to use server with at least 1GB RAM for gitlab instance. # Rubies
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.
# Installation troubles and reporting success or failure
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).