installation.md 8.29 KB
Newer Older
1 2
This installation guide was created for Debian/Ubuntu and tested on it.

3
Please read `doc/install/requirements.md` for hardware and platform requirements.
Valery Sizov's avatar
Valery Sizov committed
4

Dmitriy Zaporozhets's avatar
Dmitriy Zaporozhets committed
5

6
**Important Note:**
Riyad Preukschas's avatar
Riyad Preukschas committed
7 8 9
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.
10 11 12 13 14 15 16
For things like AWS installation scripts, init scripts or config files for
alternative web server have a look at the "Advanced Setup Tips" section.


**Important Note:**
If you find a bug/error in this guide please submit an issue or pull request
following the contribution guide (see `CONTRIBUTING.md`).
Dmitriy Zaporozhets's avatar
Dmitriy Zaporozhets committed
17

randx's avatar
randx committed
18
- - -
Dmitriy Zaporozhets's avatar
Dmitriy Zaporozhets committed
19

Riyad Preukschas's avatar
Riyad Preukschas committed
20
# Overview
Valery Sizov's avatar
Valery Sizov committed
21

Riyad Preukschas's avatar
Riyad Preukschas committed
22
The GitLab installation consists of setting up th following components:
23

Riyad Preukschas's avatar
Riyad Preukschas committed
24
1. Packages / Dependencies
randx's avatar
randx committed
25
2. Ruby
Riyad Preukschas's avatar
Riyad Preukschas committed
26
3. System Users
randx's avatar
randx committed
27
4. Gitolite
Riyad Preukschas's avatar
Riyad Preukschas committed
28 29 30
5. Database
6. GitLab
7. Nginx
Valery Sizov's avatar
Valery Sizov committed
31 32


Riyad Preukschas's avatar
Riyad Preukschas committed
33
# 1. Packages / Dependencies
Valery Sizov's avatar
Valery Sizov committed
34

35 36 37 38
*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

Riyad Preukschas's avatar
Riyad Preukschas committed
39
Make sure your system is up-to-date:
Valery Sizov's avatar
Valery Sizov committed
40 41 42 43

    sudo apt-get update
    sudo apt-get upgrade

Riyad Preukschas's avatar
Riyad Preukschas committed
44
Install the required packages:
45

46 47 48 49 50 51 52 53 54 55 56 57 58
    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

59
    # Make sure you can access Python via python2
60 61 62 63
    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
64 65


Riyad Preukschas's avatar
Riyad Preukschas committed
66
# 2. Ruby
Valery Sizov's avatar
Valery Sizov committed
67

Riyad Preukschas's avatar
Riyad Preukschas committed
68 69 70
    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
Valery Sizov's avatar
Valery Sizov committed
71 72 73 74 75
    ./configure
    make
    sudo make install


Riyad Preukschas's avatar
Riyad Preukschas committed
76 77 78
# 3. System Users

Create a user for Git and Gitolite:
79

Valery Sizov's avatar
Valery Sizov committed
80 81 82
    sudo adduser \
      --system \
      --shell /bin/sh \
Riyad Preukschas's avatar
Riyad Preukschas committed
83
      --gecos 'Git Version Control' \
Valery Sizov's avatar
Valery Sizov committed
84 85 86 87 88
      --group \
      --disabled-password \
      --home /home/git \
      git

Riyad Preukschas's avatar
Riyad Preukschas committed
89
Create a user for GitLab:
Valery Sizov's avatar
Valery Sizov committed
90

Riyad Preukschas's avatar
Riyad Preukschas committed
91
    sudo adduser --disabled-login --gecos 'GitLab' gitlab
92

Riyad Preukschas's avatar
Riyad Preukschas committed
93
    # Add it to the git group
Dmitriy Zaporozhets's avatar
Dmitriy Zaporozhets committed
94
    sudo usermod -a -G git gitlab
95

Riyad Preukschas's avatar
Riyad Preukschas committed
96
    # Generate the SSH key
97
    sudo -u gitlab -H ssh-keygen -q -N '' -t rsa -f /home/gitlab/.ssh/id_rsa
Valery Sizov's avatar
Valery Sizov committed
98

randx's avatar
randx committed
99 100 101

# 4. Gitolite

102
Clone GitLab's fork of the Gitolite source code:
103

104
    sudo -u git -H git clone -b gl-v304 https://github.com/gitlabhq/gitolite.git /home/git/gitolite
Valery Sizov's avatar
Valery Sizov committed
105

Riyad Preukschas's avatar
Riyad Preukschas committed
106 107
Setup Gitolite with GitLab as its admin:

108
**Important Note:**
Riyad Preukschas's avatar
Riyad Preukschas committed
109
GitLab assumes *full and unshared* control over this Gitolite installation.
110

Riyad Preukschas's avatar
Riyad Preukschas committed
111
    # Add Gitolite scripts to $PATH
randx's avatar
randx committed
112 113
    cd /home/git
    sudo -u git -H mkdir bin
114 115
    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'
randx's avatar
randx committed
116

Riyad Preukschas's avatar
Riyad Preukschas committed
117
    # Copy the gitlab user's (public) SSH key ...
Valery Sizov's avatar
Valery Sizov committed
118
    sudo cp /home/gitlab/.ssh/id_rsa.pub /home/git/gitlab.pub
119
    sudo chmod 0444 /home/git/gitlab.pub
Valery Sizov's avatar
Valery Sizov committed
120

Riyad Preukschas's avatar
Riyad Preukschas committed
121
    # ... and use it as the Gitolite admin key for setup
randx's avatar
randx committed
122
    sudo -u git -H sh -c "PATH=/home/git/bin:$PATH; gitolite setup -pk /home/git/gitlab.pub"
123

Riyad Preukschas's avatar
Riyad Preukschas committed
124
Fix the directory permissions for the repository:
125

Riyad Preukschas's avatar
Riyad Preukschas committed
126
    # Make sure the repositories dir is owned by git and it stays that way
127
    sudo chmod -R ug+rwXs /home/git/repositories/
Valery Sizov's avatar
Valery Sizov committed
128 129
    sudo chown -R git:git /home/git/repositories/

Riyad Preukschas's avatar
Riyad Preukschas committed
130 131 132 133
## 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
134
    sudo -u gitlab -H git clone git@localhost:gitolite-admin.git /tmp/gitolite-admin
Valery Sizov's avatar
Valery Sizov committed
135

Riyad Preukschas's avatar
Riyad Preukschas committed
136
    # If it succeeded without errors you can remove the cloned repo
137
    sudo rm -rf /tmp/gitolite-admin
Valery Sizov's avatar
Valery Sizov committed
138

139 140
**Important Note:**
If you can't clone the `gitolite-admin` repository: **DO NOT PROCEED WITH INSTALLATION**!
141
Check the [Trouble Shooting Guide](https://github.com/gitlabhq/gitlab-public-wiki/wiki/Trouble-Shooting-Guide)
Riyad Preukschas's avatar
Riyad Preukschas committed
142
and make sure you have followed all of the above steps carefully.
Valery Sizov's avatar
Valery Sizov committed
143 144


145
# 5. Database
randx's avatar
randx committed
146

147
See `doc/install/databases.md`
randx's avatar
randx committed
148 149


randx's avatar
randx committed
150
# 6. GitLab
Valery Sizov's avatar
Valery Sizov committed
151

152
    # We'll install GitLab into home directory of the user "gitlab"
Valery Sizov's avatar
Valery Sizov committed
153
    cd /home/gitlab
154

Riyad Preukschas's avatar
Riyad Preukschas committed
155
## Clone the Source
randx's avatar
randx committed
156

Riyad Preukschas's avatar
Riyad Preukschas committed
157
    # Clone the latest stable release
158
    sudo -u gitlab -H git clone -b stable https://github.com/gitlabhq/gitlabhq.git gitlab
159

160
**Note:**
Riyad Preukschas's avatar
Riyad Preukschas committed
161 162
You can change `stable` to `master` if you want the *bleeding edge* version, but
do so with caution!
163

Riyad Preukschas's avatar
Riyad Preukschas committed
164
## Configure it
randx's avatar
randx committed
165

Riyad Preukschas's avatar
Riyad Preukschas committed
166
    cd /home/gitlab/gitlab
167

Riyad Preukschas's avatar
Riyad Preukschas committed
168
    # Copy the example GitLab config
169
    sudo -u gitlab -H cp config/gitlab.yml.example config/gitlab.yml
Valery Sizov's avatar
Valery Sizov committed
170

171 172 173 174
    # 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

Riyad Preukschas's avatar
Riyad Preukschas committed
175
    # Copy the example Unicorn config
176
    sudo -u gitlab -H cp config/unicorn.rb.example config/unicorn.rb
Andrey Kumanyaev's avatar
Andrey Kumanyaev committed
177

178
**Important Note:**
Riyad Preukschas's avatar
Riyad Preukschas committed
179 180 181
Make sure to edit both files to match your setup.

## Install Gems
182

randx's avatar
randx committed
183
    cd /home/gitlab/gitlab
184

185
    sudo gem install charlock_holmes --version '0.6.9'
randx's avatar
randx committed
186
    sudo gem install bundler
Riyad Preukschas's avatar
Riyad Preukschas committed
187
    sudo -u gitlab -H bundle install --deployment --without development test 
Valery Sizov's avatar
Valery Sizov committed
188

Riyad Preukschas's avatar
Riyad Preukschas committed
189
## Configure Git
190

Riyad Preukschas's avatar
Riyad Preukschas committed
191
GitLab needs to be able to commit and push changes to Gitolite. In order to do
192 193
that Git requires a username and email. (We recommend using the same address
used for the `email.from` setting in `config/gitlab.yml`)
194

Riyad Preukschas's avatar
Riyad Preukschas committed
195
    sudo -u gitlab -H git config --global user.name "GitLab"
196 197
    sudo -u gitlab -H git config --global user.email "gitlab@localhost"

Riyad Preukschas's avatar
Riyad Preukschas committed
198
## Setup GitLab hooks
199

Riyad Preukschas's avatar
Riyad Preukschas committed
200 201
    sudo cp ./lib/hooks/post-receive /home/git/.gitolite/hooks/common/post-receive
    sudo chown git:git /home/git/.gitolite/hooks/common/post-receive
202

Riyad Preukschas's avatar
Riyad Preukschas committed
203
## Initialise Database and Activate Advanced Features
randx's avatar
randx committed
204

Riyad Preukschas's avatar
Riyad Preukschas committed
205
    sudo -u gitlab -H bundle exec rake gitlab:app:setup RAILS_ENV=production
206 207


Riyad Preukschas's avatar
Riyad Preukschas committed
208
## Check Application Status
209

210
Check if GitLab and its environment is configured correctly:
211 212 213 214

    sudo -u gitlab -H bundle exec rake gitlab:env:info RAILS_ENV=production

To make sure you didn't miss anything run a more thorough check with:
215

216
    sudo -u gitlab -H bundle exec rake gitlab:app:status RAILS_ENV=production
Valery Sizov's avatar
Valery Sizov committed
217

218 219
If you are all green: congratulations, you successfully installed GitLab!
Although this is the case, there are still a few steps to go.
Valery Sizov's avatar
Valery Sizov committed
220 221


Riyad Preukschas's avatar
Riyad Preukschas committed
222
## Install Init Script
Valery Sizov's avatar
Valery Sizov committed
223

Riyad Preukschas's avatar
Riyad Preukschas committed
224
Download the init script (will be /etc/init.d/gitlab):
225

randx's avatar
randx committed
226 227
    sudo wget https://raw.github.com/gitlabhq/gitlab-recipes/master/init.d/gitlab -P /etc/init.d/
    sudo chmod +x /etc/init.d/gitlab
228

Riyad Preukschas's avatar
Riyad Preukschas committed
229
Make GitLab start on boot:
230

randx's avatar
randx committed
231
    sudo update-rc.d gitlab defaults 21
Dmitriy Zaporozhets's avatar
Dmitriy Zaporozhets committed
232

Riyad Preukschas's avatar
Riyad Preukschas committed
233 234

Start your GitLab instance:
Valery Sizov's avatar
Valery Sizov committed
235

randx's avatar
randx committed
236
    sudo service gitlab start
237

Valery Sizov's avatar
Valery Sizov committed
238

randx's avatar
randx committed
239
# 7. Nginx
240

241 242 243 244
**Note:**
If you can't or don't want to use Nginx as your web server, have a look at the
"Advanced Setup Tips" section.

Riyad Preukschas's avatar
Riyad Preukschas committed
245
## Installation
246
    sudo apt-get install nginx
247

Riyad Preukschas's avatar
Riyad Preukschas committed
248 249 250 251
## Site Configuration

Download an example site config:

randx's avatar
randx committed
252
    sudo wget https://raw.github.com/gitlabhq/gitlab-recipes/master/nginx/gitlab -P /etc/nginx/sites-available/
253
    sudo ln -s /etc/nginx/sites-available/gitlab /etc/nginx/sites-enabled/gitlab
Valery Sizov's avatar
Valery Sizov committed
254

Riyad Preukschas's avatar
Riyad Preukschas committed
255 256
Make sure to edit the config file to match your setup:

257 258
    # Change **YOUR_SERVER_IP** and **YOUR_SERVER_FQDN**
    # to the IP address and fully-qualified domain name
Riyad Preukschas's avatar
Riyad Preukschas committed
259
    # of your host serving GitLab
260
    sudo vim /etc/nginx/sites-enabled/gitlab
Dmitriy Zaporozhets's avatar
Dmitriy Zaporozhets committed
261

Riyad Preukschas's avatar
Riyad Preukschas committed
262 263
## Restart

264
    sudo /etc/init.d/nginx restart
Dmitriy Zaporozhets's avatar
Dmitriy Zaporozhets committed
265

266

Riyad Preukschas's avatar
Riyad Preukschas committed
267
# Done!
268

Riyad Preukschas's avatar
Riyad Preukschas committed
269 270
Visit YOUR_SERVER for your first GitLab login.
The setup has created an admin account for you. You can use it to log in:
Valery Sizov's avatar
Valery Sizov committed
271

272 273
    admin@local.host
    5iveL!fe
274

275
**Important Note:**
Riyad Preukschas's avatar
Riyad Preukschas committed
276 277 278 279 280
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!**

Valery Sizov's avatar
Valery Sizov committed
281

randx's avatar
randx committed
282 283
- - -

Valery Sizov's avatar
Valery Sizov committed
284

285
# Advanced Setup Tips
randx's avatar
randx committed
286

287
## Custom Redis Connection
288 289

If you'd like Resque to connect to a Redis server on a non-standard port or on
Riyad Preukschas's avatar
Riyad Preukschas committed
290 291
a different host, you can configure its connection string via the
`config/resque.yml` file.
292

Riyad Preukschas's avatar
Riyad Preukschas committed
293 294
    # example
    production: redis.example.tld:6379
295 296 297 298 299 300


## User-contributed Configurations

You can find things like  AWS installation scripts, init scripts or config files
for alternative web server in our [recipes collection](https://github.com/gitlabhq/gitlab-recipes/).