GitLab Server is an open-source version of the cloud-hosted GitLab version control used to host Git repositories. The advantage of self-hosting your repositories over cloud hosting is the total control over your code. It has all the features you can find on the cloud service making it a useful tool for your development team. It also ships with Mattermost chat service that allows your users to talk to each other and share code reviews.
This guide will teach you how to install GitLab Server using Docker on a Ubuntu 22.04 server. GitLab offers two editions – the free Community edition and the paid Enterprise edition. We will be installing the Community edition. You can upgrade it to the Enterprise edition if you want more features.
Prerequisites
-
A server running Rocky Linux 9 with at least 4GB of RAM and 4 CPU Cores to support up to 500 users.
-
A non-root user with sudo privileges.
-
A domain name configured to point to the server,
gitlab.example.com. Depending on your requirements, we will also usemattermost.example.com, andpages.example.com. -
Everything is updated.
$ sudo dnf update
-
Few packages that your system needs.
$ sudo dnf install -y wget nano unzip yum-utils policycoreutils-python-utils
Some of these packages may already be installed on your system.
Step 1 – Configure Firewall
Before installing any packages, the first step is configuring the firewall to open ports for HTTP, and HTTPS. Rocky Linux uses Firewalld Firewall. Check the firewall’s status.
$ sudo firewall-cmd --state running
The firewall works with different zones, and the public zone is the default one that we will use. List all the services and ports active on the firewall.
$ sudo firewall-cmd --zone=public --list-all
It should show the following output.
public target: default icmp-block-inversion: no interfaces: enp1s0 sources: services: cockpit dhcpv6-client ssh ports: protocols: forward: yes masquerade: no forward-ports: source-ports: icmp-blocks: rich rules:
Open the HTTP, and HTTPS ports in the firewall.
$ sudo firewall-cmd --zone=public --add-service=http $ sudo firewall-cmd --zone=public --add-service=https
Recheck the status of the firewall.
$ sudo firewall-cmd --zone=public --list-all
You should see a similar output.
public target: default icmp-block-inversion: no interfaces: enp1s0 sources: services: cockpit dhcpv6-client http https ssh ports: protocols: forward: yes masquerade: no forward-ports: source-ports: icmp-blocks: rich rules:
Make all the changes permanent and reload the firewall to enable the changes.
$ sudo firewall-cmd --runtime-to-permanent $ sudo firewall-cmd --reload
Step 2 – Install Dependencies
Before installing GitLab, it is important to install the packages that GitLab requires to function properly. All of these packages are available in the Rocky Linux repository.
Issue the following command to install the dependencies.
$ sudo dnf install -y curl policycoreutils openssh-server perl
GitLab requires a working email solution to send notification emails. There are two options for the same. One of them is to install Postfix. And the second one is to use an external SMTP service. If you want to go with the Postfix option, then install it using the command below.
$ sudo dnf install postfix
During the installation, you may be asked for the type of site. Choose Internet Site as the option to proceed and then add your server’s FQDN for mail name and press Enter to proceed. If you see any additional screens, keep pressing the Enter key to choose the default options.
You will need a lot more to configure Postfix as an SMTP server the instructions for which are out of the scope of this article. GitLab has an article on configuring Postfix which you can check.
Step 3 – Install GitLab
Download and run the GitLab repository installer script.
$ curl https://packages.gitlab.com/install/repositories/gitlab/gitlab-ee/script.rpm.sh | sudo bash
Ignore the warning about the missing pygpgme package as it is not available on Rocky Linux 9.
GitLab ships with a lot of packages which makes managing it a lot easier. For example, GitLab ships with the Nginx web server and support for creating Let’s Encrypt SSL certificates.
If you specify an external URL for your GitLab website during installation, it will automatically be configured and SSL certificates will be generated and applied. You can also specify an administrator password during the installation. If you don’t, GitLab will generate a temporary password which gets deleted automatically after a day.
We will specify both the external URL and the administrator password. Run the following command to install GitLab.
$ sudo GITLAB_ROOT_PASSWORD="" EXTERNAL_URL="https://gitlab.example.com" dnf install -y gitlab-ee
Choose a strong password for your installation. Here we are installing the GitLab Enterprise edition (gitlab-ee). If you don’t buy and apply for the license, then it will work just as fine as its free Community Edition version. But if you install the Community edition (gitlab-ce), then you will need to install the Enterprise edition again to upgrade. Therefore, we recommend going with the Enterprise edition even if you don’t want to upgrade.
Once the installation is finished, you should get a similar output.
Notes:
Default admin account has been configured with following details:
Username: root
Password: You didn't opt-in to print initial root password to STDOUT.
NOTE: Because these credentials might be present in your log files in plain text, it is highly recommended to reset the password following https://docs.gitlab.com/ee/security/reset_user_password.html#reset-your-root-password.
gitlab Reconfigured!
*. *.
*** ***
***** *****
.****** *******
******** ********
,,,,,,,,,***********,,,,,,,,,
,,,,,,,,,,,*********,,,,,,,,,,,
.,,,,,,,,,,,*******,,,,,,,,,,,,
,,,,,,,,,*****,,,,,,,,,.
,,,,,,,****,,,,,,
.,,,***,,,,
,*,.
_______ __ __ __
/ ____(_) /_/ / ____ _/ /_
/ / __/ / __/ / / __ `/ __
/ /_/ / / /_/ /___/ /_/ / /_/ /
____/_/__/_____/__,_/_.___/
Thank you for installing GitLab!
GitLab should be available at https://gitlab.example.com
For a comprehensive list of configuration options please see the Omnibus GitLab readme
https://gitlab.com/gitlab-org/omnibus-gitlab/blob/master/README.md
Help us improve the installation experience, let us know how we did with a 1 minute survey:
https://gitlab.fra1.qualtrics.com/jfe/form/SV_6kVqZANThUQ1bZb?installation=omnibus&release=16-9
Verifying : gitlab-ee-16.9.1-ee.0.el9.x86_64 1/1
Installed:
gitlab-ee-16.9.1-ee.0.el9.x86_64
Complete!
You can also install a specific version of GitLab. First, check the list of available GitLab versions.
$ sudo dnf --showduplicates list gitlab-ee*
You should get a similar output.
Available Packages gitlab-ee.x86_64 16.0.0-ee.0.el9 gitlab_gitlab-ee gitlab-ee.x86_64 16.0.1-ee.0.el9 gitlab_gitlab-ee gitlab-ee.x86_64 16.0.2-ee.0.el9 gitlab_gitlab-ee gitlab-ee.x86_64 16.0.3-ee.0.el9 gitlab_gitlab-ee gitlab-ee.x86_64 16.0.4-ee.0.el9 gitlab_gitlab-ee gitlab-ee.x86_64 16.0.5-ee.0.el9 gitlab_gitlab-ee gitlab-ee.x86_64 16.0.6-ee.0.el9 gitlab_gitlab-ee gitlab-ee.x86_64 16.0.7-ee.0.el9 gitlab_gitlab-ee gitlab-ee.x86_64 16.0.8-ee.0.el9 gitlab_gitlab-ee gitlab-ee.x86_64 16.1.0-ee.0.el9 gitlab_gitlab-ee gitlab-ee.x86_64 16.1.1-ee.0.el9 gitlab_gitlab-ee gitlab-ee.x86_64 16.1.2-ee.0.el9 gitlab_gitlab-ee gitlab-ee.x86_64 16.1.3-ee.0.el9 gitlab_gitlab-ee gitlab-ee.x86_64 16.1.4-ee.0.el9 gitlab_gitlab-ee gitlab-ee.x86_64 16.1.5-ee.0.el9 gitlab_gitlab-ee gitlab-ee.x86_64 16.1.6-ee.0.el9 gitlab_gitlab-ee gitlab-ee.x86_64 16.2.0-ee.0.el9 gitlab_gitlab-ee gitlab-ee.x86_64 16.2.1-ee.0.el9 gitlab_gitlab-ee gitlab-ee.x86_64 16.2.2-ee.0.el9 gitlab_gitlab-ee gitlab-ee.x86_64 16.2.3-ee.0.el9 gitlab_gitlab-ee gitlab-ee.x86_64 16.2.4-ee.0.el9 gitlab_gitlab-ee gitlab-ee.x86_64 16.2.5-ee.0.el9 gitlab_gitlab-ee gitlab-ee.x86_64 16.2.6-ee.0.el9 gitlab_gitlab-ee gitlab-ee.x86_64 16.2.7-ee.0.el9 gitlab_gitlab-ee gitlab-ee.x86_64 16.2.8-ee.0.el9 gitlab_gitlab-ee gitlab-ee.x86_64 16.2.9-ee.0.el9 gitlab_gitlab-ee gitlab-ee.x86_64 16.3.0-ee.0.el9 gitlab_gitlab-ee gitlab-ee.x86_64 16.3.1-ee.0.el9 gitlab_gitlab-ee gitlab-ee.x86_64 16.3.2-ee.0.el9 gitlab_gitlab-ee gitlab-ee.x86_64 16.3.3-ee.0.el9 gitlab_gitlab-ee gitlab-ee.x86_64 16.3.4-ee.0.el9 gitlab_gitlab-ee gitlab-ee.x86_64 16.3.5-ee.0.el9 gitlab_gitlab-ee gitlab-ee.x86_64 16.3.6-ee.0.el9 gitlab_gitlab-ee gitlab-ee.x86_64 16.3.7-ee.0.el9 gitlab_gitlab-ee gitlab-ee.x86_64 16.4.0-ee.0.el9 gitlab_gitlab-ee gitlab-ee.x86_64 16.4.1-ee.0.el9 gitlab_gitlab-ee gitlab-ee.x86_64 16.4.2-ee.0.el9 gitlab_gitlab-ee gitlab-ee.x86_64 16.4.3-ee.0.el9 gitlab_gitlab-ee gitlab-ee.x86_64 16.4.4-ee.0.el9 gitlab_gitlab-ee gitlab-ee.x86_64 16.4.5-ee.0.el9 gitlab_gitlab-ee gitlab-ee.x86_64 16.5.0-ee.0.el9 gitlab_gitlab-ee gitlab-ee.x86_64 16.5.1-ee.0.el9 gitlab_gitlab-ee gitlab-ee.x86_64 16.5.2-ee.0.el9 gitlab_gitlab-ee gitlab-ee.x86_64 16.5.3-ee.0.el9 gitlab_gitlab-ee gitlab-ee.x86_64 16.5.4-ee.0.el9 gitlab_gitlab-ee gitlab-ee.x86_64 16.5.6-ee.0.el9 gitlab_gitlab-ee gitlab-ee.x86_64 16.5.7-ee.0.el9 gitlab_gitlab-ee gitlab-ee.x86_64 16.5.8-ee.0.el9 gitlab_gitlab-ee gitlab-ee.x86_64 16.6.0-ee.0.el9 gitlab_gitlab-ee gitlab-ee.x86_64 16.6.1-ee.0.el9 gitlab_gitlab-ee gitlab-ee.x86_64 16.6.2-ee.0.el9 gitlab_gitlab-ee gitlab-ee.x86_64 16.6.4-ee.0.el9 gitlab_gitlab-ee gitlab-ee.x86_64 16.6.5-ee.0.el9 gitlab_gitlab-ee gitlab-ee.x86_64 16.6.6-ee.0.el9 gitlab_gitlab-ee gitlab-ee.x86_64 16.6.7-ee.0.el9 gitlab_gitlab-ee gitlab-ee.x86_64 16.7.0-ee.0.el9 gitlab_gitlab-ee gitlab-ee.x86_64 16.7.2-ee.0.el9 gitlab_gitlab-ee gitlab-ee.x86_64 16.7.3-ee.0.el9 gitlab_gitlab-ee gitlab-ee.x86_64 16.7.4-ee.0.el9 gitlab_gitlab-ee gitlab-ee.x86_64 16.7.5-ee.0.el9 gitlab_gitlab-ee gitlab-ee.x86_64 16.7.6-ee.0.el9 gitlab_gitlab-ee gitlab-ee.x86_64 16.8.0-ee.0.el9 gitlab_gitlab-ee gitlab-ee.x86_64 16.8.1-ee.0.el9 gitlab_gitlab-ee gitlab-ee.x86_64 16.8.2-ee.0.el9 gitlab_gitlab-ee gitlab-ee.x86_64 16.8.3-ee.0.el9 gitlab_gitlab-ee gitlab-ee.x86_64 16.9.0-ee.0.el9 gitlab_gitlab-ee gitlab-ee.x86_64 16.9.1-ee.0.el9 gitlab_gitlab-ee
Let us install the 16.7.0 version.
$ sudo GITLAB_ROOT_PASSWORD="" EXTERNAL_URL="https://gitlab.example.com" dnf install -y gitlab-ee-16.7.0-ee.0.el9
Check the status of GitLab and associated services.
$ sudo gitlab-ctl status
You should see the following output.
run: alertmanager: (pid 6551) 1013s; run: log: (pid 6306) 1093s run: crond: (pid 6507) 1018s; run: log: (pid 5663) 1251s run: gitaly: (pid 6479) 1020s; run: log: (pid 5297) 1419s run: gitlab-exporter: (pid 6522) 1016s; run: log: (pid 6183) 1118s run: gitlab-kas: (pid 5553) 1400s; run: log: (pid 5566) 1399s run: gitlab-workhorse: (pid 6455) 1021s; run: log: (pid 5766) 1233s run: logrotate: (pid 5181) 1434s; run: log: (pid 5189) 1433s run: nginx: (pid 6470) 1021s; run: log: (pid 5806) 1227s run: node-exporter: (pid 6515) 1017s; run: log: (pid 6150) 1124s run: postgres-exporter: (pid 6563) 1013s; run: log: (pid 6351) 1087s run: postgresql: (pid 5360) 1411s; run: log: (pid 5385) 1408s run: prometheus: (pid 6532) 1016s; run: log: (pid 6268) 1100s run: puma: (pid 5666) 1247s; run: log: (pid 5673) 1246s run: redis: (pid 5227) 1428s; run: log: (pid 5236) 1427s run: redis-exporter: (pid 6524) 1016s; run: log: (pid 6233) 1110s run: registry: (pid 6480) 1020s; run: log: (pid 5956) 1165s run: sidekiq: (pid 5692) 1241s; run: log: (pid 5700) 1240s
You can stop and start GitLab using the following commands.
$ sudo gitlab-ctl stop $ sudo gitlab-ctl start
GitLab should be up and running.
You can also stop and start an individual service using the following commands.
$ sudo gitlab-ctl stop nginx $ sudo gitlab-ctl start nginx $ sudo gitlab-ctl restart nginx
You can access your GitLab install by visiting https://gitlab.example.com in the browser. We will come back to configure GitLab in the later steps.
Step 4 – Configure SSL
GitLab stores its configuration in the /etc/gitlab/gitlab.rb file. Open it for editing.
$ sudo nano /etc/gitlab/gitlab.rb
Locate the section Let's Encrypt Integration and change the values as shown below.
letsencrypt['contact_emails'] = ['[email protected]'] # This should be an array of email addresses to add as contacts letsencrypt['auto_renew'] = true letsencrypt['auto_renew_hour'] = "12" letsencrypt['auto_renew_minute'] = "30" letsencrypt['auto_renew_day_of_month'] = "*/7"
This enables Let’s Encrypt, sets the email for receiving SSL expiry notifications, and sets the certificates to be renewed automatically every 7th day of the month and 12:30 server time.
Enable DHParam Directive
Generate a Diffie-Hellman group certificate.
$ sudo openssl dhparam -dsaparam -out /etc/gitlab/ssl/dhparams.pem 4096
Set the following option in the file.
nginx['ssl_dhparam'] = "https://www.howtoforge.com/etc/gitlab/ssl/dhparams.pem" # Path to dhparams.pem, eg. /etc/gitlab/ssl/dhparams.pem
Disable HTTP Strict Transport Security (HSTS)
Enabling HTTPS automatically enables the HSTS service. Sometimes it can cause an issue when you don’t need it later on. To disable HSTS configure the following variables.
nginx['hsts_include_subdomains'] = false
Once you are finished, save the file by pressing Ctrl X and entering Y when prompted.
Reconfigure GitLab with the new settings.
$ sudo gitlab-ctl reconfigure
This process can take some time to finish. Once finished, you can access your GitLab install by visiting https://gitlab.example.com in the browser. You should be greeted by the following login page.
Step 5 – Configure SMTP
GitLab needs to send notification emails and for that, we need to enable SMTP settings for it. If you are using Postfix, you can skip this step. Otherwise, let’s proceed.
Open the GitLab configuration file for editing.
$ sudo nano /etc/gitlab/gitlab.rb
We will use Amazon SES for our tutorial. Find the SMTP section in the file and set the values as shown below.
gitlab_rails['smtp_enable'] = true gitlab_rails['smtp_address'] = "email-smtp.region-1.amazonaws.com" gitlab_rails['smtp_port'] = 587 gitlab_rails['smtp_user_name'] = "IAMmailerKey" gitlab_rails['smtp_password'] = "IAMmailerSecret" gitlab_rails['smtp_domain'] = "example.com" gitlab_rails['smtp_authentication'] = "login" gitlab_rails['smtp_enable_starttls_auto'] = true # If your SMTP server does not like the default 'From: gitlab@localhost' you # can change the 'From' with this setting. gitlab_rails['gitlab_email_from'] = '[email protected]' gitlab_rails['gitlab_email_display_name'] = 'Howtoforge GitLab' gitlab_rails['gitlab_email_reply_to'] = '[email protected]'
You can enable SMTP connection pooling by setting the following option.
gitlab_rails['smtp_pool'] = true
This allows Sidekiq workers to reuse SMTP connections for multiple jobs.
Once you are finished, save the file by pressing Ctrl X and entering Y when prompted.
You can also encrypt SMTP authentication details. Run the following command.
sudo gitlab-rake gitlab:smtp:secret:edit EDITOR=nano
Enter the SMTP username and password in the file as shown.
user_name: 'smtp user' password: 'smtp password'
Save the file by pressing Ctrl X and entering Y when prompted.
Remove the variables gitlab_rails['smtp_user_name'], and gitlab_rails['smtp_password'] from the /etc/gitlab/gitlab.rb.
Once you have finalized the SMTP settings, reconfigure GitLab Settings.
$ sudo gitlab-ctl reconfigure
Step 6 – Configure Nginx
GitLab’s inbuilt Nginx server can be configured extensively. We will go through some of the important options.
Open the GitLab configuration file for editing.
$ sudo nano /etc/gitlab/gitlab.rb
Redirect HTTP to HTTPS.
Change the following values for redirecting HTTP to HTTPS links automatically.
nginx['redirect_http_to_https'] = true
By default, GitLab sets the Referrer-Policy header to strict-origin-when-cross-origin on all responses. Configure the following variable to set this header to a different value.
nginx['referrer_policy'] = 'same-origin'
Insert Custom Nginx settings into the GitLab server block
Use the following variable to insert custom settings into the GitLab server block.
# Example: block raw file downloads from a specific repository
nginx['custom_gitlab_server_config'] = "location ^~ /foo-namespace/bar-project/raw/ {n deny all;n}n"
Insert custom settings into the Nginx configuration
Use the following setting to insert custom settings.
# Example: include a directory to scan for additional config files nginx['custom_nginx_config'] = "include /etc/gitlab/nginx/sites-enabled/*.conf;"
Create the /etc/gitlab/nginx/sites-available directory.
$ sudo mkdir /etc/gitlab/nginx/sites-available
Create the block file in it.
$ sudo touch /etc/gitlab/nginx/sites-enabled/example.conf
Edit it and add your settings.
$ sudo nano /etc/gitlab/nginx/sites-enabled/example.conf
Once finished, go back to the terminal, and run the following command to create the /etc/gitlab/nginx/sites-enabled directory.
$ sudo mkdir /etc/gitlab/nginx/sites-enabled
Run the following command to create a symlink.
sudo ln -s /etc/gitlab/nginx/sites-available/example.conf /etc/gitlab/nginx/sites-enabled/example.conf
Once you have finished configuring Nginx, save the file by pressing Ctrl X and entering Y when prompted.
Reconfigure GitLab Settings.
$ sudo gitlab-ctl reconfigure
Step 7 – Enable Container Registry
The container registry is automatically enabled and available on your GitLab domain, port 5050 if you’re using the built-in Let’s Encrypt integration.
Open the GitLab configuration file.
$ sudo nano /etc/gitlab/gitlab.rb
Set the external URL for your GitLab container registry.
registry_external_url 'https://gitlab.example.com:5050'
Set the HTTP to HTTPS redirection by adding the following line below the above one.
registry_nginx['redirect_http_to_https'] = true
Save the file by pressing Ctrl X and entering Y when prompted.
Reconfigure GitLab Settings.
$ sudo gitlab-ctl reconfigure
Open port 2425 in the firewall.
$ sudo firewall-cmd --zone=public --add-port=5050/tcp $ sudo firewall-cmd --runtime-to-permanent $ sudo firewall-cmd --reload
Validate using the following command.
$ openssl s_client -showcerts -servername gitlab.example.com -connect gitlab.example.com:5050 > cacert.pem
You should be able to sign in to the container registry from Docker with your GitLab credentials using the following command.
$ docker login gitlab.example.com:5050
You can use a different URL like https://registry.gitlab.example.com for your container registry which will require additional configuration. You can also configure S3 storage for the containers. Check GitLab Container Registry documentation for the instructions.
Step 8 – Enable GitLab Pages
You need to have a domain that is not a subdomain of the GitLab URL. For our purposes, we will use https://pages.example.com to host GitLab pages. We are also going ahead with the assumption that we are not using Wildcard DNS.
Open the GitLab config file.
$ sudo nano /etc/gitlab/gitlab.rb
Set the following variables as shown.
pages_external_url 'https://pages.example.com' ..... # Experimental - Enable namespace in path gitlab_pages["namespace_in_path"] = true
Configure Nginx for GitLab pages in the GitLab Pages NGINX section.
# Below you can find settings that are exclusive to "GitLab Pages NGINX" pages_nginx['enable'] = true pages_nginx['redirect_http_to_https'] = true pages_nginx['ssl_certificate'] = "https://www.howtoforge.com/etc/letsencrypt/live/pages.example.com/fullchain.pem" pages_nginx['ssl_certificate_key'] = "https://www.howtoforge.com/etc/letsencrypt/live/pages.example.com/privkey.pem"
Save the file by pressing Ctrl X and entering Y when prompted.
Reconfigure GitLab Settings.
$ sudo gitlab-ctl reconfigure
If you want to host a Wildcard DNS-based domain, refer to the GitLab Pages documentation.
Step 9 – Enable MatterMost
Mattermost is an open-source online chat service with features such as file sharing, emojis, GIFs, markdown support, syntax highlighting, and multi-language support. GitLab ships with MatterMost which you can enable and allow company users sharing the GitLab instance to communicate with each other.
GitLab Mattermost is disabled by default. To enable it, open the GitLab configuration file.
$ sudo nano /etc/gitlab/gitlab.rb
Add the Mattermost external URL. GitLab will automatically generate the SSL for the URL using Let’s Encrypt.
mattermost_external_url 'https://mattermost.example.com'
Make sure the HTTP to HTTPS configuration setting for Mattermost is set to true by adding the following line.
mattermost_nginx['redirect_http_to_https'] = true
Save the file by pressing Ctrl X and entering Y when prompted.
Reconfigure GitLab Settings.
$ sudo gitlab-ctl reconfigure
You should be able to access Mattermost via https://mattermost.example.com. You should see the following page when you launch the URL.
If you have the Mattermost app installed, then select the View in Desktop App button or choose the View in Browser button option. Make sure to check the option Remember my preference so that you don’t get asked again. We will come back to configuring Mattermost in the next step.
Configure SMTP for Mattermost
Mattermost stores its configuration in the /var/opt/gitlab/mattermost/config.json file. Open it for editing.
$ sudo nano /var/opt/gitlab/mattermost/config.json
Find the "EmailSettings" section and configure it as shown. The FeedbackEmail, ReplyToAddress, EnableSMTPAuth, SMTPUsername, SMTPPassword, SMTPServer, SMTPPort, ConnectionSecurity, and SkipServerCertificateVerification are the ones we need to set for it to work.
"EmailSettings": {
"EnableSignUpWithEmail": true,
"EnableSignInWithEmail": true,
"EnableSignInWithUsername": true,
"SendEmailNotifications": true,
"UseChannelInEmailNotifications": false,
"RequireEmailVerification": false,
"FeedbackName": "Howtoforge Mattermost",
"FeedbackEmail": "[email protected]",
"ReplyToAddress": "[email protected]",
"FeedbackOrganization": "",
"EnableSMTPAuth": true,
"SMTPUsername": "AmazonSESUsername",
"SMTPPassword": "AmazonSESPassword",
"SMTPServer": "email-smtp.us-west-2.amazonaws.com",
"SMTPPort": "465",
"SMTPServerTimeout": 10,
"ConnectionSecurity": "TLS",
"SendPushNotifications": true,
"PushNotificationServer": "https://push-test.mattermost.com",
"PushNotificationContents": "full",
"PushNotificationBuffer": 1000,
"EnableEmailBatching": false,
"EmailBatchingBufferSize": 256,
"EmailBatchingInterval": 30,
"EnablePreviewModeBanner": false,
"SkipServerCertificateVerification": true,
"EmailNotificationContentsType": "full",
"LoginButtonColor": "#0000",
"LoginButtonBorderColor": "#2389D7",
"LoginButtonTextColor": "#2389D7"
},
Save the file by pressing Ctrl X and entering Y when prompted.
Step 10 – Access and Configure GitLab Web
Accessing GitLab
Open the URL https://gitlab.example.com in your browser and you will get the following login screen.
Enter root as the username and the password, you got in the previous step to sign in to your GitLab dashboard. On signing in, you will be taken to the following dashboard screen.
As you can see, GitLab has already created a project to monitor the instance.
Shut down GitLab for maintenance
If you want to put your GitLab instance on maintenance while performing server tasks, use the following command.
$ sudo gitlab-ctl deploy-page up cp /opt/gitlab/embedded/service/gitlab-rails/public/deploy.html /opt/gitlab/embedded/service/gitlab-rails/public/index.html
When a user visits the GitLab website, he will get the Deploy in progress page.
To remove the page, run the following command.
$ sudo gitlab-ctl deploy-page down
If you want to make the projects read-only, run the following command to open a Rails console.
$ sudo gitlab-rails console
It looks like the following.
-------------------------------------------------------------------------------- Ruby: ruby 3.1.4p223 (2023-03-30 revision 957bb7cb81) [x86_64-linux] GitLab: 16.9.2-ee (0d71d32d321) EE GitLab Shell: 14.33.0 PostgreSQL: 14.10 ------------------------------------------------------------[ booted in 78.60s ] Loading production environment (Rails 7.0.8) irb(main):001:0>
Set all the projects to read-only using the following command.
Project.all.find_each { |project| project.update!(repository_read_only: true) }
Exit the console by typing exit. To revert the projects to a normal state, use the following command in the console.
Project.all.find_each { |project| project.update!(repository_read_only: false) }
Restrict Public Sign-ups
By default, anyone can create an account and gain access. If you don’t want it, you can turn it off. Fortunately, the setting for it is shown in the form of a pop-up screen on the dashboard. Click the Turn off button to restrict public sign-ups on your GitLab instance. Doing so will redirect you to the following settings page.
Uncheck the option Sign-up enabled to restrict them. Press the button Save changes to apply the setting.
In case, you don’t see the pop-up in your dashboard, you can access the settings page by clicking the Admin Area button at the bottom left menu.
Once inside the admin panel, hover your mouse over the Settings option in the left sidebar and click on the General sub-menu. From there you can reach the Sign-up restrictions panel.
Configure GitLab Profile
Your default profile is pretty much bland and doesn’t have anything to show for it. To change that, click on the user icon in the upper left-hand corner to bring up the drop-down menu and select the Edit profile option.
You will be taken to the Profile settings page where you can add your name, e-mail, and other information about yourself. Click Update profile settings when you are done. Don’t go back to the homepage as we have some more things to configure here.
Change Root Password
This is one of the most important steps. You should change your default root password immediately. With earlier versions, GitLab required you to change it as part of the installation but now it has made it optional. To change your password, click on the Password menu from the left sidebar.
Enter your password details and click Save password to make the change. You will be logged out of your instance and will have to log in again.
Change the User name and enable two-factor authentication
You can change your default GitLab username from root to anything of your choice. To do that, click the Account menu from the left sidebar.
Once on the page, enter your new username and click the Update username button to make the change. You will be prompted again for confirmation. Press the Update username button again to confirm the change.
You should also enable two-factor authentication here to improve your account security.
Disable Prometheus Metrics and improve Privacy
In the previous step, we discussed increasing the shared memory size for the droplet and keeping it at a minimum of 256 MB. It is required mainly to store the Prometheus metrics-related data on the disk. If you are not using the feature, you should disable the feature. You can do it only post-installation. To disable it, open the Admin Panel from the menu bar.
Once inside the Admin panel, open the Settings >> Metrics and profiling menu option.
On the Metrics page, expand the Metrics – Prometheus section and uncheck the Enable health and performance metrics endpoint option. Click the Save changes button to implement the change.
GitLab also collects usage information from every installation. If you value privacy and don’t want it to happen, expand the Usage statistics option on the same page and Uncheck the Enable Service Ping option. Click the Save changes button to implement the change.
Configure Mattermost
Open the URL https://mattermost.example.com and you will be taken to the following login page.
Click the GitLab button to sign up. This will integrate your Mattermost account with your GitLab account. You will be taken to the GitLab login page where you enter your credentials and click the Sign in button to proceed. You will be taken to the Authorize page shown below.
Click the Authorize button to proceed. You will be taken back to the Mattermost application which asks for the name of your organization.
Enter the name of your organization and click the Continue page. Next, you will be asked which tools you use at your work.
Click the GitLab icon and then the Continue button to proceed. You can always add other tools later. Next, you will be asked to invite your team members and will be given an invite link.
Save the link for later and click the Finish setup to finish the Mattermost install. You will be taken to the Mattermost dashboard from where you can start using it.
GitLab is only authorized to be used for logging in to the Mattermost instance. The Mattermost instance comes with a GitLab plugin pre-installed that can send commits and notifications from your repository to your Mattermost instance. We need to configure that as well.
Visit GitLab >> Edit Profile page and select the Applications menu from the left sidebar. You should see your existing Mattermost login application already registered.
Click the Add new application button to create another application for the GitLab plugin.
Give a name to the project. Set https://mattermost.example.com/plugins/com.github.manland.mattermost-plugin-gitlab/oauth/complete as the Redirect URI. Check the Confidential, api, and the read_user options. Click the Save application button at the bottom of the page to finish.
You will be taken to the following page. Copy and save the Application ID and the Application Secret which you will need later. The Application Secret will only be shown once so make sure of that.
Click the Continue button to finish.
Open your Mattermost site and click the top leftmost button to reveal the following popup menu.
Click the App Marketplace button to open the following popup window.
Click the Configure button against the GitLab plugin to proceed.
Enter the GitLab URL, OAuth Client ID, and the OAuth Client Secret generated previously, and click the Save button to finish.
Now each user needs to connect their GitLab account in Mattermost. Visit the GitLab channel on Mattermost and type the following command to start /gitlab connect and press the enter key and you will get the following message.
Click the Link button and you will be taken to a new page asking to authorize the connection. Click Connect and you will be taken back to the Mattermost page and you should see the following message confirming the connection.
Step 11 – Creating your first project
Let us try to create our first project and push a commit.
Adding your SSH Key
Before proceeding any further, we should add our SSH key. This allows us to interact with our installation without using any passwords. If you have an SSH key, you can skip the following command. If you don’t have one, you can create one using the following command.
$ ssh-keygen -t ed25519 -C "gitlab.example.com"
This command is common to macOS, Linux, and Git Bash/WSL on Windows. Accept the defaults and enter a strong passphrase. We are creating the SSH keys on the Windows Powershell Terminal.
Generating public/private rsa key pair. Generating public/private ed25519 key pair. Enter file in which to save the key (C:Users/.ssh/id_ed25519): Enter same passphrase again: Your identification has been saved in C:Users/.ssh/id_ed25519. Your public key has been saved in C:Users/.ssh/id_ed25519.pub. SHA256:CI3Ja1LSTN j4LQnDYkAoP DvZB8SWrD26zDyUBRbUY gitlab.example.com --[ED25519 256]-- |* .. E | |. / o o | | o = B o . | |. o B = S | |.o X | | X.* | | .=B o | ----[SHA256]-----
Add the private key identity to the SSH authentication agent. Make sure the OpenSSH Authentication Agent service is running if you are on Windows. If you are on Linux or macOS, run the following command.
$ eval $(ssh-agent -s)
Add the key.
$ ssh-add C:Users/.ssh/id_ed25519
On Linux and macOS, the command will change to
$ ssh-add ~/.ssh/id_ed25519
You will be prompted for the passphrase. Enter it and the key will be added.
Next, we need to save these settings to the ~/.ssh/config file. On Windows, this will be the C:Users.ssh directory. Paste the following code at the end of the file.
Host gitlab.example.com PreferredAuthentications publickey IdentityFile ~/.ssh/id_ed25519
In this file, the path name will remain the same across all operating systems. Save the file.
Next, we need to copy the public key to our GitLab account. You can display your public key via the following command. The path name will again work across all operating systems here.
$ cat ~/.ssh/id_ed25519.pub
You will get a similar output.
ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIGCEIN84O/9tcvE5wsTswY76xeJyY7TwkMW6uCvYulm1 gitlab.example.com
Open your profile settings in GitLab and select the SSH Keys menu from the left sidebar.
Paste the SSH key in the box provided and click on Add Key to proceed. You will be given a default expiration date. You can change it according to your needs.
Next, we need to test whether our SSH connection is working successfully. Run the following command on your PC terminal.
$ ssh -T [email protected]
You will get a similar output. First, you will be asked to add the SSH key to your system’s Known hosts list. Type yes to proceed. Next, you will get a success message confirming your connection to your GitLab instance.
The authenticity of host 'gitlab.example.com (178.62.213.105)' can't be established. ECDSA key fingerprint is SHA256:x1647s5G1iL/cnRFoBuE6qzRZF775fVLZzcLJTGaIvQ. Are you sure you want to continue connecting (yes/no/[fingerprint])? yes Warning: Permanently added 'gitlab.example.com,178.62.213.105' (ECDSA) to the list of known hosts. Welcome to GitLab, @navjot!
Now, we can move on to creating our first repository and make some commits.
Creating a Project
Each repository in GitLab belongs to a project. A project includes a repository, issue tracker, merge requests, wiki, continuous integration, continuous delivery (CI/CD) pipelines, and lots of other features.
To create your first repository, click the Create a project section on your homepage.
You will be taken to the New Project page where you will be given multiple options on how to create a new project.
Select the Create blank project option to proceed. On the next page, enter the Project name. Select your username from the dropdown menu in the Project URL option in the Pick a group or namespace box. Set your Project slug if you want to change the default one. Change the Visibility Level of the project as per your need. You can Initialize your repository with a README file. If you want GitLab to analyze your code for security vulnerabilities, check the Enable SAST option.
Once you are done, click Create project to finish. You will be taken to your repository page with just a single blank README.md file.
Now that our repository is live, let us try adding a changelog from the command line. Enter the following commands on your computer to create a CHANGELOG file and push it back to your repository. Make sure you have Git installed on your computer.
The first step is to clone the repository. You can clone either using SSH or HTTPS. Clone using SSH. You will be asked for the passphrase.
$ git clone [email protected]:user/howtoforge-test.git
You should see a similar output.
Cloning into 'howtoforge-test'... Enter passphrase for key '/c/Users/navjo/.ssh/id_ed25519': remote: Enumerating objects: 3, done. remote: Counting objects: 100% (3/3), done. remote: Compressing objects: 100% (2/2), done. remote: Total 3 (delta 0), reused 0 (delta 0), pack-reused 0 Receiving objects: 100% (3/3), done.
Enter the remainder of the commands to create and push the CHANGELOG file.
$ cd howtoforge-test $ touch CHANGELOG # Or create the file in your editor and enter a project description $ git add CHANGELOG $ git commit -m "add Changelog" [main d6c7a9c] add Changelog 1 file changed, 0 insertions( ), 0 deletions(-) create mode 100644 CHANGELOG $ git push -u origin main Enter passphrase for key '/c/Users/navjo/.ssh/id_ed25519': Enumerating objects: 4, done. Counting objects: 100% (4/4), done. Delta compression using up to 4 threads Compressing objects: 100% (2/2), done. Writing objects: 100% (3/3), 958 bytes | 958.00 KiB/s, done. Total 3 (delta 0), reused 0 (delta 0), pack-reused 0 To gitlab.example.com:navjot/howtoforge-test.git 523db9a..d6c7a9c main -> main branch 'main' set up to track 'origin/main'.
You will be prompted for the passphrase again during the push command.
Go back to your GitLab project page and you will see the CHANGELOG file in it. Congratulations! You have successfully created your first project and committed a file to it.
That wraps up our first GitLab project.
Step 12 – Backup GitLab
GitLab provides a command-line interface to back up your entire instance including the database, attachments, repository data, CI/CD job artifacts, CI/CD job output logs, LFS objects, Terraform states, Container registry images, GitLab Pages content, packages, snippets, group wikis, merge request diffs, and project-level secure files.
Backups don’t include the Mattermost data, Redis data, Sidekiq jobs, and Object storage.
Run the following command to perform the backup.
$ sudo gitlab-backup create STRATEGY=copy
The STRATEGY=copy option is to prevent errors in case the data is rapidly changing. This copies the data to a temporary location and avoids possible errors.
You should see a similar output.
2024-03-07 11:48:37 UTC -- Dumping database ...
Dumping PostgreSQL database gitlabhq_production ... [DONE]
2024-03-07 11:48:45 UTC -- Dumping database ... done
2024-03-07 11:48:45 UTC -- Dumping repositories ...
{"command":"create","gl_project_path":"navjot/howtoforge-test","level":"info","msg":"started create","pid":107325,"relative_path":"@hashed/6b/86/6b86b273ff34fce19d6b804eff5a3f5747ada4eaa22f1d49c01e52ddb7875b4b.git","storage_name":"default","time":"2024-03-07T11:48:45.720Z"}
{"command":"create","gl_project_path":"navjot/howtoforge-test","level":"info","msg":"completed create","pid":107325,"relative_path":"@hashed/6b/86/6b86b273ff34fce19d6b804eff5a3f5747ada4eaa22f1d49c01e52ddb7875b4b.git","storage_name":"default","time":"2024-03-07T11:48:45.772Z"}
{"command":"create","gl_project_path":"navjot/howtoforge-test.wiki","level":"info","msg":"started create","pid":107325,"relative_path":"@hashed/6b/86/6b86b273ff34fce19d6b804eff5a3f5747ada4eaa22f1d49c01e52ddb7875b4b.wiki.git","storage_name":"default","time":"2024-03-07T11:48:45.874Z"}
{"command":"create","gl_project_path":"navjot/howtoforge-test.wiki","level":"info","msg":"completed create","pid":107325,"relative_path":"@hashed/6b/86/6b86b273ff34fce19d6b804eff5a3f5747ada4eaa22f1d49c01e52ddb7875b4b.wiki.git","storage_name":"default","time":"2024-03-07T11:48:45.894Z"}
2024-03-07 11:48:45 UTC -- Dumping repositories ... done
2024-03-07 11:48:45 UTC -- Dumping uploads ...
2024-03-07 11:48:46 UTC -- Dumping uploads ... done
2024-03-07 11:48:46 UTC -- Dumping builds ...
2024-03-07 11:48:46 UTC -- Dumping builds ... done
2024-03-07 11:48:46 UTC -- Dumping artifacts ...
2024-03-07 11:48:46 UTC -- Dumping artifacts ... done
2024-03-07 11:48:46 UTC -- Dumping pages ...
2024-03-07 11:48:46 UTC -- Dumping pages ... done
2024-03-07 11:48:46 UTC -- Dumping lfs objects ...
2024-03-07 11:48:46 UTC -- Dumping lfs objects ... done
2024-03-07 11:48:46 UTC -- Dumping terraform states ...
2024-03-07 11:48:46 UTC -- Dumping terraform states ... done
2024-03-07 11:48:46 UTC -- Dumping container registry images ...
2024-03-07 11:48:46 UTC -- Dumping container registry images ... done
2024-03-07 11:48:46 UTC -- Dumping packages ...
2024-03-07 11:48:46 UTC -- Dumping packages ... done
2024-03-07 11:48:46 UTC -- Dumping ci secure files ...
2024-03-07 11:48:46 UTC -- Dumping ci secure files ... done
2024-03-07 11:48:46 UTC -- Creating backup archive: 1709812117_2024_03_07_16.9.1-ee_gitlab_backup.tar ...
2024-03-07 11:48:46 UTC -- Creating backup archive: 1709812117_2024_03_07_16.9.1-ee_gitlab_backup.tar ... done
2024-03-07 11:48:46 UTC -- Uploading backup archive to remote storage ... [SKIPPED]
2024-03-07 11:48:46 UTC -- Deleting old backups ... [SKIPPED]
2024-03-07 11:48:46 UTC -- Deleting tar staging files ...
2024-03-07 11:48:46 UTC -- Cleaning up /var/opt/gitlab/backups/backup_information.yml
2024-03-07 11:48:46 UTC -- Cleaning up /var/opt/gitlab/backups/db
2024-03-07 11:48:46 UTC -- Cleaning up /var/opt/gitlab/backups/repositories
2024-03-07 11:48:46 UTC -- Cleaning up /var/opt/gitlab/backups/uploads.tar.gz
2024-03-07 11:48:46 UTC -- Cleaning up /var/opt/gitlab/backups/builds.tar.gz
2024-03-07 11:48:46 UTC -- Cleaning up /var/opt/gitlab/backups/artifacts.tar.gz
2024-03-07 11:48:46 UTC -- Cleaning up /var/opt/gitlab/backups/pages.tar.gz
2024-03-07 11:48:46 UTC -- Cleaning up /var/opt/gitlab/backups/lfs.tar.gz
2024-03-07 11:48:46 UTC -- Cleaning up /var/opt/gitlab/backups/terraform_state.tar.gz
2024-03-07 11:48:46 UTC -- Cleaning up /var/opt/gitlab/backups/registry.tar.gz
2024-03-07 11:48:46 UTC -- Cleaning up /var/opt/gitlab/backups/packages.tar.gz
2024-03-07 11:48:46 UTC -- Cleaning up /var/opt/gitlab/backups/ci_secure_files.tar.gz
2024-03-07 11:48:46 UTC -- Deleting tar staging files ... done
2024-03-07 11:48:46 UTC -- Deleting backups/tmp ...
2024-03-07 11:48:46 UTC -- Deleting backups/tmp ... done
2024-03-07 11:48:46 UTC -- Warning: Your gitlab.rb and gitlab-secrets.json files contain sensitive data
and are not included in this backup. You will need these files to restore a backup.
Please back them up manually.
2024-03-07 11:48:46 UTC -- Backup 1709812117_2024_03_07_16.9.1-ee is done.
2024-03-07 11:48:46 UTC -- Deleting backup and restore PID file ... done
Your backup file is stored in the /var/opt/gitlab/backups directory.
$ sudo ls /var/opt/gitlab/backups 1709812117_2024_03_07_16.9.1-ee_gitlab_backup.tar
As mentioned in the output, your GitLab configuration and secrets are not included in the backup. Copy these files manually to a safe location for restoration.
Copy them.
$ sudo cp /etc/gitlab/gitlab.rb /etc/gitlab/gitlab-secrets.json /var/opt/gitlab/backups
You can configure cron to take daily backups.
Open the crontab for the root user.
$ sudo su - $ EDITOR = nano crontab -e
Add the following line to it.
0 2 * * * /opt/gitlab/bin/gitlab-backup create CRON=1
Save the file by pressing Ctrl X and entering Y when prompted.
The CRON=1 option is to hide all the output if there are no errors. This helps in limiting cron spam. However, if you are debugging, replace CRON=1 with --trace to log verbosely.
You can check the official GitLab backup documentation for more options and how to make sure your backups are automatically copied to an S3-compatible service.
Step 13 – Restore GitLab
Before restoring GitLab, make sure you meet the following requirements.
-
The GitLab version and edition should match the one from which the backup was taken.
-
You have run the command
sudo gitlab-ctl reconfigureat least once. -
GitLab should be running.
-
The GitLab secrets and the settings must be restored.
$ sudo cp gitlab.rb gitlab-secrets.json /etc/gitlab
Copy the backup file to the /var/opt/gitlab/backups directory.
$ sudo cp 1709812117_2024_03_07_16.9.1-ee_gitlab_backup.tar /var/opt/gitlab/backups/
Set the correct permissions.
$ sudo chown git:git /var/opt/gitlab/backups/1709812117_2024_03_07_16.9.1-ee_gitlab_backup.tar
Stop the processes that are connected to the database. You can leave the rest of the GitLab running as usual.
$ sudo gitlab-ctl stop puma $ sudo gitlab-ctl stop sidekiq
Verify the processes.
$ sudo gitlab-ctl status run: alertmanager: (pid 68055) 76797s; run: log: (pid 66127) 78476s run: crond: (pid 68045) 76798s; run: log: (pid 65624) 78566s run: gitaly: (pid 66424) 78414s; run: log: (pid 65273) 78710s run: gitlab-exporter: (pid 66466) 78411s; run: log: (pid 66002) 78497s run: gitlab-kas: (pid 65535) 78691s; run: log: (pid 65547) 78690s run: gitlab-pages: (pid 68003) 76801s; run: log: (pid 67700) 76996s run: gitlab-workhorse: (pid 66392) 78415s; run: log: (pid 65727) 78550s run: logrotate: (pid 106163) 3124s; run: log: (pid 65169) 78724s run: mattermost: (pid 68027) 76799s; run: log: (pid 67820) 76890s run: nginx: (pid 72647) 75588s; run: log: (pid 65781) 78544s run: node-exporter: (pid 66458) 78411s; run: log: (pid 65968) 78505s run: postgres-exporter: (pid 66505) 78407s; run: log: (pid 66162) 78470s run: postgresql: (pid 65341) 78702s; run: log: (pid 65362) 78699s run: prometheus: (pid 66476) 78410s; run: log: (pid 66070) 78483s down: puma: 14s, normally up; run: log: (pid 65649) 78562s run: redis: (pid 65207) 78719s; run: log: (pid 65216) 78718s run: redis-exporter: (pid 66468) 78410s; run: log: (pid 66034) 78490s run: registry: (pid 66414) 78414s; run: log: (pid 65864) 78528s down: sidekiq: 5s, normally up; run: log: (pid 65681) 78554s
Restore the backup. Make sure what you are doing as it will overwrite your database. You don’t need to give the full filename in the command. Just the part before the -ee_gitlab_backup.tar of the filename.
$ sudo gitlab-backup restore BACKUP=1709812117_2024_03_07_16.9.1-ee
This should restore your GitLab installation successfully.
Step 14 – Upgrade GitLab
Create a backup before upgrading GitLab. Upgrading GitLab is as simple as running sudo dnf update command.
$ sudo dnf update
Minor upgrades are safe to perform this way.
DigitalOcean Agent 40 kB/s | 3.3 kB 00:00 DigitalOcean Droplet Agent 44 kB/s | 3.3 kB 00:00 gitlab_gitlab-ee 1.4 kB/s | 1.0 kB 00:00 gitlab_gitlab-ee-source 1.2 kB/s | 951 B 00:00 Dependencies resolved. ======================================================================================================================== Package Architecture Version Repository Size ======================================================================================================================== Upgrading: gitlab-ee x86_64 16.9.2-ee.0.el9 gitlab_gitlab-ee 1.1 G Transaction Summary ======================================================================================================================== Upgrade 1 Package Total download size: 1.1 G Is this ok [y/N]: y
Type y and press Enter to start the upgrade. For major versions, you should keep a check on any breaking changes before performing the upgrade.
The site will become unavailable while the upgrade is being performed or you will get a Deploy in progress message in the browser.
Once you complete the upgrade, do the following post-upgrade check to make sure everything is working properly.
-
Check general configuration.
$ sudo gitlab-rake gitlab:check
-
Confirm that encrypted database values can be decrypted.
$ sudo gitlab-rake gitlab:doctor:secrets
-
Check whether users can sign in, the project list is visible, project issues and merge requests are accessible, users can clone repositories, and they can push commits to GitLab in GitLab UI.
-
For GitLab CI/CD, check that runners can pick up jobs and the Docker registry is working.
Conclusion
This concludes our tutorial where you learned how to install and configure GitLab on a Rocky Linux 9 server. You also created your first project and committed a file to it from your PC. If you have any questions, post them in the comments below.
