This manual covers the installation and operation of Gradle Enterprise. It is useful for administrators and maintainers of Gradle Enterprise installations, and build engineers that maintain or develop Gradle or Apache Maven™ builds that leverage Gradle Enterprise.

If you’re interested on deploying Gradle Enterprise into your own Kubernetes cluster, jump into these specific instructions.

Installation

Gradle Enterprise leverages Replicated for installation, configuration and software updates. Replicated orchestrates downloading and installing the Gradle Enterprise application on the host system as well as checking for periodic updates.

Replicated, as well as the Gradle Enterprise application both run on the host in the form of Docker containers. Management of these containers is done transparently by Replicated, however regular Docker commands can be used to inspect the status of running containers.

While the regular docker commands can be used to manage Gradle Enterprise application containers, it is highly recommended that maintenance actions such as starting and stopping the application be done via the Replicated admin console.

Before you install

This section outlines the installation resource requirements and configuration aspects that need to be resolved during installation.

Supported operating systems

Server versions of the following Linux distributions are supported:

  • Debian 7.7+

  • Ubuntu 14.04.5 / 16.04 / 18.04 / 20.04

  • Red Hat Enterprise Linux 6.5+, 7.4 - 7.8

  • CentOS 6+, 7.4 - 7.8

  • Amazon Linux 2014.03 / 2014.09 / 2015.03 / 2015.09 / 2016.03 / 2016.09 / 2017.03 / 2017.09 / 2018.03 / 2.0

  • Oracle Linux 6.5+

The host system must support docker-engine, 1.7.1 or greater, which requires a 64-bit distribution with a kernel minimum of 3.10. For detailed requirements and installation guides see the docker installation docs.

Installing on non-Linux systems

Gradle Enterprise requires a modern Linux operating system with Docker support. For trial and evaluation purposes, you can use a virtual machine to perform the installation on a non-Linux system. Several desktop virtual machine providers, such as VirtualBox, exist for this purpose.

Virtualized installation considerations

Some considerations when using virtualization in conjunction with Gradle Enterprise are:

  • Any of the above listed Linux distributions will still work, even in a virtualized environment.

  • You will need to forward the necessary ports to the host system in order to configure Gradle Enterprise and access the application.

    Newer versions of MacOS may have built-in services listening on these ports, in particular, port 8800. If you encounter errors binding to these ports you may need to forward them to a different port on your host.
  • When using a virtual machine provider such as VirtualBox, the IP of your virtualized environment will differ depending on how you have configured networking for the virtual machine. For example, with VirtualBox, if you have set it up with the default networking mode (NAT), then the IP address of the Gradle Enterprise installation will be the same as that of your host system.

    When running in NAT networking mode, a VirtualBox machine will not be able to communicate with a service running on the host system. This has the implication that a virtualized Gradle Enterprise installation will not be able to communicate with a remote build cache node running on the same host as the VirtualBox instance. For this, you will need to investigate a different network mode (such as Host-only), or you will need to install the build cache node on a different host within your organization.
  • If you remap the ports 80 or 443 of your virtual machine, you will need to ensure that the Gradle Enterprise ports are reconfigured to match on the Settings page of the admin console. Failing to do this will cause some areas of the Gradle Enterprise UI to go to an incorrect address, and the server will generate an incorrect URL for build scans.

  • Gradle Enterprise can consume a considerable amount of disk space depending on how actively it is used. Keep this in mind when provisioning a virtual disk. Also, depending on the virtualization method used, disk performance may not be consistent with native disk access so Gradle Enterprise performance is likely to be affected.

Using desktop virtualization software such as VirtualBox or Vagrant is not recommended for production deployments.

Storage requirements

Capacity

Gradle Enterprise stores the majority of its data in its “installation directory”, which defaults to /opt/gradle. The recommended minimum initial capacity to provide for this directory is 250 GB.

The amount of space used and rate of growth is dependent on your usage of Gradle Enterprise. See the disk usage management section for how to avoid running out of disk space for the installation directory.

The following are additional disk capacity requirements:

Location

/tmp

1 GB

/var/lib/docker

30 GB

/var/lib/replicated

1 GB

Performance

Disk performance has a significant impact on Gradle Enterprise. For production workloads, storage volumes should exhibit SSD-class disk performance of at least 3000 input/output operations per second (IOPS). Most desktop-class, non-SSD disk drives do not provide this level of performance.

You can run the following benchmark to estimate your disk performance:

docker run --rm -v /opt/gradle/fs-test:/var/lib/postgresql/data postgres pg_test_fsync

The majority of reported results should indicate greater than 3000 ops/sec.

Amazon Web Services

If you are using Amazon Web Services (AWS) and Elastic Block Storage (EBS) to host your Gradle Enterprise instance you should ensure that you provision 3000 or more IOPS for the data volume. Keep in mind that general purpose (or gp2) volumes are limited to 3 IOPS per gigabyte, meaning that 200 GB volume will only provide a maximum of 600 IOPS. If you are provisioning a volume smaller than 2TB you should consider using a provisioned IOPS (or io1) volume.

The recommendations above are based on average workloads. For projects with more complex builds or teams that produce a large number of build scans, Gradle Enterprise may require higher I/O performance than suggested.

CPU & memory requirements

  • Quad-core 2GHz or better CPU

  • 16 GB free RAM

Networking configuration

The following TCP ports on the host system are used by the application:

Port Network Interface Required Description

80

Public

When SSL is disabled

HTTP port used to access the application

443

Public

When SSL is enabled (default)

HTTPS port used to access the application

8800

Public

Always

System admin console

9870-9881

Public

Always

Replicated Operator

5432

docker0

Always

PostgreSQL database

22003

docker0

Always

Internal metrics collection

8080-8084

docker0

Always

Build scans and build cache servers

Only ports 443 (or 80 if not using HTTPS) and 8800 are required to be accessible from outside the host. All the other ports are used for inter-process communication on the host itself over the specified network interface.

Internet access

In addition to the ports listed above the host system will also need access to the internet for retrieving application images, syncing license information, etc. Depending on your firewall or proxy configuration you may need to whitelist individual websites. Please refer to this document for detailed information on all external websites necessary for installation and proper system function.

If internet access is not possible you can still install Gradle Enterprise via an airgapped installation.

Application hostname

When installing Gradle Enterprise, you will be asked to provide a hostname. This should be the hostname that users of the installation use to access it and therefore should resolve within your network.

This value can be changed later.

If you are unsure what name to assign, or you do not yet have a hostname assigned, you can use the public IP address of the server, or localhost if you only intend to access the installation from the same host for the time being.

The public IP address is the IP address you would use to SSH on to the host system.

If you are using a proxy or external SSL termination server, you should enter the hostname of this service as it is this name that people will use to access Gradle Enterprise.

HTTPS SSL Certificate

It is strongly recommended that production installations of Gradle Enterprise are configured to use HTTPS with a trusted certificate, or to use an external SSL terminating server to secure your data whilst in transit.

If you do not have a certificate to use you may either:

  1. Allow Gradle Enterprise to generate an untrusted, self-signed, certificate

  2. Disable HTTPS and use plain HTTP

Using an untrusted certificate requires extra build script configuration for both build scans and the build cache, in addition to requiring users to accept the untrusted connection in their browser each time they access the application. However, your data will be encrypted whilst in transit on the network.

Using plain HTTP means that no extra build or browser configuration is required, but your data will not be encrypted while in transit on the network.

Untrusted SSL certificates

By default, Gradle Enterprise uses the default trust settings of the Java runtime that it ships with when connecting to other systems using SSL. If your organization uses certificates that are not signed by a trusted certificate authority, you must perform additional configuration for this to work. This may be the case if you use self-signed certificates or an internal certificate authority.

Additional certificates to trust can be configured by during installation/configuration by enabling “Trust additional certificates for SSL communication” and uploading all required certificates as a single PEM file.

If using self-signed certificates, the certificate of each service must be uploaded. If using an internal certificate authority, its certificate must be uploaded.

HTTP and access control

When Gradle Enterprise is configured to use HTTP instead of HTTPS, it must be accessed via a private IP address when access control is enabled. This also applies when using external HTTPS termination. This is a security restriction that reduces the risk of secrets being transmitted without encryption being stolen.

A private IP address is any within ranges 10.0.0.0/8, 172.16.0.0/12 or 192.168.0.0/16.

Installation

Gradle Enterprise supports multiple installation mechanisms.

Standard installation is recommended as it is simple and requires few steps. It requires the host system to have Internet access.

Once installed, Gradle Enterprise does not require a connection to the Internet. It is possible to only establish an Internet connection for the host system for the initial install and to obtain subsequent updates manually.

Airgapped installation can be performed on a host without an Internet connection. Installation materials are downloaded from a system with Internet access and then manually transferred to the host system.

Some non-essential Gradle Enterprise functions may not be available when operating without an Internet connection.

Airgapped installations are not available for trial licenses.

Standard

Installing the Replicated admin console
  1. During installation you will be asked for any required proxy settings. You should have this information on hand before proceeding with the next step. Later you may also be prompted to supply the host’s public IP address if the installer was unable to automatically detect it. If this happens, the IP address should be left blank.

    If you intend to run the Gradle Enterprise application with SSL enabled (which is recommended) you should also have the public certificate and private key available prior to beginning installation.

  2. Install Replicated on the target host by issuing the following command on the host system.

    curl -sSL https://get.replicated.com/docker/gradleenterprise/stable | sudo bash
    As part of the installation procedure, Replicated will create a user replicated (if one doesn’t exist already), and add it to the docker group of users.
    If you already have Docker installed, Replicated will warn you about overwriting it with a newer version. You may either let Replicated do this, or continue to use the version currently installed on your system. Please pay attention to the supported Docker versions reported in the warning from Replicated.
  3. Open a web browser and navigate to https://«hostname»:8800 to access the Replicated admin console.

  4. Enter a valid Hostname used by the Replicated admin console. This name should be routable on your network and resolve to the IP address of the host system. It will be used when generating self-signed certificates for the Replicated admin console.

  5. For SSL used by the Replicated admin console you can either use self-signed certificates or provide your own.

    1. To use self-signed certificates simply select Use Self-Signed Cert.

    2. To provide your own certificates provide files for Private Key and Certificate and select Upload & Continue.

    install ssl 2017.7
    These settings can always be changed later via the Console Settings screen, accessible under the install gear icon icon in the upper-right corner of the Replicated admin console.
  6. Select Choose License and navigate to the location of the license file which was sent to you via email.

    install license 2017.7
  7. Choose a method for securing the Replicated admin console. Either Anonymous or Password, and select Continue.

    install password 2018.3
    Should you choose to change these settings later, you can do so by visiting https://«hostname»:8800/create-password.
  8. The system will perform some pre-flight checks to test the host system for compatibility. Although the software can be installed without passing these checks it is highly recommended that any deficiencies be addressed. Proper system functionality cannot be guaranteed if the host system does not meet the required criteria.

    install preflight check 2017.7

    Select Continue.

After installing the Replicated admin console the application will begin downloading in the background. When the download is complete installation will begin automatically. At any time you can select Dashboard from the navigation menu to see the current status of the application.

You will be presented with a screen to allow you to customize various application settings. Changes to these settings can be made at any time. Changes will only take effect after selecting Save on the bottom of the Settings page.

Selecting Save will require the application to restart for changes to take effect. Select Restart Now to restart the application and apply the new settings. If the application is in the process of starting (during initial installation) then changes will be applied when the application finishes starting. Changes to a stopped application will apply the next time the application is started.
Upgrading

Before upgrading, be sure to check the Upgrade notes section for any special considerations when upgrading from older versions of Gradle Enterprise.

  1. Open a web browser and navigate to https://«hostname»:8800 to access the Replicated admin console.

  2. Checks for updates are done periodically. When an update is available you will see something similar to the screen below. You can explicitly check for updates at any time by selecting Check Now.

    update dashboard 2019.2
  3. Select View Update.

  4. On the Release History screen select Install Update to install the latest released version.

    Updating requires the application to be temporarily shutdown. This means the application will not be accessible and information for builds run during this downtime period will not be captured.
    update install 2017.7
  5. The updated application images will be downloaded and installation will begin immediately once the download has completed.

  6. Select Dashboard from the navigation menu. The status Started will be shown when installation is complete and the application is up and running.

    update started 2017.7

After upgrading, Docker may keep older Gradle Enterprise images on disk. These unused images can consume a significant amount of disk space. You can clear up space taken by unused Docker images at any time by running the following command:

docker images --filter dangling=true -q | xargs docker rmi

Airgapped

Installation

In an airgapped installation, you will need to first install Docker on the host system, since the automated installer will not install it for you. You can refer to this guide for information about installing Docker in an airgapped fashion. After a compatible version of Docker is installed, follow the instructions below.

Replicated already performs Docker cleanup management such as deleting dangling images or removing stopped containers. In an airgapped environment, there might be a race condition while executing docker system prune and the restart of containers, leading to a deletion of a required Docker image. Therefore, it’s not recommended to perform this kind of manual cleanup.
  1. Along with your provided license file you will be given a link and password to access the Gradle Enterprise airgap bundle download page.

  2. Select Get Download Link and download the airgap bundle.

    If using wget to download the airgap bundle you will need to use the --trust-server-names option or rename the downloaded file to .airgap. You may also need to surround the URL with quotes (").
  3. Transfer the airgap bundle to the host system.

  4. Download the Replicated admin console installer.

  5. Transfer the installer bundle to the host system.

  6. Run the Replicated admin console installer.

    tar xzvf replicated.tar.gz
    cat ./install.sh | sudo bash -s airgap
  7. Open a web browser and navigate to https://«hostname»:8800 to access the Replicated admin console.

  8. Enter a valid Hostname used by the Replicated admin console. This name should be routable on your network and resolve to the IP address of the host system. It will be used when generating self-signed certificates for the Replicated admin console.

  9. For SSL used by the Replicated admin console you can either use self-signed certificates or provide your own.

    1. To use self-signed certificates simply select Use Self-Signed Cert.

    2. To provide your own certificates provide files for Private Key and Certificate and select Upload & Continue.

    install ssl airgap 2017.7
    These settings can always be changed later via the Console Settings screen, accessible under the install gear icon icon in the upper-right corner of the Replicated admin console.
  10. At the following screen, select Choose license and select the license file which was sent to you via email.

    install license airgap 2017.7
  11. Then on the next screen choose Airgapped and click Continue

    install choose installation airgap 2017.7
  12. Enter the location of the .airgap file you downloaded and transferred earlier.

    install airgap package 2017.7
  13. Select Continue.

  14. After the airgap packages have been extracted, choose a method for securing the Replicated admin console. Either Anonymous or Password, and select Continue.

    install password 2018.3
    Should you choose to change these settings later, you can do so by visiting https://«hostname»:8800/create-password.
  15. The system will perform some pre-flight checks to test the host system for compatibility. Although the software can be installed without passing these checks it is highly recommended that any deficiencies be addressed. Proper system functionality cannot be guaranteed if the host system does not meet the required criteria.

    install preflight check 2017.7

    Select Continue.

You will be presented with a screen to allow you to customize various application settings. Changes to these settings can be made at any time. Changes will only take effect after selecting Save on the bottom of the Settings page.

Selecting Save will require the application to restart for changes to take effect. Select Restart Now to restart the application and apply the new settings. If the application is in the process of starting (during intial installation) then changes will be applied when the application finishes starting. Changes to a stopped application will apply the next time the application is started.
Upgrading
  1. Check in the release notes whether Replicated has been upgraded as part of the release. If so, follow steps 4-6 in the Installation section above to upgrade to the required Replicated version.

  2. Confirm the update path used to search for new airgap bundles. The Replicated admin console will look for updates in this folder. You can configure this in the Airgap Settings settings section of the Console Settings page which is accessible via the install gear icon in the navigation menu.

    update airgap 2017.7
  3. Follow steps 1-3 in the Installation section above to get the latest airgap bundle. You will want to place the .airgap file in the location confirmed in the step above.

  4. You can now upgrade the system using the instructions in the Upgrading section.

Auto start

The Gradle Enterprise installer configures your system to automatically start Gradle Enterprise on system reboot.

Unattended installation

Gradle Enterprise can be installed without user intervention, by specifying configuration options in files before starting the installer. This allows scripted installations or installation by configuration management tools. For assistance in performing an unattended installation, please submit a support ticket at support.gradle.com.

Operation

Disk usage management

Gradle Enterprise stores the majority of its data in its “installation directory”, which defaults to /opt/gradle. The amount of space used and rate of growth is dependent on your usage of Gradle Enterprise. Administrators should take care to ensure that the volume this directory is on does not run out of space.

Monitoring

The Replicated admin console graphs the usage of the disk volume that contains the installation directory, over the last 30 days. It is strongly recommended to regularly verify that adequate disk space is available and will be available in the future.

disk usage

Alternatively, or in conjunction with, it is recommended to use a server monitoring solution to notify when free space is running low on the installation volume.

Build scan retention

For most installations, disk usage will be dominated by build scan data. The amount of data used and rate of growth is dependent on the number and size of builds being captured. By default, build scans are stored indefinitely.

To limit the amount of disk space used to store build scan data, enable the “Delete old build scans” option in the Replicated admin console. Each day, build scans for builds that occurred more than the specified number of days ago will be deleted.

delete old build scans

Active disk space monitoring and management

Gradle Enterprise can also monitor the amount of disk space free and can take various actions to stop the disk from running out of space.

It is recommended that administrators enable at least some of these settings, as recovering space from a completely full disk can be difficult.

disk usage thresholds 2019.2
Email warnings

An administrator can be notified if the installation’s free disk space goes below a given percentage. This requires administrator email details and SMTP server settings to be configured for the Gradle Enterprise instance.

SMTP with implicit TLS can’t be tested using this console. To test the setup with this option selected, please run replicated admin test-notification on the Gradle Enterprise host and verify that the output states Successfully sent out test notification!.
email settings 2019.3

The warning emails will be triggered when the system goes below the configured percentage of disk space free on the data volume, and will send further updates for each further percentage point change.

When an administrator receives a disk space warning email, they should review their data retention settings, and either:

  • Increase the disk space available to Gradle Enterprise, or

  • Enable the Delete old build scans setting if not enabled or reduce the number of days to retain build scans for

Deleting old build scans

The system can be configured to delete older build scans once disk space free goes below a given percentage. This will delete build scans, starting at the oldest, until disk space is above the configured threshold. This will happen even if the Delete old build scans setting is not enabled, and will delete build scans younger than the given retention window.

If some other process is filling up the Gradle Enterprise volume, the system may keep deleting build scans until none are left. This option should only be enabled on systems where the data volume is isolated from other processes and other things that might fill up a disk, such as log directories.

If an email warning threshold is set, administrators will be sent notification that scan deletion has been triggered. If no warning email threshold is set, no notification will be sent.

Rejecting incoming build scans

The system can be configured to reject incoming build scans once disk space free goes below a given percentage. Build scans will be rejected with an informative error message explaining the reason for the rejection. This stops the system from further increasing disk usage until the administrator can step in to resolve the issue.

An email notification will always be sent when the server starts rejecting build scans.

On a volume that only has Gradle Enterprise data, the following settings are recommended:

  • Warning emails at 15% free disk space.

  • Reject build scans at 5% free disk space. Gradle Enterprise needs a small amount of free space available to recover disk space when removing old data, so it is strongly recommended to stop incoming build scans before the disk is completely full.

  • Optionally delete older build scans at 10% free disk space.

Some things to consider:

  • If backups are created on the same volume, make sure to leave enough room for them in your thresholds. For example, if the total space that your backups take up is 40% of the disk, the above recommended settings would be 55%, 50% and 45%. This goes for any other data on the same volume.

    Backup location can be changed to a different volume by enabling the Use custom location for backup archives setting and specifying a Backup directory on a different volume.
  • If anything other than Gradle Enterprise could potentially write data to your data volume, it is recommended not to enable automatic deletion.

Backup and disaster recovery

Gradle Enterprise provides system backup and restore capabilities to facilitate disaster recovery. Backups can be triggered manually or scheduled to be done automatically on a periodic basis, and require no system downtime.

The backup process produces a single compressed archive which can be used to restore all user data to a state at the time of the backup. It is highly recommended that this archive additionally be copied to an off-host location, in the case of a complete loss of the host system or volume used to store backup archives.

In addition to disaster recovery, backup archives can be used to migrate your Gradle Enterprise data to a new host system. This can be useful in scenarios where a trial instance is promoted to a production one or in the event that you require upgrading your Gradle Enterprise instance hardware.

Only user data is captured in each backup. Replicated admin console settings, including SSL certificates, passwords, etc are not included in backup archives. We suggest making a note of such configuration options, to be used during the restore process in case of a complete loss of the system.

Creating backups

Backup settings can be configured on the Settings page of the Replicated admin console under the Backup section. The storage location of backup archives can be customized, as well as retention policies and email notifications which apply to both automatic and manual backups. You can additionally configure Gradle Enterprise to automatically perform backups on a regular schedule, either daily, weekly or via a custom schedule defined as a cron expression.

Email notifications

An administrator can be notified of the backup process outcome, which is particularly important in the case of failures. This requires administrator email details and SMTP server settings to be configured for the Gradle Enterprise instance.

SMTP with implicit TLS can’t be tested using this console. To test the setup with this option selected, please run replicated admin test-notification on the Gradle Enterprise host and verify that the output states Successfully sent out test notification!.
email settings 2019.3
Manual backups

In addition to configuring automatic scheduled backups, you may trigger a manual backup at any time by running the following command on the host system.

replicated admin backup
Tracking backup runtime

For instances with a large number of build scans, a backup may take an extended amount of time. Backup logs, as well as email notifications will include the time taken to perform the backup. In addition to inspecting logs, the Dashboard page of the Replicated admin console includes a graph of backup runtimes for the past 30 days.

backup runtime

Restoring from a backup

Once a backup archive is created you may use it to restore a Gradle Enterprise instance to the backup state at any time. Backup archives contain only a copy of the application database and not configuration settings entered in the Replicated admin console. If restoring to a completely new host you will first need to perform a fresh installation and restore any configuration options manually.

Executing the restore_snapshot.sh script requires 7zip to be installed on the host system. This can typically be done by installing the p7zip package using your Linux distribution’s package manager.
  1. If restoring to a new host, perform a fresh installation as described in the Installation section above.

  2. Copy the previously created backup archive to a location on the host system.

  3. Stop the server by visiting the Dashboard page of the Replicated admin console and selecting Stop Now.

  4. Execute the following command on the host system as root.

    /opt/gradle/tools/restore_snapshot.sh \
        -y \ # assume that the answer to any question which would be asked is yes. Useful for unattended executions"
        /opt/gradle/data/backups/backup.7z # location of backup archive
  5. When the script has completed, return to the Replicated admin console Dashboard and select Start Now.

Troubleshooting

Issues with the Replicated admin console

If you experience difficulty accessing the Replicated admin console then you may need to restart the Replicated services on the host system. To restart Replicated, issue the following commands:

Debian/Ubuntu
sudo service replicated restart
sudo service replicated-ui restart
sudo service replicated-operator restart
CentOS 7/RHEL 7/Fedora
sudo systemctl restart replicated replicated-ui replicated-operator

Resource usage

Standard Linux process utilities such as ps and top can be used to inspect the resource usage of the application.

Both Replicated and the application run in Docker containers. The following is sample output from running the command ps -aufx which displays the application’s processes.

process list

The Replicated admin console (https://«hostname»:8800/dashboard) also displays CPU and memory usage of the application’s Docker containers.

dashboard resource usage 2017.7
Both the Memory Usage and CPU Usage charts have a window of 15 minutes and are representative of the most recent usage data.

Alternatively, docker stats can be used to get more detailed resource usage information about the individual Docker containers.

docker stats

Support

If you are experiencing issues with Gradle Enterprise, the Gradle Build Scan plugin, or the Gradle Enterprise Maven extension please submit a support ticket at support.gradle.com, including details of the issue and an attached Support Bundle.

Support Bundles assist our engineers in troubleshooting your issue by providing the following information about your Gradle Enterprise installation:

  • Host Information

    • Operating System

    • CPU

    • Memory

    • Disk Usage

  • Logs

    • Gradle Enterprise

    • Replicated

  • Docker Configuration

  • Gradle Enterprise Database Statistics

Generating a support bundle

  1. Open a web browser and navigate to https://«hostname»:8800 to access the Replicated admin console.

    update dashboard 2019.2
  2. Select Support from the navigation menu.

    support dashboard 2019.2
  3. Click the Download Support Bundle button.

    Generation of the Support Bundle may take several minutes to complete. Once the Support Bundle has been generated it will be automatically downloaded.

Access control

Gradle Enterprise supports individual user login and access control. User accounts and permissions can be created and managed locally in Gradle Enterprise, or can be sourced from an LDAP service, including Active Directory, or a SAML 2.0 identity provider.

Setup

Access control can be enabled on the Settings page of the Replicated admin console under the Access control section.

  1. Select the “Enable access control” option. An initialization key will now be visible, which is required in a subsequent step.

    access control enable 2018.5
  2. Click Save and choose Restart Now when prompted. You will need to wait for Gradle Enterprise to restart before continuing.

  3. Copy the Initialization key and follow the link to https://«hostname»/admin/init to initialize the system user account.

    access control initialization key 2018.5
  4. Enter the initialization key into the box provided and click Access.

  5. The system user account has a fixed username of system. Enter a password to use for the system user account and click Initialize.

    access control system user setup 2019.1
  6. The system user account has now been initialized and can be used to either create local users or configure an external identity provider.

Build scan viewing and publishing

By default, Gradle Enterprise disables anonymous viewing of build scans but enables anonymous publishing of build scans.

access control anon scan access 2019.4

When anonymous build scan viewing or publishing is disabled, users must also be granted the associated access control role to be able to view or publish build scans. Assigning users to access control roles is discussed in subsequent sections.

Authenticated build scan publishing requires individual users configuring access keys for their build environment which may be an impediment when initially evaluating and trialling Gradle Enterprise. For production installations, it is recommended to disable anonymous build scan publishing. Please consult the Gradle Enterprise Gradle Plugin User Manual or Gradle Enterprise Maven Extension User Manual for guidance on how to configure a build environment for authenticated build scan publishing.

Create local users

To create local user accounts, log in as the system user or a user account that has the required permissions. It is recommended to only use the system account to create the first administrator account, and subsequently use an administrator account to create further accounts.

  1. Navigate to the user list at https://«hostname»/admin/users, and click Add.

    access control users 2019.2
  2. Complete the form, including the required roles, and click Save.

    access control add user 2019.4

Required fields

Users have four required fields:

  • Username

  • First name

  • Last name

  • Email

Both username and email must be unique in the system.

Roles

Role Description

Build scan view

Allows viewing of build scans and associated functions (when anonymous build scan viewing is disabled)

Build scan publish

Allows publishing of build scans (when anonymous build scan publishing is disabled)

Export API

Allows use of the Export API

Cache Admin

Allows administration of build cache functionality

Admin

Allows general administration of Gradle Enterprise (e.g. access control)

Test distribution

Allows distributing test execution via Gradle Enterprise

Passwords

New local user accounts must be given a temporary password. Users will be prompted to change this password when they log in to Gradle Enterprise for the first time.

Configure an external identity provider

Gradle Enterprise can be configured to use an external identity provider for authentication, instead of requiring local user accounts. The supported protocols are SAML 2.0 and LDAP. Authorization, by role membership, can optionally also be managed at the identity provider.

You will need to log in as the system user or a user account that has the required permissions for Gradle Enterprise administration.

You cannot log in with a user account at an external identity provider that has the same username as a local user account. If this is the case, you need to use the system user account to delete the local user account and configure the external identity provider.

SAML 2.0

  1. Navigate to the identity provider page at https://«hostname»/admin/providers.

    access control identity provider 2019.2
  2. Choose “SAML 2.0” from the provider type list and click Add.

  3. Create a SAML application at your identity provider using the provided “SSO Url” and “SP Entity Id”.

  4. Download the metadata for the SAML application from your identity provider, and select this file for the “Identity provider metadata file” field.

    access control saml provider details 2019.4
  5. Enter a name for the identity provider, this will be used for the button on the log in page, and click Save.

Roles

By default, users' roles are defined by your Identity Provider. Enter the SAML attribute name that will contain the roles, and Gradle Enterprise will link roles for users when they log in.

With standard role mapping, the roles assigned at your SAML identity provider must exactly match the following:

Role Description

ge-scans-viewing

Allows viewing of build scans and associated functions (when anonymous build scan viewing is disabled)

ge-scans-publishing

Allows publishing of build scans (when anonymous build scan publishing is disabled)

ge-cache-administration

Allows administration of build cache functionality

ge-administration

Allows general administration of Gradle Enterprise (e.g. access control)

ge-distributed-testing

Allows distributing test execution via Gradle Enterprise

You can also specify custom SAML role names when configuring your provider (note that that above role names are reserved and cannot be entered as custom names). It is possible to only enter custom names for some roles and leave others to be the default, or to use the same custom name for more than one role and thus define aggregated roles.

Export API access control does not support SAML and requires a local user account for access when using a SAML based identity provider. Role changes made at the SAML identity provider will only take affect after either a user initiated logout, administrator force logout, or session expiry.

It is also possible to define role membership in Gradle Enterprise, and to specify default roles that a user will receive when they first log in.

To do this, choose “Defined by Gradle Enterprise” in the “Role membership” section, and then select the default roles you wish to automatically apply. Once a user has logged in, it is possible to change their assigned roles (for example, to grant them additional roles) using the “Users” screen.

Attribute mappings

By default, users are prompted for “first name”, “last name” and “email” on first log in to Gradle Enterprise.

It is possible to manage any or all of these fields at your SAML identity provider. Select the relevant option for the field to be managed at your SAML identity provider, and enter the SAML attribute name that will contain the field.

Attribute changes made at the SAML identity provider will only take affect after either a user initiated logout, administrator force logout, or session expiry.

SAML configuration options

By default, SAML authn requests are not signed and Gradle Enterprise will not validate SAML response signatures. SAML assertions are also not required to be encrypted.

Any or all of these options can be enabled. Once enabled and saved, Gradle Enterprise’s service provider config can be downloaded to configure your SAML identity provider with the required certificates for authn request signature validation and SAML assertion encryption.

Logout

Log out from Gradle Enterprise will not log users out of the SAML identity provider.

LDAP

Gradle Enterprise supports LDAP and LDAPS.

If using an LDAPS server with an untrusted certificate, you must configure Gradle Enterprise to trust it.
  1. Navigate to the identity provider page at https://«hostname»/admin/providers.

    access control select ldap provider 2019.2
  2. Choose “LDAP” from the provider type list, and click Add.

  3. Complete the form with the details for your LDAP provider.

    access control ldap provider 2019.4
  4. If authentication is required for your LDAP provider, choose the “Require authentication” option and enter the “bind DN” and “bind credentials”.

  5. Click Save.

Roles

By default, users' roles are defined by your LDAP server. Enter the parent DN of the LDAP groups, the LDAP attribute that contains the role name, and the role object class, and Gradle Enterprise will link roles for users when they log in.

For most LDAP providers it is common for the role object class to be “groupOfNames”, however for Active Directory this is usually “group”.

With standard role mapping, the roles assigned at your LDAP identity provider must exactly match the following:

Role Description

ge-scans-viewing

Allows viewing of build scans and associated functions (when anonymous build scan viewing is disabled)

ge-scans-publishing

Allows publishing of build scans (when anonymous build scan publishing is disabled)

ge-data-export

Allows use of the Export API

ge-cache-administration

Allows administration of build cache functionality

ge-administration

Allows general administration of Gradle Enterprise (e.g. access control)

ge-distributed-testing

Allows distributing test execution via Gradle Enterprise

You can also specify custom LDAP role names when configuring your provider (note that that above role names are reserved and cannot be entered as custom names). It is possible to only enter custom names for some roles and leave others to be the default, or to use the same custom name for more than one role and thus define aggregated roles.

Role changes made at the LDAP identity provider will only take affect after either a user initiated logout, administrator force logout, or session expiry.

It is also possible to define role membership in Gradle Enterprise, and to specify default roles that a user will receive when they first log in.

To do this, choose “Defined by Gradle Enterprise” in the “Role membership” section, and then select the default roles you wish to automatically apply. Once a user has logged in, it is possible to change their assigned roles (for example, to grant them additional roles) using the “Users” screen.

Attribute mappings

There are five required fields in Gradle Enterprise: “username”, ”first name”, “last name”, “email“, and “UUID”. These fields are required to be mapped to fields in your LDAP identity provider.

Commonly, the “UUID” attribute is “entryUUID”, however for LDAP providers where this is missing, another sensible unique persistent ID should be used. For Active Directory, this is usually called “objectGUID”.

Manage users

User accounts can only be managed by Gradle Enterprise administrators.

The list of current users can be seen by navigating to the user list at https://«hostname»/admin/users.

Click on a row to edit a user and:

  • Amend user attributes e.g. “first name”, “last name” and “email” (unless managed externally at an identity provider).

  • Amend user roles (unless managed externally at an identity provider).

  • Reset password (local users only). The password will be temporary and the user will be asked for a new password when they next log in to Gradle Enterprise.

  • Force session log out.

  • Delete the user from Gradle Enterprise. SAML or LDAP users will also need to be deleted at the source in order to prevent access.

  • Revoke all access keys to prevent the user from publishing build scans.

  • Revoke an individual access key.

    access control edit user 2019.4

Login timeouts

There are currently three timeouts you can configure for access control in Gradle Enterprise. These timeouts can be configured by navigating to the settings page at https://«hostname»/admin/settings.

access control settings 2019.4

Name

Default

Description

Access token timeout

10 minutes

The maximum time before an access token is expired. This value is recommended to be short relative to the session timeouts.

User permission changes will automatically be applied after an access token expires. They will be immediately applied if a user logs out and logs in again.

After a force logout of a user, they will still have access to Gradle Enterprise until the access token is expired.

Session idle timeout

4 days (5760 minutes)

The time a login session is allowed to be idle before it expires.

Users will be required to log in again after the login session and access token have expired.

Session max lifetime

30 days (43200 minutes)

The maximum time before a login session is expired.

Users will be required to log in again after the login session and access token have expired.

Build scans

A build scan is a shareable record of a build that provides insights into what happened and why.

For information on how to create build scans, please consult the links below.

Compatibility between versions of Gradle Enterprise and the Gradle Build Scan plugin or the Gradle Enterprise Maven extension can be found here.

Build cache

Build caching dramatically decreases build times for both local development and continuous integration builds. Build caches store outputs from Gradle tasks and Maven goal executions and serve them to later builds to reuse, instead of the outputs being built again.

Gradle Enterprise provides a built-in build cache node as part of each installation, and allows optionally connecting one or more remote nodes to use as discrete caches or replicas for reducing network latency.

For information on how to use the Gradle Enterprise build cache, please consult the links below.

Build cache administration is available at /cache-admin of your Gradle Enterprise installation.

Configuration

By default, the built-in cache node provided with Gradle Enterprise is enabled and has no access protection. It also defaults to a cache size of 10 GB and a maximum artifact size of 100 MB. These settings, and access controls, can be configured at any time.

Click the Nodes item in the left menu to access the node listing, then click View built-in node details.

controller built in details 2019.2

Remote nodes

Remote build cache nodes are installed separately from Gradle Enterprise. They can be used to separate cache artifacts, distribute load, or improve build performance by having a better network link between the build and the node.

By connecting remote nodes to a Gradle Enterprise instance, you are able to configure them centrally from Gradle Enterprise, and have them replicate entries from other cache nodes.

Installation and operation of remote build cache nodes is documented in the dedicated Build Cache Node User Manual.

Connecting with Gradle Enterprise

To connect a remote node to your Gradle Enterprise installation, you first need to create a record for the node with Gradle Enterprise.

Visit /cache-admin of your Gradle Enterprise installation, and select Nodes from the left menu. In the Remote nodes > Create new node section, enter the name for your node and click Create new node.

controller after new node added 2019.2

The node will now be listed in the Existing nodes section. 

Each node is assigned a key and a secret. The node needs to be configured with the key and secret.

The secret is only viewable for 5 minutes after node creation. If the node secret is lost, use the regenerate function to issue a new secret which will then be viewable for 5 minutes.
controller secret 2019.2

The node must also be configured with details of the server to connect with, including the assigned key and secret. Please consult the Gradle Enterprise Registration section of the Build Cache Node User Manual for information on how to do this.

Replication

The bandwidth and latency of the network link between a build and a build cache significantly affects build performance. Replication allows users to use a cache node that they have a better network link to, while reusing artifacts from another cache node that is further away. This is particularly effective for geographically distributed teams.

The replication settings for each node can be configured via the node’s configuration page in Gradle Enterprise. They can not be configured for remote nodes via the remote node’s user interface or configuration file.

A typical arrangement is to have continuous integration builds push to a cache node on a local network, and have other nodes used by developers in different locations, ideally on their local network, use it as their replication source.

replication network

Replication is one-way (i.e. replication sources do not copy artifacts from nodes using them as a source). Furthermore, a node that is acting as a replication source cannot itself use a replication source.

Replication is not supported with remote nodes earlier than 3.0. This setting will not be shown for such nodes.

By default, cache entries are replicated on demand. Nodes will copy a cache entry from their replication source when that particular cache entry is requested for the first time. This avoids copying entries between nodes that will never be used, but forces builds to wait for the transfer on first use.

Preemptive replication enables better build cache performance, at the expense of more network transfer between nodes. When preemptive replication is enabled, nodes will copy cache entries from their replication source as soon as they are added. The downside of this approach is that entries may be copied that are never used. If network bandwidth usage between nodes is not a concern, this is the best configuration.

Only cache entries that are added to the replication source after the node has connected are copied preemptively. Any already existing entries will be copied on demand.

Preemptive replication is only supported for nodes of version 4.0 or later. If the node or its replication source is older than this, replication will be on demand.

Health monitoring

The Health page provides an overview of the operational status of all enabled build cache nodes.

controller health 2019.2

Each node may have a status of OK, WARN or ERROR. If all nodes are reported as OK, you can be assured that your build cache network is operating well.

WARN indicates that there is a non-critical issue, or that there is a problem that is expected to resolve itself soon. If the issue does not resolve itself, or for immediately critical issues, the ERROR status is used.

A monitoring tool friendly version of this page is available via the Monitoring page link towards the bottom of the page. This endpoint returns the statuses in plain text. If there are any ERROR statuses, the HTTP response status code for this page will be 503. Otherwise, it will be 200.

Test Distribution

Gradle Enterprise Test Distribution takes your existing test suites and distributes them across remote agents to execute them faster.

Test Distribution is available in Gradle Enterprise as a preview of the testing add-on package. Depending on your usage license, this functionality may not be available to your installation when it is no longer in feature preview. If you have questions regarding this matter, please contact Gradle Enterprise support.

Connecting builds

Test Distribution is currently only available for Gradle builds. Please consult the Gradle Enterprise Test Distribution Gradle Plugin User Manual for information on build configuration.

Gradle Enterprise users must be granted the “Test distribution” access control role to be able to use Test Distribution.

Connecting agents

Utilizing Test Distribution requires connecting additional compute resources, called agents, to Gradle Enterprise. The Test Distribution agent is available as a Docker image or standalone fat JAR and is easy to deploy and operate via Kubernetes or any modern compute platform. Please consult the Gradle Enterprise Test Distribution Agent User Manual for more on deploying and operating agents.

Registration key secrets – that agents use to connect to the Gradle Enterprise server – can be generated in the Gradle Enterprise admin section, under “Test distribution” → “Agents”. This page also shows the currently connected agents along with their declared capabilities and current status.

testdistribution agents 2020.2

Registration keys are not unique per agent. Multiple can be created to facilitate a rolling update if required.

Revoking an access key prevents it from being used for future registrations, and will cause any agents that registered with the key to be disconnected within one hour.

Viewing usage

Usage information is available via the “Jobs” and “Usage” tabs of the “Test distribution” page in the Gradle Enterprise admin section.

Current jobs

The “Jobs” tab provides an overview of the currently active jobs, where each job represents a running test task in a Gradle build.

testdistribution jobs 2020.2

The first part of the label indicates the root project name of the build, while the second part identifies the particular task.

The count of assigned agents shows how many agents are currently assigned to the job. More agents may be assigned as they become available.

The count of compatible agents shows how many currently connected agents have capabilities that satisfy the requirements of the job.

Historical usage

The “Usage” tab provides a historical overview of workload in terms of number of active jobs and agent utilization, for the last 24 hours or 7 days.

testdistribution usage 2020.2

By default, all jobs and agents are shown. Adding requirement/capability criteria shows only the jobs with at least all of the requirements, and only the agents with at least all of the capabilities.

Uninstalling

To uninstall Gradle Enterprise you first need stop the application. Navigate to the dashboard at https://«hostname»:8800, and click “Stop Now”.

Then follow the steps to uninstall Replicated, which can be found here.

You can then remove the replicated user that was created on install, by running the command:

sudo userdel -r replicated

This will remove the user, along with their home directory.

Appendix A: Upgrade notes

Temporarily degraded performance due to data reindexing

Upon upgrading, a data reindexing process will be initiated in the background with Gradle Enterprise being usable for its duration. CPU usage will be increased and performance may be slightly degraded. For large installations storing many build scans, the reindexing process may take several hours. During this time, some builds may be omitted on the scan list and all dashboards. However, incoming and recent builds are prioritized for indexing, they will be available for analysis much sooner.

New persistent storage for Test Distribution file cache

This release introduces a file cache for the Test Distribution feature inside Gradle Enterprise. If you are using a Kubernetes based installation, a new persistent volume claim of 10 GB will be created during the upgrade. If you are using a Standard installation, we recommend increasing the storage capacity of the installation directory by 10 GB.

Upgrading from versions prior to 2019.1

Upgrading directly from versions prior to 2019.1 is no longer supported. If you are using such a version and wish to upgrade, please submit a support ticket at support.gradle.com. For additional information, please consult the Gradle Enterprise version compatibility manual.

New Replicated admin console version

This release requires a new Replicated admin console version. If you have an airgapped installation, please follow steps 4-6 in the Installation section to install the new version. For non airgapped installations, there are no extra steps to perform.