The instance first starts over HTTP, then TLS is enabled on it. Before you start, make sure the server meets the requirements.

In the commands and configuration files below, replace <HOSTNAME> with the FQDN of the instance and <VERSION> with the version of the package you received, for example 1.0.0-0.

The CLI utilities (gitlab-ctl, gitlab-backup), the configuration file (/etc/gitlab/gitlab.rb) and the service directories (/opt/gitlab, /var/opt/gitlab) keep the gitlab- prefix: Deckhouse Code runs on the GitLab engine, and the system names are left unchanged.

Preparation

The instance name <HOSTNAME> is used in the web interface address, in the repository addresses for Git, in the external_url setting and in the CN and SAN fields of the certificate — the same name everywhere.

  1. Check that the name resolves to the IP address of the machine:

    getent hosts <HOSTNAME>

  2. If there is no A or AAAA DNS record, add the name to the /etc/hosts file on the server:

    echo "<IP_ADDRESS> <HOSTNAME>" | sudo tee -a /etc/hosts

    <IP_ADDRESS> is the IP address of the instance machine. Add the same line on every machine that will open the web interface and work with Git, including your workstation.

Installing the package

The installation starts the initial configuration (gitlab-ctl reconfigure) on its own, which takes several minutes. The instance address is taken from the EXTERNAL_URL variable during the first installation; TLS is enabled at the next step.

  • RED OS 8
  • Ubuntu 24.04

Install the system dependencies:

sudo dnf install -y libxcrypt-compat policycoreutils-python-utils

The libxcrypt-compat package provides the libcrypt.so.1 library, without which the application does not start: the minimal RED OS installation does not contain it. The policycoreutils-python-utils package provides the semanage utility, which sets the SELinux contexts during the initial configuration.

Install the Deckhouse Code package:

sudo EXTERNAL_URL="http://<HOSTNAME>" \
  rpm -i ./deckhouse-code-<VERSION>.el8.x86_64.rpm

The enforcing SELinux mode is supported: the policy module is installed during the initial configuration, and no manual action is needed.

There is no need to install the system dependencies separately: they are declared in the package, and apt takes them from the OS repositories.

Install the Deckhouse Code package:

sudo EXTERNAL_URL="http://<HOSTNAME>" \
  apt install -y ./deckhouse-code_<VERSION>_amd64.deb

The ./ prefix in the file path is required: without it, apt looks for a package with that name in the repositories.

What you get

The instance is running at http://<HOSTNAME>: the web interface, Git over HTTP, the database and the background jobs. Check its state — the commands run on the instance machine itself:

# Every service is in the run state.
sudo gitlab-ctl status
# Code 200 is expected.
curl -s -o /dev/null -w "%{http_code}\n" http://localhost/-/health
# The first administrator password.
sudo cat /etc/gitlab/initial_root_password

Open http://<HOSTNAME> in a browser and sign in as the root user with the password from the /etc/gitlab/initial_root_password file.

Save the password: the initial_root_password file is kept for 24 hours, and any further gitlab-ctl reconfigure run deletes it once more than a day has passed since the installation. The password value itself does not change.

TLS

Over HTTP, passwords and repository contents travel in plain text, so enable TLS right after the first sign-in.

Prepare the directory for the certificates:

sudo mkdir -p /etc/gitlab/ssl && sudo chmod 755 /etc/gitlab/ssl

Place the certificate and the key in it under the names <HOSTNAME>.crt and <HOSTNAME>.key.

  • Your own certificate
  • Self-signed certificate

Issue a certificate for the <HOSTNAME> name in your certificate authority and copy the files to the server:

sudo install -m 600 <KEY_FILE> /etc/gitlab/ssl/<HOSTNAME>.key
# The certificate together with its chain.
sudo install -m 644 <CERT_FILE> /etc/gitlab/ssl/<HOSTNAME>.crt

<KEY_FILE> and <CERT_FILE> are the paths to the key and certificate files you received.

On a test stand, issue the certificate on the spot. The instance name in the SAN field is required, otherwise clients reject the certificate:

sudo openssl req -x509 -nodes -newkey rsa:2048 -days 825 \
  -keyout /etc/gitlab/ssl/<HOSTNAME>.key \
  -out /etc/gitlab/ssl/<HOSTNAME>.crt \
  -subj "/CN=<HOSTNAME>/O=Deckhouse Code/C=RU" \
  -addext "subjectAltName=DNS:<HOSTNAME>"
sudo chmod 600 /etc/gitlab/ssl/<HOSTNAME>.key

Enable HTTPS in the /etc/gitlab/gitlab.rb file:

external_url 'https://<HOSTNAME>'
letsencrypt['enable'] = false
nginx['redirect_http_to_https'] = true
nginx['ssl_certificate'] = "/etc/gitlab/ssl/<HOSTNAME>.crt"
nginx['ssl_certificate_key'] = "/etc/gitlab/ssl/<HOSTNAME>.key"

Without the letsencrypt['enable'] = false line, the configuration with an https:// address starts obtaining a certificate through Let’s Encrypt over HTTP-01 and fails in an isolated network.

Apply the configuration:

sudo gitlab-ctl reconfigure

Verification

Check the state of the services, the response over HTTPS and the redirect from HTTP:

# Every service is in the run state.
sudo gitlab-ctl status
# The --resolve option sends the request to the loopback address: /-/health answers
# only on the machine itself, while the name check against the certificate is kept.
# health=200 tls=0 is expected.
curl --cacert /etc/gitlab/ssl/<HOSTNAME>.crt \
     --resolve '<HOSTNAME>:443:127.0.0.1' \
     -o /dev/null -w "health=%{http_code} tls=%{ssl_verify_result}\n" \
     https://<HOSTNAME>/-/health
# The redirect from HTTP to HTTPS, https://<HOSTNAME>/ is expected.
curl -sI http://<HOSTNAME>/ | grep -i location

A browser and Git reject a self-signed certificate until its certificate authority is trusted. For Git, set the path to the certificate file on the client machine:

git config --global http.https://<HOSTNAME>.sslCAInfo <CERT_FILE>

Change the password of the root user in the web interface and delete the initial password file:

sudo rm -f /etc/gitlab/initial_root_password

Additional resources

←
Linux package / Requirements
Linux package / Post-installation setup
→