doc/install/installation.md

   1 # Select Version to Install
   2 Make sure you view this installation guide from the branch (version) of GitLab you would like to install. In most cases
   3 this should be the highest numbered stable branch (example shown below).
   4
   5 ![capture](https://f.cloud.github.com/assets/1192780/564911/2f9f3e1e-c5b7-11e2-9f89-98e527d1adec.png)
   6
   7 If this is unclear check the [GitLab Blog](http://blog.gitlab.org/) for installation guide links by version.
   8
   9 # Important notes
  10
  11 This installation guide was created for and tested on **Debian/Ubuntu** operating systems. Please read [`doc/install/requirements.md`](./requirements.md) for hardware and operating system requirements.
  12
  13 This is the official installation guide to set up a production server. To set up a **development installation** or for many other installation options please consult [the installation section in the readme](https://github.com/gitlabhq/gitlabhq#installation).
  14
  15 The following steps have been known to work. Please **use caution when you deviate** from this guide. Make sure you don't violate any assumptions GitLab makes about its environment. For example many people run into permission problems because they changed the location of directories or run services as the wrong user.
  16
  17 If you find a bug/error in this guide please **submit a pull request** following the [contributing guide](../../CONTRIBUTING.md).
  18
  19 - - -
  20
  21 # Overview
  22
  23 The GitLab installation consists of setting up the following components:
  24
  25 1. Packages / Dependencies
  26 2. Ruby
  27 3. System Users
  28 4. GitLab shell
  29 5. Database
  30 6. GitLab
  31 7. Nginx
  32
  33
  34 # 1. Packages / Dependencies
  35
  36 `sudo` is not installed on Debian by default. Make sure your system is
  37 up-to-date and install it.
  38
  39     # run as root!
  40     apt-get update -y
  41     apt-get upgrade -y
  42     apt-get install sudo -y
  43
  44 **Note:**
  45 During this installation some files will need to be edited manually.
  46 If you are familiar with vim set it as default editor with the commands below.
  47 If you are not familiar with vim please skip this and keep using the default editor.
  48
  49     # Install vim and set as default editor
  50     sudo apt-get install -y vim
  51     sudo update-alternatives --set editor /usr/bin/vim.basic
  52
  53 Install the required packages:
  54
  55     sudo apt-get install -y build-essential zlib1g-dev libyaml-dev libssl-dev libgdbm-dev libreadline-dev libncurses5-dev libffi-dev curl openssh-server redis-server checkinstall libxml2-dev libxslt-dev libcurl4-openssl-dev libicu-dev logrotate
  56
  57 Make sure you have the right version of Python installed.
  58
  59     # Install Python
  60     sudo apt-get install -y python
  61
  62     # Make sure that Python is 2.5+ (3.x is not supported at the moment)
  63     python --version
  64
  65     # If it's Python 3 you might need to install Python 2 separately
  66     sudo apt-get install -y python2.7
  67
  68     # Make sure you can access Python via python2
  69     python2 --version
  70
  71     # If you get a "command not found" error create a link to the python binary
  72     sudo ln -s /usr/bin/python /usr/bin/python2
  73
  74     # For reStructuredText markup language support install required package:
  75     sudo apt-get install -y python-docutils
  76
  77 Make sure you have the right version of Git installed
  78
  79     # Install Git
  80     sudo apt-get install -y git-core
  81
  82     # Make sure Git is version 1.7.10 or higher, for example 1.7.12 or 1.8.4
  83     git --version
  84
  85 Is the system packaged Git too old? Remove it and compile from source.
  86
  87     # Remove packaged Git
  88     sudo apt-get remove git-core
  89
  90     # Install dependencies
  91     sudo apt-get install -y libcurl4-openssl-dev libexpat1-dev gettext libz-dev libssl-dev build-essential
  92
  93     # Download and compile from source
  94     cd /tmp
  95     curl --progress https://git-core.googlecode.com/files/git-1.8.4.1.tar.gz | tar xz
  96     cd git-1.8.4.1/
  97     make prefix=/usr/local all
  98
  99     # Install into /usr/local/bin
 100     sudo make prefix=/usr/local install
 101
 102     # When editing config/gitlab.yml (Step 6), change the git bin_path to /usr/local/bin/git
 103
 104 **Note:** In order to receive mail notifications, make sure to install a
 105 mail server. By default, Debian is shipped with exim4 whereas Ubuntu
 106 does not ship with one. The recommended mail server is postfix and you can install it with:
 107
 108         sudo apt-get install -y postfix
 109
 110 Then select 'Internet Site' and press enter to confirm the hostname.
 111
 112 # 2. Ruby
 113
 114 Remove the old Ruby 1.8 if present
 115
 116     sudo apt-get remove ruby1.8
 117
 118 Download Ruby and compile it:
 119
 120     mkdir /tmp/ruby && cd /tmp/ruby
 121     curl --progress ftp://ftp.ruby-lang.org/pub/ruby/2.0/ruby-2.0.0-p353.tar.gz | tar xz
 122     cd ruby-2.0.0-p353
 123     ./configure --disable-install-rdoc
 124     make
 125     sudo make install
 126
 127 Install the Bundler Gem:
 128
 129     sudo gem install bundler --no-ri --no-rdoc
 130
 131
 132 # 3. System Users
 133
 134 Create a `git` user for Gitlab:
 135
 136     sudo adduser --disabled-login --gecos 'GitLab' git
 137
 138
 139 # 4. GitLab shell
 140
 141 GitLab Shell is an ssh access and repository management software developed specially for GitLab.
 142
 143     # Go to home directory
 144     cd /home/git
 145
 146     # Clone gitlab shell
 147     sudo -u git -H git clone https://github.com/gitlabhq/gitlab-shell.git -b v1.7.9
 148
 149     cd gitlab-shell
 150
 151     sudo -u git -H cp config.yml.example config.yml
 152
 153     # Edit config and replace gitlab_url
 154     # with something like 'http://domain.com/'
 155     sudo -u git -H editor config.yml
 156
 157     # Do setup
 158     sudo -u git -H ./bin/install
 159
 160
 161 # 5. Database
 162
 163 To setup the MySQL/PostgreSQL database and dependencies please see [`doc/install/databases.md`](./databases.md).
 164
 165
 166 # 6. GitLab
 167
 168     # We'll install GitLab into home directory of the user "git"
 169     cd /home/git
 170
 171 ## Clone the Source
 172
 173     # Clone GitLab repository
 174     sudo -u git -H git clone https://github.com/gitlabhq/gitlabhq.git -b 6-3-stable gitlab
 175
 176     # Go to gitlab dir
 177     cd /home/git/gitlab
 178
 179 **Note:**
 180 You can change `6-3-stable` to `master` if you want the *bleeding edge* version, but never install master on a production server!
 181
 182 ## Configure it
 183
 184     cd /home/git/gitlab
 185
 186     # Copy the example GitLab config
 187     sudo -u git -H cp config/gitlab.yml.example config/gitlab.yml
 188
 189     # Make sure to change "localhost" to the fully-qualified domain name of your
 190     # host serving GitLab where necessary
 191     #
 192     # If you installed Git from source, change the git bin_path to /usr/local/bin/git
 193     sudo -u git -H editor config/gitlab.yml
 194
 195     # Make sure GitLab can write to the log/ and tmp/ directories
 196     sudo chown -R git log/
 197     sudo chown -R git tmp/
 198     sudo chmod -R u+rwX  log/
 199     sudo chmod -R u+rwX  tmp/
 200
 201     # Create directory for satellites
 202     sudo -u git -H mkdir /home/git/gitlab-satellites
 203
 204     # Create directories for sockets/pids and make sure GitLab can write to them
 205     sudo -u git -H mkdir tmp/pids/
 206     sudo -u git -H mkdir tmp/sockets/
 207     sudo chmod -R u+rwX  tmp/pids/
 208     sudo chmod -R u+rwX  tmp/sockets/
 209
 210     # Create public/uploads directory otherwise backup will fail
 211     sudo -u git -H mkdir public/uploads
 212     sudo chmod -R u+rwX  public/uploads
 213
 214     # Copy the example Unicorn config
 215     sudo -u git -H cp config/unicorn.rb.example config/unicorn.rb
 216
 217     # Enable cluster mode if you expect to have a high load instance
 218     # Ex. change amount of workers to 3 for 2GB RAM server
 219     sudo -u git -H editor config/unicorn.rb
 220
 221     # Copy the example Rack attack config
 222     sudo -u git -H cp config/initializers/rack_attack.rb.example config/initializers/rack_attack.rb
 223
 224     # Configure Git global settings for git user, useful when editing via web
 225     # Edit user.email according to what is set in gitlab.yml
 226     sudo -u git -H git config --global user.name "GitLab"
 227     sudo -u git -H git config --global user.email "gitlab@localhost"
 228     sudo -u git -H git config --global core.autocrlf input
 229
 230 **Important Note:**
 231 Make sure to edit both `gitlab.yml` and `unicorn.rb` to match your setup.
 232
 233 ## Configure GitLab DB settings
 234
 235     # Mysql
 236     sudo -u git cp config/database.yml.mysql config/database.yml
 237
 238     # Make sure to update username/password in config/database.yml.
 239     # You only need to adapt the production settings (first part).
 240     # If you followed the database guide then please do as follows:
 241     # Change 'secure password' with the value you have given to $password
 242     # You can keep the double quotes around the password
 243     sudo -u git -H editor config/database.yml
 244
 245     or
 246
 247     # PostgreSQL
 248     sudo -u git cp config/database.yml.postgresql config/database.yml
 249
 250
 251     # Make config/database.yml readable to git only
 252     sudo -u git -H chmod o-rwx config/database.yml
 253
 254 ## Install Gems
 255
 256     cd /home/git/gitlab
 257
 258     # For MySQL (note, the option says "without ... postgres")
 259     sudo -u git -H bundle install --deployment --without development test postgres aws
 260
 261     # Or for PostgreSQL (note, the option says "without ... mysql")
 262     sudo -u git -H bundle install --deployment --without development test mysql aws
 263
 264
 265 ## Initialize Database and Activate Advanced Features
 266
 267     sudo -u git -H bundle exec rake gitlab:setup RAILS_ENV=production
 268
 269     # Type 'yes' to create the database.
 270
 271     # When done you see 'Administrator account created:'
 272
 273
 274 ## Install Init Script
 275
 276 Download the init script (will be /etc/init.d/gitlab):
 277
 278     sudo cp lib/support/init.d/gitlab /etc/init.d/gitlab
 279
 280 And if you are installing with a non-default folder or user copy and edit the defaults file:
 281
 282     sudo cp lib/support/init.d/gitlab.default.example /etc/default/gitlab
 283
 284 If you installed gitlab in another directory or as a user other than the default you should change these settings in /etc/default/gitlab. Do not edit /etc/init.d/gitlab as it will be changed on upgrade.
 285
 286 Make GitLab start on boot:
 287
 288     sudo update-rc.d gitlab defaults 21
 289
 290 ## Set up logrotate
 291
 292     sudo cp lib/support/logrotate/gitlab /etc/logrotate.d/gitlab
 293
 294 ## Check Application Status
 295
 296 Check if GitLab and its environment are configured correctly:
 297
 298     sudo -u git -H bundle exec rake gitlab:env:info RAILS_ENV=production
 299
 300 ## Start Your GitLab Instance
 301
 302     sudo service gitlab start
 303     # or
 304     sudo /etc/init.d/gitlab restart
 305
 306
 307 ## Compile assets
 308
 309     sudo -u git -H bundle exec rake assets:precompile RAILS_ENV=production
 310
 311
 312 # 7. Nginx
 313
 314 **Note:**
 315 Nginx is the officially supported web server for GitLab. If you cannot or do not want to use Nginx as your web server, have a look at the
 316 [GitLab recipes](https://github.com/gitlabhq/gitlab-recipes).
 317
 318 ## Installation
 319     sudo apt-get install -y nginx
 320
 321 ## Site Configuration
 322
 323 Download an example site config:
 324
 325     sudo cp lib/support/nginx/gitlab /etc/nginx/sites-available/gitlab
 326     sudo ln -s /etc/nginx/sites-available/gitlab /etc/nginx/sites-enabled/gitlab
 327
 328 Make sure to edit the config file to match your setup:
 329
 330     # Change YOUR_SERVER_FQDN to the fully-qualified
 331     # domain name of your host serving GitLab.
 332     sudo editor /etc/nginx/sites-available/gitlab
 333
 334 ## Restart
 335
 336     sudo service nginx restart
 337
 338
 339 # Done!
 340
 341 ## Double-check Application Status
 342
 343 To make sure you didn't miss anything run a more thorough check with:
 344
 345     sudo -u git -H bundle exec rake gitlab:check RAILS_ENV=production
 346
 347 If all items are green, then congratulations on successfully installing GitLab!
 348
 349 ## Initial Login
 350
 351 Visit YOUR_SERVER in your web browser for your first GitLab login.
 352 The setup has created an admin account for you. You can use it to log in:
 353
 354     admin@local.host
 355     5iveL!fe
 356
 357 **Important Note:**
 358 Please go over to your profile page and immediately change the password, so
 359 nobody can access your GitLab by using this login information later on.
 360
 361 **Enjoy!**
 362
 363
 364 - - -
 365
 366
 367 # Advanced Setup Tips
 368
 369 ## Custom Redis Connection
 370
 371 If you'd like Resque to connect to a Redis server on a non-standard port or on
 372 a different host, you can configure its connection string via the
 373 `config/resque.yml` file.
 374
 375     # example
 376     production: redis://redis.example.tld:6379
 377
 378 If you want to connect the Redis server via socket, then use the "unix:" URL scheme
 379 and the path to the Redis socket file in the `config/resque.yml` file.
 380
 381     # example
 382     production: unix:/path/to/redis/socket
 383
 384 ## Custom SSH Connection
 385
 386 If you are running SSH on a non-standard port, you must change the gitlab user's SSH config.
 387
 388     # Add to /home/git/.ssh/config
 389     host localhost          # Give your setup a name (here: override localhost)
 390         user git            # Your remote git user
 391         port 2222           # Your port number
 392         hostname 127.0.0.1; # Your server name or IP
 393
 394 You also need to change the corresponding options (e.g. ssh_user, ssh_host, admin_uri) in the `config\gitlab.yml` file.
 395
 396 ## LDAP authentication
 397
 398 You can configure LDAP authentication in config/gitlab.yml. Please restart GitLab after editing this file.
 399
 400 ## Using Custom Omniauth Providers
 401
 402 GitLab uses [Omniauth](http://www.omniauth.org/) for authentication and already ships with a few providers preinstalled (e.g. LDAP, GitHub, Twitter). But sometimes that is not enough and you need to integrate with other authentication solutions. For these cases you can use the Omniauth provider.
 403
 404 ### Steps
 405
 406 These steps are fairly general and you will need to figure out the exact details from the Omniauth provider's documentation.
 407
 408 * Stop GitLab
 409                 `sudo service gitlab stop`
 410
 411 * Add provider specific configuration options to your `config/gitlab.yml` (you can use the [auth providers section of the example config](https://github.com/gitlabhq/gitlabhq/blob/master/config/gitlab.yml.example) as a reference)
 412
 413 * Add the gem to your [Gemfile](https://github.com/gitlabhq/gitlabhq/blob/master/Gemfile)
 414                 `gem "omniauth-your-auth-provider"`
 415 * If you're using MySQL, install the new Omniauth provider gem by running the following command:
 416                 `sudo -u git -H bundle install --without development test postgres --path vendor/bundle --no-deployment`
 417
 418 * If you're using PostgreSQL, install the new Omniauth provider gem by running the following command:
 419                 `sudo -u git -H bundle install --without development test mysql --path vendor/bundle --no-deployment`
 420
 421 > These are the same commands you used in the [Install Gems section](#install-gems) with `--path vendor/bundle --no-deployment` instead of `--deployment`.
 422
 423 * Start GitLab
 424                 `sudo service gitlab start`
 425
 426
 427 ### Examples
 428
 429 If you have successfully set up a provider that is not shipped with GitLab itself, please let us know.
 430 You can help others by reporting successful configurations and probably share a few insights or provide warnings for common errors or pitfalls by sharing your experience [in the public Wiki](https://github.com/gitlabhq/gitlab-public-wiki/wiki/Custom-omniauth-provider-configurations).
 431 While we can't officially support every possible auth mechanism out there, we'd like to at least help those with special needs.