Download as
Browse Code »

Commit 4af26f66f87fb77487c9955e58826344af6d3f66

Authored by Riyad Preukschas
1 parent 198e93cc
Exists in master and in 4 other branches 6-8-stable, 7-0-stable, 7-0-stable-spb, spb-stable

Update installation guide

Showing 1 changed file with 120 additions and 108 deletions   Show diff stats
doc/install/installation.md
  Diff comments   View file @4af26f6
... ... @@ -3,87 +3,75 @@ This installation guide was created for Debian/Ubuntu and tested on it.
3 3 Please read doc/install/requirements.md for hardware andplatform requirements.
4 4  
5 5  
6   -
7   -### IMPORTANT
8   -
9   -Please make sure you have followed all the steps below before posting to the mailing list with installation and configuration questions.
10   -
11   -Only create a GitHub Issue if you want a specific part of this installation guide updated.
12   -
13   -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.
  6 +**Important Note**
  7 +The following steps have been known to work.
  8 +If you deviate from this guide, do it with caution and make sure you don't
  9 +violate any assumptions GitLab makes about its environment.
  10 +If you find a bug/error in this guide please an issue or pull request following
  11 +the contribution guide (see CONTRIBUTING.md).
14 12  
15 13 - - -
16 14  
17   -# Basic setup
  15 +# Overview
18 16  
19   -The basic installation will provide you a GitLab setup with options:
  17 +The GitLab installation consists of setting up th following components:
20 18  
21   -1. ruby 1.9.3
22   -2. mysql as main db
23   -3. gitolite v3 fork by gitlab
24   -4. nginx + unicorn
25   -
26   -The installation consists of next steps:
27   -
28   -1. Packages / dependencies
  19 +1. Packages / Dependencies
29 20 2. Ruby
30   -3. Users
  21 +3. System Users
31 22 4. Gitolite
32   -5. Mysql
33   -6. GitLab.
34   -7. Nginx
  23 +5. Database
  24 +6. GitLab
  25 +7. Nginx
35 26  
36 27  
37   -# 1. Packages / dependencies
  28 +# 1. Packages / Dependencies
38 29  
39 30 *Keep in mind that `sudo` is not installed on Debian by default. You should install it as root:*
40 31  
41 32 apt-get update && apt-get upgrade && apt-get install sudo
42 33  
43   -Now install the required packages:
  34 +Make sure your system is up-to-date:
44 35  
45 36 sudo apt-get update
46 37 sudo apt-get upgrade
47 38  
48   - 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 python2.7 libyaml-dev postfix
  39 +Install the required packages:
49 40  
50   - sudo pip install pygments
  41 + 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 python2.7 libyaml-dev postfix
51 42  
52 43  
53   -# 2. Install Ruby
  44 +# 2. Ruby
54 45  
55   - wget http://ftp.ruby-lang.org/pub/ruby/1.9/ruby-1.9.3-p194.tar.gz
56   - tar xfvz ruby-1.9.3-p194.tar.gz
57   - cd ruby-1.9.3-p194
  46 + wget http://ftp.ruby-lang.org/pub/ruby/1.9/ruby-1.9.3-p327.tar.gz
  47 + tar xfvz ruby-1.9.3-p327.tar.gz
  48 + cd ruby-1.9.3-p327
58 49 ./configure
59 50 make
60 51 sudo make install
61 52  
62   -# 3. Users
63 53  
64   -Create user for git:
  54 +# 3. System Users
  55 +
  56 +Create a user for Git and Gitolite:
65 57  
66 58 sudo adduser \
67 59 --system \
68 60 --shell /bin/sh \
69   - --gecos 'git version control' \
  61 + --gecos 'Git Version Control' \
70 62 --group \
71 63 --disabled-password \
72 64 --home /home/git \
73 65 git
74 66  
75   -Create user for GitLab:
76   -
77   - # ubuntu/debian
78   - sudo adduser --disabled-login --gecos 'gitlab system' gitlab
  67 +Create a user for GitLab:
79 68  
80   -Add your users to groups:
  69 + sudo adduser --disabled-login --gecos 'GitLab' gitlab
81 70  
82   - sudo usermod -a -G git gitlab
83   - sudo usermod -a -G gitlab git
84   -
85   -Generate key:
  71 + # Add it to the git group
  72 + sudo addmod -a -G git gitlab
86 73  
  74 + # Generate the SSH key
87 75 sudo -u gitlab -H ssh-keygen -q -N '' -t rsa -f /home/gitlab/.ssh/id_rsa
88 76  
89 77  
... ... @@ -93,34 +81,43 @@ Clone GitLab's fork of the Gitolite source code:
93 81  
94 82 sudo -u git -H git clone -b gl-v304 https://github.com/gitlabhq/gitolite.git /home/git/gitolite
95 83  
96   -Setup:
  84 +Setup Gitolite with GitLab as its admin:
  85 +
  86 +**Important Note**
  87 +GitLab assumes *full and unshared* control over this Gitolite installation.
97 88  
  89 + # Add Gitolite scripts to $PATH
98 90 cd /home/git
99 91 sudo -u git -H mkdir bin
100 92 sudo -u git -H sh -c 'echo -e "PATH=\$PATH:/home/git/bin\nexport PATH" >> /home/git/.profile'
101 93 sudo -u git -H sh -c 'gitolite/install -ln /home/git/bin'
102 94  
  95 + # Copy the gitlab user's (public) SSH key ...
103 96 sudo cp /home/gitlab/.ssh/id_rsa.pub /home/git/gitlab.pub
104 97 sudo chmod 0444 /home/git/gitlab.pub
105 98  
  99 + # ... and use it as the Gitolite admin key for setup
106 100 sudo -u git -H sh -c "PATH=/home/git/bin:$PATH; gitolite setup -pk /home/git/gitlab.pub"
107   -
108 101  
109   -Permissions:
  102 +Fix the directory permissions for the repository:
110 103  
  104 + # Make sure the repositories dir is owned by git and it stays that way
111 105 sudo chmod -R ug+rwXs /home/git/repositories/
112 106 sudo chown -R git:git /home/git/repositories/
113 107  
114   - # clone admin repo to add localhost to known_hosts
115   - # & be sure your user has access to gitolite
  108 +## Test if everything works so far
  109 +
  110 + # Clone the admin repo so SSH adds localhost to known_hosts ...
  111 + # ... and to be sure your users have access to Gitolite
116 112 sudo -u gitlab -H git clone git@localhost:gitolite-admin.git /tmp/gitolite-admin
117 113  
118   - # if succeed you can remove it
  114 + # If it succeeded without errors you can remove the cloned repo
119 115 sudo rm -rf /tmp/gitolite-admin
120 116  
121   -**IMPORTANT! If you can't clone `gitolite-admin` repository - DO NOT PROCEED WITH INSTALLATION**
  117 +**Impornant Note**
  118 +If you can't clone the `gitolite-admin` repository: **DO NOT PROCEED WITH INSTALLATION**
122 119 Check the [Trouble Shooting Guide](https://github.com/gitlabhq/gitlab-public-wiki/wiki/Trouble-Shooting-Guide)
123   -and ensure you have followed all of the above steps carefully.
  120 +and make sure you have followed all of the above steps carefully.
124 121  
125 122  
126 123 # 5. Database
... ... @@ -130,135 +127,150 @@ See doc/install/databases.md
130 127  
131 128 # 6. GitLab
132 129  
  130 + We'll install GitLab into the gitlab user's home directory
133 131 cd /home/gitlab
134 132  
  133 +## Clone the Source
135 134  
136   -#### Get source code
137   -
138   - # Get gitlab code. Use this for stable setup
  135 + # Clone the latest stable release
139 136 sudo -u gitlab -H git clone -b stable https://github.com/gitlabhq/gitlabhq.git gitlab
140 137  
141   - # Skip this for stable setup.
142   - # Master branch (recent changes, less stable)
143   - sudo -u gitlab -H git clone -b master https://github.com/gitlabhq/gitlabhq.git gitlab
  138 +**Note***
  139 +You can change `stable` to `master` if you want the *bleeding edge* version, but
  140 +do so with caution!
144 141  
  142 +## Configure it
145 143  
146   -#### Copy configs
147   -
148   - cd gitlab
  144 + cd /home/gitlab/gitlab
149 145  
150   - # Rename config files
151   - #
  146 + # Copy the example GitLab config
152 147 sudo -u gitlab -H cp config/gitlab.yml.example config/gitlab.yml
153 148  
154   - # Copy unicorn config
155   - #
  149 + # Copy the example Unicorn config
156 150 sudo -u gitlab -H cp config/unicorn.rb.example config/unicorn.rb
157 151  
158   -#### Install gems
  152 +Make sure to edit both files to match your setup.
  153 +
  154 +## Install Gems
159 155  
160 156 cd /home/gitlab/gitlab
161 157  
162 158 sudo gem install charlock_holmes --version '0.6.9'
163 159 sudo gem install bundler
164   - sudo -u gitlab -H bundle install --without development test postgres --deployment
  160 + sudo -u gitlab -H bundle install --deployment --without development test
165 161  
166   -#### Configure git client
  162 +## Configure Git
167 163  
168   -Gitlab needs to be able to commit and push changes to gitolite.
169   -Git requires a username and email in order to be able to do that.
  164 +GitLab needs to be able to commit and push changes to Gitolite. In order to do
  165 +that Git requires a username and email. (Please use the `email.from` address
  166 +for the email)
170 167  
  168 + sudo -u gitlab -H git config --global user.name "GitLab"
171 169 sudo -u gitlab -H git config --global user.email "gitlab@localhost"
172   - sudo -u gitlab -H git config --global user.name "Gitlab"
173 170  
174   -#### Setup application
  171 +## Setup GitLab hooks
175 172  
176   - sudo -u gitlab -H bundle exec rake gitlab:app:setup RAILS_ENV=production
  173 + sudo cp ./lib/hooks/post-receive /home/git/.gitolite/hooks/common/post-receive
  174 + sudo chown git:git /home/git/.gitolite/hooks/common/post-receive
177 175  
  176 +## Initialise Database and Activate Advanced Features
178 177  
179   -#### Setup GitLab hooks
  178 + sudo -u gitlab -H bundle exec rake gitlab:app:setup RAILS_ENV=production
180 179  
181   - sudo cp ./lib/hooks/post-receive /home/git/.gitolite/hooks/common/post-receive
182   - sudo chown git:git /home/git/.gitolite/hooks/common/post-receive
183 180  
184   -#### Check application status
  181 +## Check Application Status
185 182  
186   -Checking status:
  183 +Just to check we didn't miss anything.
187 184  
188 185 sudo -u gitlab -H bundle exec rake gitlab:app:status RAILS_ENV=production
189 186  
  187 +```
  188 +# OUTPUT EXAMPLE
  189 +Starting diagnostic
  190 +config/database.yml............exists
  191 +config/gitlab.yml............exists
  192 +/home/git/repositories/............exists
  193 +/home/git/repositories/ is writable?............YES
  194 +remote: Counting objects: 603, done.
  195 +remote: Compressing objects: 100% (466/466), done.
  196 +remote: Total 603 (delta 174), reused 0 (delta 0)
  197 +Receiving objects: 100% (603/603), 53.29 KiB, done.
  198 +Resolving deltas: 100% (174/174), done.
  199 +Can clone gitolite-admin?............YES
  200 +UMASK for .gitolite.rc is 0007? ............YES
  201 +/home/git/share/gitolite/hooks/common/post-receive exists? ............YES
  202 +```
190 203  
191   - # OUTPUT EXAMPLE
192   - Starting diagnostic
193   - config/database.yml............exists
194   - config/gitlab.yml............exists
195   - /home/git/repositories/............exists
196   - /home/git/repositories/ is writable?............YES
197   - remote: Counting objects: 603, done.
198   - remote: Compressing objects: 100% (466/466), done.
199   - remote: Total 603 (delta 174), reused 0 (delta 0)
200   - Receiving objects: 100% (603/603), 53.29 KiB, done.
201   - Resolving deltas: 100% (174/174), done.
202   - Can clone gitolite-admin?............YES
203   - UMASK for .gitolite.rc is 0007? ............YES
204   - /home/git/share/gitolite/hooks/common/post-receive exists? ............YES
  204 +If you are all green - congratulations! You run a GitLab now.
  205 +But there are still a few steps to go.
205 206  
206   -If you got all YES - congratulations! You can run a GitLab app.
207 207  
208   -#### init script
  208 +## Install Init Script
209 209  
210   -Create init script in /etc/init.d/gitlab:
  210 +Download the init script (will be /etc/init.d/gitlab):
211 211  
212 212 sudo wget https://raw.github.com/gitlabhq/gitlab-recipes/master/init.d/gitlab -P /etc/init.d/
213 213 sudo chmod +x /etc/init.d/gitlab
214 214  
215   -GitLab autostart:
  215 +Make GitLab start on boot:
216 216  
217 217 sudo update-rc.d gitlab defaults 21
218 218  
219   -#### Now you should start GitLab application:
  219 +
  220 +Start your GitLab instance:
220 221  
221 222 sudo service gitlab start
222 223  
223 224  
224 225 # 7. Nginx
225 226  
226   - # Install first
  227 +## Installation
227 228 sudo apt-get install nginx
228 229  
229   - # Add GitLab to nginx sites & change with your host specific settings
  230 +## Site Configuration
  231 +
  232 +Download an example site config:
  233 +
230 234 sudo wget https://raw.github.com/gitlabhq/gitlab-recipes/master/nginx/gitlab -P /etc/nginx/sites-available/
231 235 sudo ln -s /etc/nginx/sites-available/gitlab /etc/nginx/sites-enabled/gitlab
232 236  
  237 +Make sure to edit the config file to match your setup:
  238 +
233 239 # Change **YOUR_SERVER_IP** and **YOUR_SERVER_FQDN**
234 240 # to the IP address and fully-qualified domain name
235   - # of the host serving GitLab.
  241 + # of your host serving GitLab
236 242 sudo vim /etc/nginx/sites-enabled/gitlab
237 243  
238   - # Restart nginx:
  244 +## Restart
  245 +
239 246 sudo /etc/init.d/nginx restart
240 247  
241 248  
242   -# Done! Visit YOUR_SERVER for gitlab instance
  249 +# Done!
243 250  
244   -You can login via web using admin generated with setup:
  251 +Visit YOUR_SERVER for your first GitLab login.
  252 +The setup has created an admin account for you. You can use it to log in:
245 253  
246 254 admin@local.host
247 255 5iveL!fe
248 256  
  257 +**Important Note**
  258 +Please go over to your profile page and immediately chage the password, so
  259 +nobody can access your GitLab by using this login information later on.
  260 +
  261 +**Enjoy!**
  262 +
249 263  
250 264 - - -
251 265  
252 266  
253 267 # Advanced setup tips:
254 268  
255   -## Customizing Resque's Redis connection
  269 +## Custom Redis connections
256 270  
257 271 If you'd like Resque to connect to a Redis server on a non-standard port or on
258   -a different host, you can configure its connection string in the
259   -**config/resque.yml** file:
260   -
261   - production: redis.example.com:6379
  272 +a different host, you can configure its connection string via the
  273 +`config/resque.yml` file.
262 274  
263   -**Ok - we have a working application now. **
264   -**But keep going - there are some things that should be done **
  275 + # example
  276 + production: redis.example.tld:6379
... ...