217 lines
9.1 KiB
Markdown
217 lines
9.1 KiB
Markdown
---
|
|
stage: Systems
|
|
group: Distribution
|
|
info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments
|
|
---
|
|
|
|
# Getting started with an offline GitLab Installation **(FREE SELF)**
|
|
|
|
This is a step-by-step guide that helps you install, configure, and use a self-managed GitLab
|
|
instance entirely offline.
|
|
|
|
## Installation
|
|
|
|
NOTE:
|
|
This guide assumes the server is Ubuntu 20.04 using the [Omnibus installation method](https://docs.gitlab.com/omnibus/) and will be running GitLab [Enterprise Edition](https://about.gitlab.com/install/ce-or-ee/). Instructions for other servers may vary.
|
|
This guide also assumes the server host resolves as `my-host.internal`, which you should replace with your
|
|
server's FQDN, and that you have access to a different server with Internet access to download the required package files.
|
|
|
|
<i class="fa fa-youtube-play youtube" aria-hidden="true"></i>
|
|
For a video walkthrough of this process, see [Offline GitLab Installation: Downloading & Installing](https://www.youtube.com/watch?v=TJaq4ua2Prw).
|
|
|
|
### Download the GitLab package
|
|
|
|
You should [manually download the GitLab package](../../update/package/index.md#upgrade-using-a-manually-downloaded-package) and relevant dependencies using a server of the same operating system type that has access to the Internet.
|
|
|
|
If your offline environment has no local network access, you must manually transport across the relevant package files through physical media, such as a USB drive, or writable DVD.
|
|
|
|
In Ubuntu, this can be performed on a server with Internet access using the following commands:
|
|
|
|
```shell
|
|
# Download the bash script to prepare the repository
|
|
curl --silent "https://packages.gitlab.com/install/repositories/gitlab/gitlab-ee/script.deb.sh" | sudo bash
|
|
|
|
# Download the gitlab-ee package and dependencies to /var/cache/apt/archives
|
|
sudo apt-get install --download-only gitlab-ee
|
|
|
|
# Copy the contents of the apt download folder to a mounted media device
|
|
sudo cp /var/cache/apt/archives/*.deb /path/to/mount
|
|
```
|
|
|
|
### Install the GitLab package
|
|
|
|
Prerequisites:
|
|
|
|
- Before installing the GitLab package on your offline environment, ensure that you have installed all required dependencies first.
|
|
|
|
If you are using Ubuntu, you can install the dependency `.deb` packages you copied across with `dpkg`. Do not install the GitLab package yet.
|
|
|
|
```shell
|
|
# Navigate to the physical media device
|
|
sudo cd /path/to/mount
|
|
|
|
# Install the dependency packages
|
|
sudo dpkg -i <package_name>.deb
|
|
```
|
|
|
|
[Use the relevant commands for your operating system to install the package](../../update/package/index.md#upgrade-using-a-manually-downloaded-package) but make sure to specify an `http`
|
|
URL for the `EXTERNAL_URL` installation step. Once installed, we can manually
|
|
configure the SSL ourselves.
|
|
|
|
It is strongly recommended to setup a domain for IP resolution rather than bind
|
|
to the server's IP address. This better ensures a stable target for our certs' CN
|
|
and makes long-term resolution simpler.
|
|
|
|
The following example for Ubuntu specifies the `EXTERNAL_URL` using HTTP and installs the GitLab package:
|
|
|
|
```shell
|
|
sudo EXTERNAL_URL="http://my-host.internal" dpkg -i <gitlab_package_name>.deb
|
|
```
|
|
|
|
## Enabling SSL
|
|
|
|
Follow these steps to enable SSL for your fresh instance. These steps reflect those for
|
|
[manually configuring SSL in Omnibus's NGINX configuration](https://docs.gitlab.com/omnibus/settings/ssl.html#configure-https-manually):
|
|
|
|
1. Make the following changes to `/etc/gitlab/gitlab.rb`:
|
|
|
|
```ruby
|
|
# Update external_url from "http" to "https"
|
|
external_url "https://my-host.internal"
|
|
|
|
# Set Let's Encrypt to false
|
|
letsencrypt['enable'] = false
|
|
```
|
|
|
|
1. Create the following directories with the appropriate permissions for generating self-signed
|
|
certificates:
|
|
|
|
```shell
|
|
sudo mkdir -p /etc/gitlab/ssl
|
|
sudo chmod 755 /etc/gitlab/ssl
|
|
sudo openssl req -x509 -nodes -days 365 -newkey rsa:2048 -keyout /etc/gitlab/ssl/my-host.internal.key -out /etc/gitlab/ssl/my-host.internal.crt
|
|
```
|
|
|
|
1. Reconfigure your instance to apply the changes:
|
|
|
|
```shell
|
|
sudo gitlab-ctl reconfigure
|
|
```
|
|
|
|
## Enabling the GitLab Container Registry
|
|
|
|
Follow these steps to enable the container registry. These steps reflect those for
|
|
[configuring the container registry under an existing domain](../../administration/packages/container_registry.md#configure-container-registry-under-an-existing-gitlab-domain):
|
|
|
|
1. Make the following changes to `/etc/gitlab/gitlab.rb`:
|
|
|
|
```ruby
|
|
# Change external_registry_url to match external_url, but append the port 4567
|
|
external_url "https://gitlab.example.com"
|
|
registry_external_url "https://gitlab.example.com:4567"
|
|
```
|
|
|
|
1. Reconfigure your instance to apply the changes:
|
|
|
|
```shell
|
|
sudo gitlab-ctl reconfigure
|
|
```
|
|
|
|
## Allow the Docker daemon to trust the registry and GitLab Runner
|
|
|
|
Provide your Docker daemon with your certs by
|
|
[following the steps for using trusted certificates with your registry](../../administration/packages/container_registry.md#using-self-signed-certificates-with-container-registry):
|
|
|
|
```shell
|
|
sudo mkdir -p /etc/docker/certs.d/my-host.internal:5000
|
|
|
|
sudo cp /etc/gitlab/ssl/my-host.internal.crt /etc/docker/certs.d/my-host.internal:5000/ca.crt
|
|
```
|
|
|
|
Provide your GitLab Runner (to be installed next) with your certs by
|
|
[following the steps for using trusted certificates with your runner](https://docs.gitlab.com/runner/install/docker.html#installing-trusted-ssl-server-certificates):
|
|
|
|
```shell
|
|
sudo mkdir -p /etc/gitlab-runner/certs
|
|
|
|
sudo cp /etc/gitlab/ssl/my-host.internal.crt /etc/gitlab-runner/certs/ca.crt
|
|
```
|
|
|
|
## Enabling GitLab Runner
|
|
|
|
[Following a similar process to the steps for installing our GitLab Runner as a Docker service](https://docs.gitlab.com/runner/install/docker.html#install-the-docker-image-and-start-the-container), we must first register our runner:
|
|
|
|
```shell
|
|
$ sudo docker run --rm -it -v /etc/gitlab-runner:/etc/gitlab-runner gitlab/gitlab-runner register
|
|
Updating CA certificates...
|
|
Runtime platform arch=amd64 os=linux pid=7 revision=1b659122 version=12.8.0
|
|
Running in system-mode.
|
|
|
|
Please enter the gitlab-ci coordinator URL (e.g. https://gitlab.com/):
|
|
https://my-host.internal
|
|
Please enter the gitlab-ci token for this runner:
|
|
XXXXXXXXXXX
|
|
Please enter the gitlab-ci description for this runner:
|
|
[eb18856e13c0]:
|
|
Please enter the gitlab-ci tags for this runner (comma separated):
|
|
|
|
Registering runner... succeeded runner=FSMwkvLZ
|
|
Please enter the executor: custom, docker, virtualbox, kubernetes, docker+machine, docker-ssh+machine, docker-ssh, parallels, shell, ssh:
|
|
docker
|
|
Please enter the default Docker image (e.g. ruby:2.6):
|
|
ruby:2.6
|
|
Runner registered successfully. Feel free to start it, but if it's running already the config should be automatically reloaded!
|
|
```
|
|
|
|
Now we must add some additional configuration to our runner:
|
|
|
|
Make the following changes to `/etc/gitlab-runner/config.toml`:
|
|
|
|
- Add Docker socket to volumes `volumes = ["/var/run/docker.sock:/var/run/docker.sock", "/cache"]`
|
|
- Add `pull_policy = "if-not-present"` to the executor configuration
|
|
|
|
Now we can start our runner:
|
|
|
|
```shell
|
|
sudo docker run -d --restart always --name gitlab-runner -v /etc/gitlab-runner:/etc/gitlab-runner -v /var/run/docker.sock:/var/run/docker.sock gitlab/gitlab-runner:latest
|
|
90646b6587127906a4ee3f2e51454c6e1f10f26fc7a0b03d9928d8d0d5897b64
|
|
```
|
|
|
|
### Authenticating the registry against the host OS
|
|
|
|
As noted in [Docker registry authentication documentation](https://docs.docker.com/registry/insecure/#docker-still-complains-about-the-certificate-when-using-authentication),
|
|
certain versions of Docker require trusting the certificate chain at the OS level.
|
|
|
|
In the case of Ubuntu, this involves using `update-ca-certificates`:
|
|
|
|
```shell
|
|
sudo cp /etc/docker/certs.d/my-host.internal\:5000/ca.crt /usr/local/share/ca-certificates/my-host.internal.crt
|
|
|
|
sudo update-ca-certificates
|
|
```
|
|
|
|
If all goes well, this is what you should see:
|
|
|
|
```plaintext
|
|
1 added, 0 removed; done.
|
|
Running hooks in /etc/ca-certificates/update.d...
|
|
done.
|
|
```
|
|
|
|
### Disable Version Check and Service Ping
|
|
|
|
The Version Check and Service Ping services improve the GitLab user experience and ensure that
|
|
users are on the most up-to-date instances of GitLab. These two services can be turned off for offline
|
|
environments so that they do not attempt and fail to reach out to GitLab services.
|
|
|
|
Learn more about [disabling usage statistics](../../user/admin_area/settings/usage_statistics.md#enable-or-disable-usage-statistics).
|
|
|
|
### Configure NTP
|
|
|
|
In GitLab 15.4 and 15.5, Gitaly Cluster doesn't function if `pool.ntp.org` is unreachable.
|
|
[Customize the time server setting](../../administration/gitaly/praefect.md#customize-time-server-setting) on the Gitaly
|
|
and Praefect servers so they can use an accessible NTP server.
|
|
|
|
On offline instances, the [GitLab Geo check Rake task](../../administration/geo/replication/troubleshooting.md#can-geo-detect-the-current-site-correctly)
|
|
always fails because it uses `pool.ntp.org`. This error can be ignored but you can
|
|
[read more about how to work around it](../../administration/geo/replication/troubleshooting.md#message-machine-clock-is-synchronized--exception).
|