Self-Hosted Standalone Installation Guide

Version 2023.3

This manual covers the installation of Gradle Enterprise into a single host.

Time to completion: 60 minutes

Before Installation

Gradle Enterprise is a Kubernetes-based application, distributed as a Helm chart. Helm is a package manager for Kubernetes applications.

The standalone installation of Gradle Enterprise described in this manual involves installing the K3s lightweight Kubernetes distribution onto a host, then using Helm to install Gradle Enterprise in the K3s instance on that host.

Helm manages all Gradle Enterprise components.

For those installing Gradle Enterprise on a host without public network connectivity, please follow sections marked Airgap.

Prerequisites

1. A Gradle Enterprise License

If you have purchased Gradle Enterprise or started a trial, you should already have a license file called gradle-enterprise.license. Otherwise, you may request a Gradle Enterprise trial license.

Host Requirements

This section outlines the host requirements for the installation.

1. Operating system

We focus our support efforts on Ubuntu 18.04/20.04/22.04, RHEL 8.4/8.5/8.6, and Debian 11. Gradle Enterprise is expected to work on most modern Linux systems.

2. K3s

K3s needs several ports to be accessible from the host.

Protocol	Port
TCP	6443
TCP	10250
UDP	8472

While these ports don’t need to be accessible from outside the host machine, K3s may access them using a different network interface or non-localhost IP.

RHEL / CentOS

There are some additional requirements for RHEL or CentOS installations. You must disable the nm-cloud-setup.service and nm-cloud-setup.timer services.

Disabling firewalld is recommended, too. If you can’t, ensure that the ports mentioned above are accessible and enable IP address masquerading. This can be done with the following command:

$ firewall-cmd --add-masquerade --permanent

For more details on IP address masquerading, see RedHat’s docs.
For more details on the RHEL / CentOS requirements, see K3s’s docs.

3. CPU & Memory

The minimum installation requirements are:

Quad-core 2GHz or better CPU (amd64 architecture)
16 GB free RAM

4. Database

By default, Gradle Enterprise stores its data in a PostgreSQL database that is run as part of the application itself, with data being stored in a directory mounted on its host machine.

Gradle Enterprise installations have two database options:

An embedded database that is highly dependent on disk performance.
A user-managed database that is compatible with PostgreSQL 12, 13, or 14.

Using PGBouncer with a user managed database is not supported.

5. Storage

In addition to the database, Gradle Enterprise needs some storage capacity for configuration files, logs, and build cache artifacts. These storage requirements apply regardless of which type of database you use, although the necessary size varies based on the database type.

The majority of data is stored in the installation directory, which defaults to /opt/gradle (unless otherwise specific in your Helm values file in the Helm Configuration section).

Capacity

The minimum capacity required for the installation directory for the embedded database case is 250 GB.

The minimum capacity required for the installation directory for the user-managed database case is 30 GB.

It is recommended to create a specific volume for the installation directory to avoid consuming the space required for Gradle Enterprise, and to ensure at least 10% of the volume’s space is free at all times.

The following are additional disk capacity requirements:

Location Storage Size

Location	Storage Size
`/tmp` ^[1]	1 GB
`/var/lib/rancher/k3s` ^[1]	30 GB

/tmp ^[1]

1 GB

/var/lib/rancher/k3s ^[1]

30 GB

¹ These are not particularly performance sensitive.

Performance

For production workloads, storage volumes should exhibit SSD-class disk performance of at least 3000 IOPS (input/output operations per second). Most NFS based storage or desktop-class, non-SSD disk drives do not provide this level of performance.

Disk performance has a significant impact on Gradle Enterprise performance.

6. Network Connectivity

Gradle Enterprise requires network connectivity for periodic license validation.

An installation of Gradle Enterprise will not start if it cannot connect to both registry.gradle.com and harbor.gradle.com.

It is strongly recommended that production installations of Gradle Enterprise are configured to use HTTPS with a trusted certificate.

When installing Gradle Enterprise, you will need to provide a hostname, such as ge.example.com.

For Airgap installations, you will need a temporary machine that can access the internet to download installation files. You will need to transfer those files from the machine to your Gradle Enterprise host of choice.

Helm Configuration

Installation options for Grade Enterprise are depicted in a Helm values file.

Follow the instructions in the Standalone Helm Chart Configuration Guide and return to this document with a complete values.yaml file.

Installation

In this section you will install Gradle Enterprise on your host.

For those installing Gradle Enterprise on a host without public network connectivity, please follow the Airgap installation instructions.

1. Copy Files

Makes sure that your Gradle license file and your Helm values file are available on your host machine.

2. Install K3s

Install K3s and make it available to the current user:

$ curl -sfL https://get.k3s.io | sh -

$ sudo chown $UID /etc/rancher/k3s/k3s.yaml

$ mkdir -p "${HOME}/.kube"

$ ln -sf /etc/rancher/k3s/k3s.yaml "${HOME}/.kube/config"

Verify that you can interact with the K3s cluster:

$ kubectl get ns

The expected output should be similar to this:

NAME                STATUS   AGE
default             Active   1h
kube-system         Active   1h
kube-public         Active   1h
kube-node-lease     Active   1h

For more information on K3s installation, see the K3s Quick-Start Guide and K3s Installation.

3. Install Helm

Gradle Enterprise requires Helm version 3.5.x (or later) to install.

It is recommended to use the latest version available as this will have all known security vulnerabilities addressed. This document describes the maximum version skew supported between Helm and Kubernetes.

For more information on installing Helm (including alternate installation approaches), see Installing Helm.

Install Helm with the following command:

$ curl https://raw.githubusercontent.com/helm/helm/main/scripts/get-helm-3 | bash

Verify that helm is installed and working:

$ helm version

The expected output should be similar to this:

version.BuildInfo{Version:"v3.11.1", GitCommit:"293b50c65d4d56187cd4e2f390f0ada46b4c4737", GitTreeState:"clean", GoVersion:"go1.19.1"}

4. Install the Helm chart

Gradle Enterprise is distributed from the Gradle Enterprise Helm repository.

Add the Gradle Enterprise Helm repository to your Helm installation and fetch its contents into the local cache:

$ helm repo add gradle https://helm.gradle.com/

$ helm repo update gradle

Verify that the Gradle Enterprise chart is accessible:

$ helm search repo gradle-enterprise

This will report the latest versions available for the two Gradle Enterprise charts:

NAME                               	CHART VERSION	APP VERSION	DESCRIPTION
gradle/gradle-enterprise           	2023.2.0        2023.2      Official Gradle Enterprise chart for Kubernetes cluster installations
gradle/gradle-enterprise-standalone	2023.2.0        2023.2      Official Gradle Enterprise chart for standalone installations

This guide covers installation of the gradle-enterprise-standalone chart. Installation of the gradle-enterprise chart is covered in the Self-Hosted Kubernetes Installation Guide.

5. Install Gradle Enterprise

Install Gradle Enterprise by running:

$ helm install \
    --create-namespace --namespace gradle-enterprise \(1)
    ge-standalone \(2)
    gradle/gradle-enterprise-standalone \(3)
    --values values.yaml \(4)
    --set-file global.license.file=./gradle-enterprise.license (5)

1	This example uses gradle-enterprise as the namespace, but it can be a custom name. If you use a custom name, update all other example commands accordingly.
2	This is the Helm release name. It is used by Helm to identify the Gradle Enterprise installation.
3	The Gradle Enterprise chart to install, in this case, `gradle/gradle-enterprise-standalone`. To install a specific version, use `--version 2023.2.0`.
4	The Helm values file with configuration values, including items such as the hostname.
5	The Gradle Enterprise license file (if not already included in values file).

6. Start Gradle Enterprise

At this point, it should be possible to see the Helm release installed:

$ helm --namespace gradle-enterprise list

NAME         	NAMESPACE        	REVISION	UPDATED                                	STATUS  	CHART                                	APP VERSION
ge-standalone	gradle-enterprise	1       	2023-07-18 03:01:58.704019291 +0000 UTC	deployed	gradle-enterprise-standalone-2023.2.0  	2023.2

You can inspect the status of the Gradle Enterprise pods:

$ kubectl --namespace gradle-enterprise get pods

NAME                                               READY   STATUS    RESTARTS   AGE
gradle-enterprise-operator-76694c949d-md5dh        1/1     Running   0          84m
gradle-monitoring-5545d7d5d8-lpm9x                 1/1     Running   0          84m
gradle-proxy-0                                     1/1     Running   0          83m
gradle-database-65d975cf8-dk7kw                    2/2     Running   0          83m
gradle-enterprise-app-0                            1/1     Running   0          83m
gradle-metrics-cfcd8f7f7-zqds9                     1/1     Running   0          83m
gradle-test-distribution-broker-6fd84c6988-x6jvw   1/1     Running   0          83m
gradle-build-cache-node-57b9bdd46d-2txf5           1/1     Running   0          84m
gradle-keycloak-0                                  1/1     Running   0          83m

Gradle Enterprise has a /ping endpoint, which can be used to verify network connectivity with Gradle Enterprise.

Connectivity to Gradle Enterprise installation can be tested by running the following command on machines which need to connect to Gradle Enterprise:

$ curl -sw \\n --fail-with-body --show-error https://«gradle-enterprise-host»/ping

It should return SUCCESS.

Once all pods have a status of Running and the system is up and connected, you can interact with Gradle Enterprise by visiting its URL in a web browser (i.e. the hostname).

Congratulations Gradle Enterprise is installed and running. Head over to the Post Installation section for next steps.

Airgap Installation

In an airgap installation, the container images are preloaded into K3s. Helm is then configured so that no attempt is made to pull images from the outside world.

Airgap installations require a specific entitlement on your license. If you need an Airgap-enabled license, please contact your customer success representative.

1. Overview

Airgap installation involves downloading files, transferring them, installing supporting software, and running helm install.

When installing Gradle Enterprise, follow the installation manual for that version as the steps may have changed. See Gradle Enterprise releases for information about the available versions.

We recommend you save all the files into a single transfer directory, so that it is easy to transfer to the host where you are installing Gradle Enterprise. For example:

$ mkdir gradle-enterprise-installation-files && cd gradle-enterprise-installation-files

2. Download K3s

Download and verify the K3s images, binary, and install script:

$ curl -s https://api.github.com/repos/k3s-io/k3s/releases/latest | jq -r '.tag_name'

$ curl -s https://api.github.com/repos/k3s-io/k3s/releases/latest | jq -r '.tag_name'

$ curl -L -o install_k3s.sh https://get.k3s.io

$ echo "6d41ae24985061f6fcfd80bad1162ab39cfd40308f68956f22794be816b0245f  k3s" | sha256sum -c

$ echo "6e5f11b00586df7ea517d996c5a26637c4c99f869cb42296ccaccaff59e7df96  k3s-airgap-images-amd64.tar.gz" | sha256sum -c

If you are running Red Hat Enterprise Linux with SELinux enabled, you will also need to download and verify the K3s SELinux Policy package:

$ curl -L -o k3s-selinux.el8.noarch.rpm https://github.com/k3s-io/k3s-selinux/releases/download/v1.2.stable.2/k3s-selinux-1.2-2.el8.noarch.rpm

$ echo "e949fde3e0255c6b5ce3f52db4277897882ed1664e87bfcf5122df5e96559340  k3s-selinux.el8.noarch.rpm" | sha256sum -c

3. Download Helm

Download and verify the Helm binary:

$ curl -L -o helm-linux-amd64.tar.gz https://get.helm.sh/helm-v3.11.1-linux-amd64.tar.gz

$ echo "0b1be96b66fab4770526f136f5f1a385a47c41923d33aab0dcb500e0f6c1bf7c  helm-linux-amd64.tar.gz" | sha256sum -c

4. Download Bundle

Save your Gradle Enterprise license to the transfer directory as gradle-enterprise.license.

Download and verify the airgap bundle:

$ curl -LOJd @gradle-enterprise.license https://registry.gradle.com/airgap/gradle-enterprise-standalone-2023.2-bundle.tar.gz

$ curl -LOJd @gradle-enterprise.license https://registry.gradle.com/airgap/gradle-enterprise-standalone-2023.2-bundle.tar.gz.sha256

$ sha256sum -c gradle-enterprise-standalone-2023.2-bundle.tar.gz.sha256

If checksum verification fails, check the contents of the downloaded files for error messages. If the error message indicates that your license is invalid/expired/not airgap enabled, you will need to request an updated license file by contacting your customer success representative.

Instead of running the above curl commands, you can download the airgap bundle by navigating to https://registry.gradle.com/airgap in your browser and following the instructions on the page.

5. Download Helm Values File

Download and verify the example Helm values file:

$ curl -L -o example.values.yaml https://docs.gradle.com/enterprise/helm-standalone-installation/values-2023.3/gradle-enterprise-standalone-values-2023.3.yaml

$ curl -L -o example.values.yaml.sha256 https://docs.gradle.com/enterprise/helm-standalone-installation/values-2023.3/gradle-enterprise-standalone-values-2023.3.yaml.sha256

$ echo "$(cat example.values.yaml.sha256)  example.values.yaml" | sha256sum -c

6. Update the Values File

Before transferring files to your host, make sure your Helm values file from the Helm Configuration is updated in your transfer directory.

You can use the example values.yaml file from the previous section to check for any missing configuration.

7. Transfer Files

Check that the transfer directory contains the following files (additional files are fine):

k3s-airgap-images-amd64.tar.gz
k3s
install_k3s.sh
k3s-selinux.el8.noarch.rpm (only if you are running SELinux)
helm-linux-amd64.tar.gz
gradle-enterprise.license
values.yaml
gradle-enterprise-standalone-2023.2-bundle.tar.gz
Optional: SSL certificates

Once you’ve verified that you have the required files, transfer them to the host where you are installing Gradle Enterprise.

8. Install K3s

Follow these instructions on the host where you are installing Gradle Enterprise with your transferred files present in the current directory.

If you are running Red Hat Enterprise Linux with SELinux enabled:
1. Install the container-selinux package. This is a package that can be found in Red Hat Enterprise Linux’s default repository. Install this package on the airgapped server just like you would install any other package. If your organization has an internal mirror of the Red Hat package repositories, you can run:
  $ sudo yum install -y container-selinux
2. Install the K3s SELinux Policy package:
  $ sudo yum install -y k3s-selinux.el8.noarch.rpm

Install K3s and make it available to the current user:

$ sudo mkdir -p /var/lib/rancher/k3s/agent/images/

$ sudo cp k3s-airgap-images-amd64.tar.gz /var/lib/rancher/k3s/agent/images/

$ (cd /var/lib/rancher/k3s/agent/images/ && sudo gunzip -f k3s-airgap-images-amd64.tar.gz)

$ sudo cp k3s /usr/local/bin

$ sudo chmod a+rx /usr/local/bin/k3s

$ sudo chmod a+rx ./install_k3s.sh

$ INSTALL_K3S_SKIP_DOWNLOAD=true ./install_k3s.sh

$ sudo chown $UID /etc/rancher/k3s/k3s.yaml

$ mkdir -p "${HOME}/.kube"

$ ln -sf /etc/rancher/k3s/k3s.yaml "${HOME}/.kube/config"

Verify that you can interact with the K3s cluster:

$ kubectl get ns

The expected output should be similar to this:

NAME                STATUS   AGE
default             Active   1h
kube-system         Active   1h
kube-public         Active   1h
kube-node-lease     Active   1h

9. Install Helm

Follow these instructions on the host where you are installing Gradle Enterprise with your transferred files present in the current directory.

To install Helm:

$ tar -zxvf helm-linux-amd64.tar.gz

$ sudo mv linux-amd64/helm /usr/local/bin/helm

Verify that helm is installed and working:

$ helm version

The expected output should be similar to this:

version.BuildInfo{Version:"v3.11.1", GitCommit:"293b50c65d4d56187cd4e2f390f0ada46b4c4737", GitTreeState:"clean", GoVersion:"go1.19.1"}

10. Install Gradle Enterprise

Follow these instructions on the host where you are installing Gradle Enterprise with your transferred files present in the current directory.

Install Gradle Enterprise:

$ tar zxvf gradle-enterprise-standalone-2023.2-bundle.tar.gz

$ k3s ctr images import gradle-enterprise-standalone-2023.2-images.tar (1)

1	This command imports the images into K3s.

$ helm install \
    --create-namespace --namespace gradle-enterprise \ (1)
    ge-standalone \ (2)
    gradle-enterprise-standalone-2023.2.0.tgz \
    --values values.yaml \ (3)
    --set-file global.license.file=./gradle-enterprise.license (4)

1	This example uses gradle-enterprise as the namespace, but it can be a custom name. If you use a custom name, update all other example commands accordingly.
2	This is the Helm release name. It is used by Helm to identify the Gradle Enterprise installation.
3	The Helm values file with configuration values, including items such as the hostname.
4	The Gradle Enterprise license file (if not already included in values file).

10. Start Gradle Enterprise

You can see the status of Gradle Enterprise starting up by examining its pods.

$ kubectl --namespace gradle-enterprise get pods

NAME                                              READY   STATUS              RESTARTS   AGE
gradle-enterprise-operator-76694c949d-md5dh       1/1     Running             0          39s
gradle-monitoring-5545d7d5d8-lpm9x                1/1     Running             0          39s
gradle-database-65d975cf8-dk7kw                   0/2     Init:0/2            0          39s
gradle-build-cache-node-57b9bdd46d-2txf5          0/1     Init:0/1            0          39s
gradle-proxy-0                                    0/1     ContainerCreating   0          39s
gradle-metrics-cfcd8f7f7-zqds9                    0/1     Running             0          39s
gradle-test-distribution-broker-6fd84c6988-x6jvw  0/1     Init:0/1            0          39s
gradle-keycloak-0                                 0/1     Pending             0          39s
gradle-enterprise-app-0                           0/1     Pending             0          39s

Eventually the pods should all report as Running:

$ kubectl --namespace gradle-enterprise get pods

NAME                                               READY   STATUS    RESTARTS   AGE
gradle-enterprise-operator-76694c949d-md5dh        1/1     Running   0          4m
gradle-monitoring-5545d7d5d8-lpm9x                 1/1     Running   0          4m
gradle-proxy-0                                     1/1     Running   0          3m
gradle-database-65d975cf8-dk7kw                    2/2     Running   0          3m
gradle-enterprise-app-0                            1/1     Running   0          3m
gradle-metrics-cfcd8f7f7-zqds9                     1/1     Running   0          3m
gradle-test-distribution-broker-6fd84c6988-x6jvw   1/1     Running   0          3m
gradle-build-cache-node-57b9bdd46d-2txf5           1/1     Running   0          4m
gradle-keycloak-0                                  1/1     Running   0          3m

Once all pods have a status of Running and the system is up and connected, you can interact with it by visiting its URL in a web browser (i.e. the hostname).

11. Cleanup

It is recommended to remove the following files after installation:

k3s-airgap-images-amd64.tar.gz
k3s
install_k3s.sh
k3s-selinux.el8.noarch.rpm
helm-linux-amd64.tar.gz
gradle-enterprise-standalone-2023.2-bundle.tar.gz
gradle-enterprise-standalone-2023.2.tgz
gradle-enterprise-standalone-2023.2-images.tar

Once Gradle Enterprise has been installed, files used during installation are not required at runtime and can be removed if desired. However, the following files may be useful to preserve, as they may aid in future upgrades or maintenance:

Helm values files
SSL certificates
Gradle Enterprise license

Care should be applied when handling these files as they may be considered sensitive.

Congratulations Gradle Enterprise is installed and running.

Post-Installation

Many features of Gradle Enterprise, including access control, database backups, and Build Scan retention can be configured in Gradle Enterprise, once it is running. Consult the Gradle Enterprise Administration guide to learn more.

For instructions on how to start using Gradle Enterprise in your builds, consult the Getting Started with Gradle Enterprise guide.