Installing GitLab in your local network or your own PC and setting it up to work perfectly


Some Background

Online Git Hosting vs. Local Bare Repos

So you work very well using Git in your own PC and looking to get a couple of people in your local network to join with you in the project? There are couple of options available to you here: you either can initialize a bare Git repository for your project in one of the computers in your local network and have all the team members to use it as their origin repository, or you can create a repository in an online Git hosting service like GitHub and use that as your project’s central repository.

There are pros and cons in both methods. I will list some that comes to my mind.

GitHub or similar online Git hosting service.

Pros

  • You get a really nice GUI to manage your remote repositories.
  • You get an environment that encourage team work.
  • You can use “Merge Requests”/”Pull Requests” and have your team members review your code.
  • You get an issue tracking system, that heavily integrates with commits (You can mention the issue number in commit messages and the system will automatically link that commit to the mentioned issue!).
  • You can set permissions for each project member, whether they can only report issues, or develop features, or manage repository etc.

Cons

  • You have to have a working Internet connection to push your work, see issues, and collaborate with others.
  • You most likely have to pay for “Private Repositories”. You don’t really need your code to be open to the world, unless it’s a open source project, do you?
  • Even if you purchased a “Private Repository”, your code does reside in someone else’s server. Yes, yes, we trust GitHub. But what would happen should there be a security flow even they can’t controll, like Heartbleed?
  • Imagine you are an owner of a company, your employees can simply log into their GitHub account from their homes and clone the project to their own computers, can’t they? Private repositories won’t help here, as you have actually granted them access to it. You probably don’t want your employees taking the code home!

Bare repository in your own local network.

Pros

  • You control the hardware, you control the software on it.
  • You don’t need an Internet connection, just the local network is enough.
  • No one can access the repository from outside the office (Unless you explicitly made it possible.).
  • No payments are needed, you can create any number of repositories as you wish.

Cons

  • You can control it only through command line.
  • You have to use external tools for facilitating team work.
  • You will have to name a leader who will have to listen to other’s non-written requests to pull their code and merge to main branch.
  • You have to manually set user permissions on Git.
  • You have to manually set up a issue tracking system, and there won’t be any links between commits and the issues, you’ll have to map them in your mind!

What if there is something that gives you the best of both? Enter GitLab!

GitLab

GitLab is a Git repository management software, that does the same thing GitHub does, but in your own computer. It has a really beutiful GUI which makes it easy to manage remote Git repositories. Following are few options of it, in the order that they come into my mind.

  • Create and manage users.
  • Add SSH keys to user profiles, so they can securely access repositories.
  • Make repositories private, protected, or public, so that only assigned users, any registered user, or anyone can access them respectively.
  • Create branches and tags right from the GUI.
  • See commits and changes done in them.
  • Comment on commits, or comment per lines of code.
  • Receive email notifications when someone creates an issue and assign it to you, assign you to a new project, comment on one of your commits or a line of code within your commit.
  • Mention other users in your comments, so that they’ll receive notifications about them being mentioned in your comments.
  • Visualize each user’s contribution to the code base.

Apart from the above features in the software itself, you get following benefits:

  • You get a really nice GUI to manage your remote repositories.
  • You get tools that encourage team work.
  • You can use “Merge Requests”/”Pull Requests” and have your team members review your code.
  • You get a issue tracking system, that heavily integrates with commits (You can mention the issue number in commit messages and the system will automatically link that commit to the mentioned issue!).
  • You can set permissions for each project member, whether they can only report issues, or develop features, or manage repository etc.
  • You control the hardware, you control the software on it.
  • You don’t need an Internet connection, just the local network is enough.
  • No one can access the repository from outside the office (Unless you made it possible.).
  • No payments are needed, you can create any number of repositories as you wish.

Can you see what I did there? I just copied and pasted the pros sections of GitHub like online services, and having Git bare repositories in a local machine together. I think that clearly explains the value of GitLab, if not, please say it in the comments section. ๐Ÿ™‚

Above are just a few good things about using GitLab. If you’d like to see it for yourself, you can read GitLab specific articles, and search YouTube for “GitLab”; I find watching videos of a software is the best way to get a feeling about it before you even try downloading it.

GitLab also offers a SaaS (Software as a Service) option called “GitLab.com”. Just like GitHub, you can sign up for an account there and create some repositories to test it. Of course you can do your projects just using GitLab.com without even installing GitLab on your computer, but my goal is to guide you through the process of creating a GitLab server in your own work space.

Prepararing, Installing, and Configuring GitLab

I recently installed GitLab in my office. So I will just tell you the way I did it, so that you’ll be able to learn something from my first hand experience and do it yourself.

Without digging in to details, I will first just tell you the overall steps I took in order to get my GitLab installation working perfectly.

First I got a computer and installed VirtualBox in it. The operating system of this machine is not important, because we will be installing GitLab inside VirtualBox. I will explain why I used VirtualBox later. Then I created a Virtual Machine with Ubuntu as it’s operating system. Using Ubuntu as the OS of the VM is important. Then, within the VM, I downloaded the installer DEB file for GitLab and installed it. Then I made GitLab available to anyone in the same network as the host machine. Finally I did some configurations within GitLan to make it fully functional.

Yes, that’s all what I did. So let’s get into details.

The Host Machine

The host machine I used has 4 GB of RAM and a 2+ GHz Core 2 Duo processor. I am not a hardware geek, but I guess that’s about the lowest specifications that VirtualBox can run without slowing down like a sloth.

The Virtual Machine

Download and install VirtualBox in your host machine. Then create a Virtual Machine with about 1.5 GB RAM and a expandable Virtual Hard Disk. I suggest using VMDK format for the disk, as it will come handy when you back the VM up.

Once the VM is created, download Ubuntu Disk Image, load it to VM’s optical drive, and install Ubuntu on your VM. I am not going to walk you through the process of installing Ubuntu, as it is more than simple. But keep it in mind that, when you are given the option to partition the hard disk within the Ubuntu installer, just use the entire hard disk. There is no use in partitioning the virtual hard disk.

The main reason for using a VM is that GitLab uses it’s own version of Ngnix as a web server and it takes control of the port 80 of the machine you install GitLab. Installing GitLab directly on a machine, in which you might want to install Apache or any other software will make a mess; it’s not impossible to get them to co-exist, but why bother when you have an easier and more rewarding method?

The other reason for using a VM is that you can back the entire VM up for safe keeping. It is much easier than backing up GitLab alone, and when you back the VM up, you get all it’s configurations and settings with the back up archive. Should something go wrong, you only have to restore the VM, and all it’s settings and installed programs (Including GitLab) will be available.

Installing GitLab

Once Ubuntu is successfully installed in your VM, boot it up, and within the VM, navigate to GitLab’s website, and download “GitLab Community Edition” (“GitLab CE”) for Ubuntu. The version number of Ubuntu mentioned in the GitLab’s installer package doesn’t matter (When I installed GitLab, it worked fine in Ubuntu 14.04 although it said it’s for Ubuntu 12.04 in the file name.).

Once the DEB file is downloaded, go ahead and install it. I prefer to use the command line for this.

cd to-the-directory-you-downloaded-gitlab-deb
sudo dpkg -i the-name-of-gitlab-deb-file

This will install GitLab on your VM. At the end of the installation, you will be instructed to

sudo gitlab-ctl reconfigure

Now restart the VM for good meassures. Once it is back up, try going to http://localhost inside your VM.

If go to http://localhost as soon as the VM booted up, you’ll see a 502 error; don’t panic, it’s normal; GitLab need a couple of minutes to fully awaken itself.

Once the 502 error is gone, you will see a login window. The default username is “root” and the default password is “5iveL!fe”. Once you are logged in, you’ll immediately be given the chance to change the password to one of your own. Do that and turn the VM off. It’s true that the GitLab is up and running. But we got more work to do.

Making GitLab available from the network

Although GitLab is up and running, it can only be accessed within the VM yet. We need to make a couple of changes to the VM and make GitLab accessible to any machine in the network to which the host machine is connected.

Once the VM is turned off, right-click on our VM in VirtualBox manager window, and go to “Settings”. Inside the Settings window, go to the “Network” section. Here, activate two network connections. First one should be a bridge and the second should be a NAT.

GitLab Network SettingsGitLab Network Settings

Now boot the VM up again, and in it’s network manager, edit the bridged connection to have the static IP address 192.168.1.99 (Or something you like, I went with the above.).

 

To do that we need to find among the two network connections available to the VM, which is the bridged connection and which is the NAT connection. So, open up a terminal in Ubuntu, and issue following command:

ifconfig

It’ll show an output like the following:

Fining network configurations in Ubuntu.

Here we can see the IP address of “eth1” connection is 10.0.3.15. This is the NAT connection. As you can see, the IP address of the “eth0” is already 192.168.1.99, that’s because I am taking screenshots from an already configured VM. But you’ll see a different IP address here, probably within 192.168.XXX.XXX range. This is the bridged connection.

To assign a static IP address, open the network menu in Ubuntu, and click “Edit Connections…”.

Ubuntu Network Connections

That’ll show you a window titled “Network Connections”.

Ubuntu Network Connections

From this window, select the bridged connection (“eth0”), and click “Edit…”. In the window that would open, go to the “IPv4 Settings” tab, and make changes to the settings mimicking the following screenshot.

Editing Network in Ubuntu

If you want to use a different IP address than 192.168.1.99, set what you like under the “Address” column. Then restart the VM.

From here on, your GitLab installation will be accessible to any machine in the host machine’s local network by goin to http://192.168.1.99 through the web browser.

GitLab accessed from a remote PC.

Enable Email Notifications

I found how properly configure SMTP email sending in GitLab from http://blog.fizyk.net.pl/blog/configure-gitlab-with-smtp-mail-server.html, feel free to go thank him.

By enabling email notifications, you cut off the need to go to every project you are a member of and seeing if there’s anything new that you should be aware of.

We need to have a SMTP server configured for GitLab to send email through. I am using a service called “MailGun.com”, which allows up to 300 mails to be sent for free per a day. You might either want to buy their paid subscription or use an alternative; but for now MailGun is enough for me.

Choose a SMTP service you like, and acquire it’s settings.

Then open the file

/opt/gitlab/embedded/service/gitlab-rails/config/environments/production.rb

in a text editor as root, and find the string that says

config.action_mailer.delivery_method = :sendmail

and change it to this:

config.action_mailer.delivery_method = :smtp

Then go to

/opt/gitlab/embedded/service/gitlab-rails/config/initializers

You can see there is a file named “smtp_settings.rb.sample”; we need to make a copy of it. Then open the newly created file as root in a text editor. And change the settings in that file to look like the following.

if Rails.env.production?
 Gitlab::Application.config.action_mailer.delivery_method = :smtp
 ActionMailer::Base.smtp_settings = {
 address: "smtp.mailgun.org (Your SMTP server address.)",
 port: 587 (Your SMTP server port.),
 user_name: "you@sandboxXXXXX.mailgun.org (Your SMTP server username.)",
 password: "XXXXXXXXXXXXXXXXXX (Your SMTP server password.)",
 domain: "your.fake.domain (The domain you need your email to be appeared sent from.)",
 authentication: 'plain',
 enable_starttls_auto: true
 }
end

To test email sending, create another user with a legit email address, activate that account, and from the admin account create a test repository and add the new user to it as a developer, if mail configuration is done okay, the new user’s email account should get an email about himself being added to the new project.

If something goes wrong here, let me know.

Setting the static IP address as the Host Name of GitLab

GitLab automatically uses the hostname of it’s operating system as it’s host name. This is not a problem, but it’ll result in useless addresses like the following in GitLab.

GitLab Access

We need it to be like this instead:

GitLab Access

So you don’t have to remember to replace “VirtualBox-PC” with “192.168.1.99”, every time you have to use this.

To do that, open the file

/opt/gitlab/embedded/service/gitlab-rails/config/gitlab.yml

and find the string that says

host: VirtualBox-PC

This should be in the very top section of the file, so it won’t be hard to find this. Replace it with the IP address you previously selected, so that it’ll look like this:

host: 192.168.1.99

Now GitLab will use the IP address in place of hostname.

Upgrading GitLab

Upgrading GitLab is very easy. Just download the DEB file for the new version of GitLab, and install it just like you did the first time.

Remember to back the VM up before upgrading though!

Howeverv, when you upgrade your GitLab installation, the hostname we changed will be reverted to default. You will have to repeat the step “Setting the static IP address as the Host Name of GitLab” to set it again.

Backing the VM Up

I take backups of the VM in my office at the end of every working day. I suggest you do the same. To do that, first turn the VM off, and in the VirtualBox Manager, choose “File -> Export Applicance…”.

Exporting VirtualBox Appliance

Then choose the VM you need to backup (If you have more than one VMs.).

Exporting VirtualBox Appliance

Next, choose a place to save the back up. Remember to save the backup with the OVA extension.

Exporting VirtualBox Appliance

Now you know how to successfully setup GitLab, work with it, and manage it in your own local network.


14 responses to “Installing GitLab in your local network or your own PC and setting it up to work perfectly”

  1. I am having issues with the emailing. I set it up exactly as shown here and no emails ever get sent. Not sure where to look in the logs or even where the logs are to find out. Everything else worked great though

    • Hi Erik, I think the logs are stored in /opt/gitlab/embedded/logs . I am not sure though.

      However, can you tell me what is the SMTP service you used? Did you manage to get it to work elsewhere?

  2. Hi, the email settings doesn’t work for me. I’m using gitlab 7.2.1. The same settings works elsewhere (jenkins, crowd etc…)

  3. can’t seem to access it from other computers in the local network, after configuring as you mentioned here. Any tips how to debug this?

    • If you followed the instruction correctly, you should be able to access the VM from physical machines in your LAN.

      That being said, I did’t use GitLab in this manner in a long time; I am now hosting mine โ€” my company’s, actually โ€” in DigitalOcean.

  4. I tried out the GitLab-recommended Omnibus package installation method on Ubuntu 18.04 LTS in VirtualBox 5.2. If I set EXTERNAL_URL to “http://localhost”, the installation will always run endlessly till Ubuntu freezes. Any idea why and how to fix it?

    • Sorry Ryan, it’s been a long time since I did this, and I do not remember details anymore.

      I would recommend creating an account in DigitalOcean with Ubuntu as the OS, and simply install the GitLab omnibus package for Ubuntu.

      If you don’t already have an account in DigitalOcean, use my referral link https://m.do.co/c/e210d2f2ba8f , it will give you 100 USD free credit.

Leave a Reply

Your email address will not be published. Required fields are marked *