Updated by Linode
Use promo code DOCS10 for $10 credit on a new account.
GitLab is a free Git repository management application, like GitHub or Bitbucket, that you can run on your own Linode. This guide will show you how to install GitLab using the official GitLab Docker image.
The GitLab application has a number of services it depends on, including PostgreSQL, Nginx, and Redis. A major benefit of using Docker to install GitLab is that these dependencies are isolated to a single easy-to-update and self-contained image.
Before You Begin
Choose An Appropriately Sized Linode
GitLab is a resource-intensive application. To get the most out of GitLab, we recommend a Linode with at least 8GB of memory and at least 2 CPU cores. For more information on system requirements, visit the GitLab Hardware Requirements page.
NoteThis guide was written for and tested with Ubuntu 18.04. You may be able to adapt this guide to other operating systems supported by Docker. When following this guide under another OS, use the Docker installation instructions for that OS.
Secure your Server
Review and implement the measures in the How to Secure your Server guide, including creating a limited user account.
Change your Linode’s Default SSH Port
One of GitLab’s features is the ability for you to push and fetch code changes to and from your repository over SSH. When installing GitLab, the software will need to bind to port 22, which is the standard port for SSH. Your system’s SSH service already runs on this port by default, so you will receive an error from GitLab if you don’t address this conflict.
To fix this, you’ll want to change the port that your system’s SSH service listens on. This can be accomplished by editing your Linode’s
/etc/ssh/sshd_config file and changing the
Port assignment. The example snippet below changes the port from 22 to port 26:
When editing the file, you may also need to uncomment the
Port line by removing the
# character from the start of the line, if one is present. After updating this file and saving the change, restart the SSH service:
sudo systemctl restart sshd
Close your current SSH session and create a new one, making sure to specify the new port. You can do this by supplying the
ssh email@example.com -p 26
(Optional) Update your DNS Records
Assign a domain or subdomain to your GitLab server. This step is optional, as you can always access GitLab via your server’s IP address. However, using a domain is necessary if you would like to take advantage of GitLab’s built in SSL support, which uses Let’s Encrypt to issue certificates. This guide’s examples will use
It takes some time for DNS changes to propagate through the internet, so it’s suggested that you do this before you set up GitLab. There are several options for updating your DNS records:
If you already use Linode’s name servers, or if you would like to use them for your domain, review the DNS Manager guide. You will need to set up an A record which is assigned your Linode’s IP address.
If you use a different DNS provider, review that provider’s documentation for setting up a new A record.
Updating DNS records at common nameserver authorities
The following support documents describe how to update DNS records at common nameserver authorities:
You can test to see if your DNS changes have propagated with the
dig +short gitlab.example.com
Once your changes have propagated, you can move forward with the installation.
You must have Docker installed on your Linode to continue.
These steps install Docker Community Edition (CE) using the official Ubuntu repositories. To install on another distribution, see the official installation page.
Remove any older installations of Docker that may be on your system:
sudo apt remove docker docker-engine docker.io
Make sure you have the necessary packages to allow the use of Docker’s repository:
sudo apt install apt-transport-https ca-certificates curl software-properties-common
Add Docker’s GPG key:
curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo apt-key add -
Verify the fingerprint of the GPG key:
sudo apt-key fingerprint 0EBFCD88
You should see output similar to the following:
pub 4096R/0EBFCD88 2017-02-22 Key fingerprint = 9DC8 5822 9FC7 DD38 854A E2D8 8D81 803C 0EBF CD88 uid Docker Release (CE deb)
sub 4096R/F273FCD8 2017-02-22
sudo add-apt-repository "deb [arch=amd64] https://download.docker.com/linux/ubuntu $(lsb_release -cs) stable"
Update your package index and install Docker CE:
sudo apt update sudo apt install docker-ce
Add your limited Linux user account to the
sudo usermod -aG docker $USER
After entering the
usermodcommand, you will need to close your SSH session and open a new one for this change to take effect.
Check that the installation was successful by running the built-in “Hello World” program:
docker run hello-world
Install the GitLab EE Image
After installing Docker, download the latest GitLab Enterprise Edition Docker image from DockerHub. This image contains everything GitLab needs in order to run: PostgreSQL, Nginx, Redis, etc. To download the image, run the following
sudo docker pull gitlab/gitlab-ee:latest
Community Edition or Enterprise Edition?
The GitLab Enterprise Edition software does not actually require you to have a license to use it. If you do not supply a license after installation, it will automatically show you the GitLab Community Edition feature set instead.
If you’d like, you can instead opt to download GitLab Community Edition. This will offer the same features as an unlicensed Enterprise Edition installation. The key difference between these software packages is that the features of the EE installation can be upgraded at any time by entering a license.
The primary reason someone might download the Community Edition is if they prefer to only download open source software. For more information on GitLab’s licensing, review the GitLab article on this subject. To download the GitLab CE Docker image, run this command:
sudo docker pull gitlab/gitlab-ce:latest
It may take a few minutes to download the image. When the download is complete, you can view a list of all installed Docker images with the
sudo docker images
Configure and Run GitLab
In order to configure and run the GitLab container, you need to provide a few options at runtime.
Consider the following command, a version of which you will use to start the GitLab container:
sudo docker run --detach --hostname gitlab.example.com --publish 443:443 --publish 80:80 --publish 22:22 --name gitlab-linode --restart always --volume /srv/gitlab/config:/etc/gitlab --volume /srv/gitlab/logs:/var/log/gitlab --volume /srv/gitlab/data:/var/opt/gitlab --env GITLAB_OMNIBUS_CONFIG="external_url 'https://gitlab.example.com/';" gitlab/gitlab-ee:latest
Descriptions for each option
--detachruns the Docker container as a background process, as opposed to running it in the foreground.
--hostnamedefines the container’s internal hostname.
--publishtells the container to publish ports, or ranges of ports, to the host. Because GitLab accepts connections on the HTTP (80), HTTPS (443), and SSH (22) ports, this option is declared three times. If you wanted to access GitLab from a non-standard port on your host, you would provide the host port first, and the container port second after the semi-colon. For instance if you wanted to access GitLab SSH on port 3333, you would write
--nameallows you to apply a label to your container, for use when referencing the container within a Docker network.
--restartspecifies a restart policy for the container. Here it is set to
always, meaning that the container, if exited, will automatically be restarted.
--volumedefines the host mounted volumes the container uses to store persistent data. These three volumes store application data, log files, and configuration files. The value to the left of the the semi-colon is the local location, and the value to the right is the container location.
--envsupplies the variable
GITLAB_OMNIBUS_CONFIG, which can hold a series of values, separated by a colon, that correspond to the GitLab Omnibus configuration settings. In this case, an external URL is supplied. Some additional settings might include SMTP configuration values so that GitLab can send activity emails.
As of GitLab 10.7, if you provide an external URL with a HTTPS protocol, GitLab will automatically set up SSL certificates using Let’s Encrypt, and all traffic will be forwarded to HTTPS. For more information about this functionality, read the GitLab SSL Documentation
As an alternative to specifying the
GITLAB_OMNIBUS_CONFIGvariable via the
--envoption, you can edit the GitLab configuration file directly. For more instructions on how to do that, visit the Configure GitLab documentation.
In the above command, replace the values for the
--hostnameoption and for the
external_urlconfiguration setting with the domain or subdomain for your GitLab site. If you did not set up DNS for your site, enter
https) for the
external_urlsetting. Then, run the command.
If you are using the GitLab Community Edition image, replace
The container may take a few moments to start. After it starts, you’ll be given a container ID like the following:
It will take an additional few minutes to be able to access GitLab in your browser after the container starts. You can find out more information about the startup process by monitoring the logs:
sudo docker logs -f gitlab-linode
To exit from the log monitoring process, enter
CTRL-C. This will not stop the container from running.
Load the GitLab site in your web browser. If you try to load it too shortly after starting the container, you may see an HTTP 502 error. If this happens, try waiting for a few more minutes and then refresh your page.
The first time you access the site it will prompt you to enter an administrative password. Enter a complex password and record it somewhere safe.
Log in to your GitLab site by entering
rootas the user along with the password you created in the previous step.
Create your First Project
Each repository in GitLab belongs to a project. A project includes: a repository for your files, an issues tracker, a section for merge requests, a wiki, continuous integration and continuous delivery (CI/CD) pipelines, and other features to support your development.
To create your first repository, click Create a project.
You will be taken to the New Project page. Enter the project name. You can optionally alter the project’s slug, enter a description, or change the visibility of the project. Once you’re done, click Create project.
Once your project has been created, you’ll be provided with an empty project repository:
If you didn’t have GitLab create a
README.mdfile during project setup, instructions on how to start using your repository from the command line will be shown.
Enter those commands on your computer to add a new
README.mdto your repository and push it back up to your GitLab repository. Change the domain in the
git clonecommand to your site’s domain:
git clone https://gitlab.example.com/testuser/example-project.git cd example-project touch README.md # Or create the file in your editor and enter a project description git add README.md git commit -m "add README" git push -u origin master
Manage the GitLab Container
To view all of your running containers, you can issue the
sudo docker ps
To stop the GitLab container, issue the
stop command by supplying the container ID you procured with the
ps command, or supply the container name:
sudo docker stop gitlab-linode
To start a stopped container, issue the
start command by supplying the container ID or container name:
sudo docker start gitlab-linode
Once the container has stopped, you can remove the container using the
rm command, again supplying the container ID or container name:
sudo docker container rm gitlab-linode
Removing the container will not delete your projects and repositories.
To upgrade GitLab to the newest version, you must stop and remove the container, pull the newest image, and then recreate the container:
sudo docker stop gitlab-linode sudo docker rm gitlab-linode sudo docker pull gitlab/gitlab-ee:latest sudo docker run --detach --hostname gitlab.example.com --publish 443:443 --publish 80:80 --publish 22:22 --name gitlab-linode --restart always --volume /srv/gitlab/config:/etc/gitlab --volume /srv/gitlab/logs:/var/log/gitlab --volume /srv/gitlab/data:/var/opt/gitlab --env GITLAB_OMNIBUS_CONFIG="external_url 'https://gitlab.example.com/';" gitlab/gitlab-ee:latest
Remember to provide your own hostname, name, and external URL. If you are using GitLab Community Edition, specify the
gitlab/gitlab-ce:latest image instead.
GitLab offers many features that are worth taking the time to understand and utilize. Here are a few next steps to take after you’ve completed this guide:
Upload an SSH key to your GitLab account so that you can transfer files over SSH.
Explore CI/CD pipelines to streamline your development practices.
rootGitLab account, explore the Admin settings to customize the functionality of GitLab.
Review Linode’s Git documentation:
You may wish to consult the following resources for additional information on this topic. While these are provided in the hope that they will be useful, please note that we cannot vouch for the accuracy or timeliness of externally hosted materials.
Find answers, ask questions, and help others.
This guide is published under a CC BY-ND 4.0 license.