Omnibus GitLab is a software package (or software stack) that allows you to easily install and run GitLab on your Linode. This guide walks you through the process of installing and setting up your own nginx server on a typical Omnibus installation. Using the method outlined here, you are not forced to use Omnibus’s default settings, and can create as many virtual hosts as you need for hosting multiple websites and apps on the same server as your GitLab.
Preconfigured software stacks sometimes bring a series of challenges to those who need to customize specific settings. If you require more control over your installation, consider installing GitLab from source. This application stack could benefit from large amounts of disk space, so also consider using our Block Storage service with this setup.
Before You BeginPermalink
- Familiarize yourself with Linode’s Getting Started guide and complete the steps for setting your Linode’s hostname and timezone.
- Complete the sections of our Securing Your Server guide to create a standard user account, harden SSH access and remove unnecessary network services.
- This guide has been tested with Ubuntu 14.04 LTS and 16.04 LTS. Some commands will be slightly different for each version, so be sure to read each step carefully for version-specific instructions.
- Update your system:
sudo apt-get update && sudo apt-get upgrade
Note
This guide is written for a non-root user. Commands that require elevated privileges are prefixed withsudo. If you’re not familiar with thesudocommand, visit our Users and Groups guide for more information.
Install Omnibus GitLabPermalink
If you’re already running an Omnibus GitLab environment upgrade to the newest version and proceed to the next section, Unbundle nginx from Omnibus. If you’re installing GitLab for the first time, continue with the steps in this section.
Note that nginx cannot be disabled in older versions of GitLab Community Edition (CE). If you currently have an older version of GitLab CE installed, we recommend that you upgrade incrementally to avoid issues.
- Install the dependencies:
sudo apt-get install curl openssh-server ca-certificates postfix - While installing Postfix, you’ll be asked to configure a few basic settings. On the first ncursesscreen, select Internet Site as the mail configuration. On the second screen, enter your fully qualified domain name (FQDN). This will be used to send email to users when configuring new accounts and resetting passwords. The rest of the mail options will be configured automatically.
- Add the GitLab CE repository and install the
gitlab-cepackage:curl -sS https://packages.gitlab.com/install/repositories/gitlab/gitlab-ce/script.deb.sh | sudo bash sudo apt-get install gitlab-ceYou can view the contents of the script in its entirety on the GitLab website if you’re hesitant to run it sight-unseen. The GitLab downloads page also contains alternative download methods if you’re still not comfortable running their script.
Unbundle nginx from Omnibus GitLabPermalink
- To unbundle nginx from GitLab, we’ll need to disable the version included in the Omnibus package. Add the following lines to
/etc/gitlab/gitlab.rb:- /etc/gitlab/gitlab.rb
-
1 2 3 4# Unbundle nginx from Omnibus GitLab nginx['enable'] = false # Set your Nginx's username web_server['external_users'] = ['www-data']
- Reconfigure GitLab to apply the changes:
sudo gitlab-ctl reconfigure
For more information on how to customize Omnibus nginx, visit the official nginx documentation.
Install Ruby, Passenger, and nginxPermalink
Now that GitLab’s bundled nginx has been disabled, the next step is to install and configure the web server from scratch.
- Since GitLab is written in Ruby, install Ruby on your system:
sudo apt-get install ruby sudo gem install rubygems-update sudo update_rubygems - We’ll also need to install Phusion Passenger, a web application server for Ruby. Install Phusion Passenger’s PGP key:
sudo apt-key adv --keyserver hkp://keyserver.ubuntu.com:80 --recv-keys 561F9B9CAC40B2F7 - Add Passenger’s APT repository by adding the following lines to
/etc/apt/sources.list.d/passenger.list:- /etc/apt/sources.list.d/passenger.list
-
1deb https://oss-binaries.phusionpassenger.com/apt/passenger trusty main
Note
If you’re using Ubuntu 16.04, replacetrustywithxenialin the above command. - Update your package repositories:
sudo apt-get update - Install Passenger and nginx:
sudo apt-get install nginx-extras passenger - Enable the new Passenger module by uncommenting the
include /etc/nginx/passenger.conf;line from the/etc/nginx/nginx.conffile:- /etc/nginx/nginx.conf
-
1include /etc/nginx/passenger.conf;
- Finally, restart nginx. On Ubuntu 14.04:
sudo service nginx restartOn Ubuntu 16.04:
sudo systemctl restart nginx
For further information, please refer to Installing Passenger + nginx on Ubuntu 14.04 LTS (with APT).
Create a New Virtual HostPermalink
In this section, we’ll create a new virtual host to serve GitLab. Since we’ve unbundled nginx, we’ll also be able to configure other virtual hosts for other websites and apps.
- Copy the default virtual host file to a new virtual host file, replacing
example.comwith your virtual host:sudo cp /etc/nginx/sites-available/default /etc/nginx/sites-available/example.com - Edit your new virtual host file to match the following, replacing
example.comwith your own hostname and do not forget to add this domain to your DNS:- /etc/nginx/sites-available/example.com (Click me for the latest “Config” file)
-
upstream gitlab-workhorse { server unix:/var/opt/gitlab/gitlab-workhorse/socket; } ## Normal HTTP host server { ## Either remove "default_server" from the listen line below, ## or delete the /etc/nginx/sites-enabled/default file. This will cause gitlab ## to be served if you visit any address that your server responds to, eg. ## the ip address of the server (http://x.x.x.x/)n 0.0.0.0:80 default_server; listen 0.0.0.0:80 default_server; listen [::]:80 default_server; server_name YOUR_SERVER_FQDN; ## Replace this with something like gitlab.example.com server_tokens off; ## Don't show the nginx version number, a security best practice root /opt/gitlab/embedded/service/gitlab-rails/public; ## See app/controllers/application_controller.rb for headers set ## Individual nginx logs for this GitLab vhost access_log /var/log/nginx/gitlab_access.log; error_log /var/log/nginx/gitlab_error.log; location / { client_max_body_size 0; gzip off; ## https://github.com/gitlabhq/gitlabhq/issues/694 ## Some requests take more than 30 seconds. proxy_read_timeout 300; proxy_connect_timeout 300; proxy_redirect off; proxy_http_version 1.1; proxy_set_header Host $http_host; proxy_set_header X-Real-IP $remote_addr; proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; proxy_set_header X-Forwarded-Proto $scheme; proxy_pass http://gitlab-workhorse; } }
- Enable your new virtual host by symbolically linking it to
sites-enabled(changeexample.com):sudo ln -s /etc/nginx/sites-available/example.com /etc/nginx/sites-enabled/example.com - Restart nginx to load your changes. On Ubuntu 14.04:
sudo service nginx restartOn Ubuntu 16.04:
sudo systemctl restart nginx - Since nginx needs to access GitLab, add the
www-datauser to thegitlab-wwwgroup:sudo usermod -aG gitlab-www www-data
Congratulations! You have turned a default Omnibus GitLab server into a multi-purpose one. To serve additional websites and apps using your newly unbundled nginx server, simply create additional virtual hosts above, and configure them to your needs. For more information, please refer to our guide on how to configure nginx.