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 and operation

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 / 16.04 / 18.04

  • Red Hat Enterprise Linux 6.5+

  • CentOS 6+

  • 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 - 18.09.2-ce (with 18.09.2-ce being the recommended version), 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 managing disk usage 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

250 MB

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

  • 8 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

8080-8083

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.

  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 from https://s3.amazonaws.com/replicated-airgap-work/replicated.tar.gz.

  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. 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
  2. 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.

  3. 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.

Managing disk usage

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.

email settings 2019.2

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.

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.

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.2

Required fields

Users have four required fields:

  • Username

  • First name

  • Last name

  • Email

Both username and email must be unique in the system.

Roles

There are four roles in Gradle Enterprise, each controlling access to a particular area of the system.

Role

Description

GE Admin

This role allows users to use the Gradle Enterprise administration pages.

Scans

This role allows users to view individual build scans, build scan list, build scan comparison, and performance dashboard.

Cache Admin

This role allows users to use the build cache administration pages.

Export API

This role allows users to use the Export API.

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.1
  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-administration

This role allows users to use the Gradle Enterprise administration pages.

ge-scans-viewing

This role allows users to view individual build scans, build scan list, build scan comparison, and performance dashboard.

ge-cache-administration

This role allows users to use the build cache administration pages.

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.1
  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-administration

This role allows users to use the Gradle Enterprise administration pages.

ge-scans-viewing

This role allows users to view individual build scans, build scan list, build scan comparison, and performance dashboard.

ge-cache-administration

This role allows users to use the build cache administration pages.

ge-data-export

This role allows users to use the Export API.

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.

    access control edit user 2019.2

Settings

Access control 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 2018.5

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.

Allowing open access to build scans

In some environments, it may be desirable to allow access to build scans and associated functions for everyone. This can be achieved by checking “Allow anyone to access build scans” in the installation settings console.

access control anon scan access 2019.3

Enabling this option allows anyone to access all build scan information without being authenticated. It does not affect access control to other functions such as build cache administration or application administration.

Build scans

Usage

Creating build scans

For information on how to create Gradle build scans, please consult the Gradle Build Scan Plugin User Manual.

For information on how to create Maven build scans, please consult the Gradle Enterprise Maven Extension User Manual.

Viewing build scans

When running a build that publishes build scans, the URL to the build scan for that build is output at the end of the build which looks like this…

Publishing build scan...
https://«hostname»/s/«scan-id»

To view all of the collected build scans, open the Gradle Enterprise application in your browser. This will redirect you to the /scans page where you can search for build scans. Click on a search result to view the build scan.

usage scan list 2019.2

Integrating your CI tool

The Gradle plugin for Jenkins prominently displays links to the build scan for any Gradle builds that produce build scans. This makes viewing the build scan of CI builds much easier.

jenkins

A TeamCity build scan plugin is also available that provides a prominent link to the build scan for executed builds.

teamcity

Gradle plugin / Maven extension version compatibility

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.

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

Gradle usage

In order to use a build cache, the address of the build cache needs to be configured in your Gradle builds.

The built-in cache node is available via https://«gradle-enterprise-hostname»/cache/ (or with https if configured):

settings.gradle
buildCache {
    remote(HttpBuildCache) {
        url = 'https://gradle-enterprise.mycompany.com/cache/'
    }
}
settings.gradle.kts
buildCache {
    remote(HttpBuildCache::class) {
        url = uri("https://gradle-enterprise.mycompany.com/cache/")
    }
}

If your Gradle Enterprise installation is using HTTPS with a self-signed or untrusted certificate, connection to the build cache will fail. As of Gradle 4.2, you can allow connections to untrusted servers by adding allowUntrustedServer = true to the configuration:

settings.gradle
buildCache {
    remote(HttpBuildCache) {
        url = 'https://gradle-enterprise.mycompany.com/cache/'
        allowUntrustedServer = true
    }
}
settings.gradle.kts
buildCache {
    remote(HttpBuildCache::class) {
        url = uri("https://gradle-enterprise.mycompany.com/cache/")
        isAllowUntrustedServer = true
    }
}

Earlier versions of Gradle do not support untrusted HTTPS connections to a build cache.

Remote nodes are available via http://«remote-cache-node-hostname»/cache/ (or with https if configured):

settings.gradle
buildCache {
    remote(HttpBuildCache) {
        url = 'https://gradle-cache-node-1.mycompany.com/cache/'
    }
}
settings.gradle.kts
buildCache {
    remote(HttpBuildCache::class) {
        url = uri("https://gradle-cache-node-1.mycompany.com/cache/")
    }
}

For more information about using a build cache from Gradle, please consult the Gradle user manual.

Using multiple caches

When leveraging replication, the build configuration should allow using the best available cache node. One approach is to set a default cache location, while allowing users to override it for their environment.

This can be done by leveraging system properties:

settings.gradle
buildCache {
    remote(HttpBuildCache) {
        url = System.getProperty('buildCacheUrl', 'https://cache1/cache/')
    }
}
settings.gradle.kts
buildCache {
    remote(HttpBuildCache::class) {
        url = uri(System.getProperty("buildCacheUrl", "https://cache1/cache/"))
    }
}

Users can then specify their best build cache node by adding the following to their ~/.gradle/gradle.properties file:

systemProp.buildCacheUrl=https://cache2/cache/

More automatic schemes are also possible, depending on your environment. For example, if you are able to programmatically determine where the build is running, it may be practical to choose the best cache node automatically within the cache configuration logic.

Apache Maven™ usage

In order to use a build cache, the address of the build cache needs to be configured in the configuration for your Maven builds, unless you are connecting to the built-in cache node of Gradle Enterprise.

The built-in cache node is configured by providing the URL of your Gradle Enterprise installation:

gradle-enterprise.xml
<gradleEnterprise>
  <server>
    <url>https://«gradle-enterprise-hostname»</url>
  </server>
</gradleEnterprise>

If your Gradle Enterprise installation is using HTTPS with a self-signed or untrusted certificate, connection to the build cache will fail. You can allow connections to untrusted servers by adding <allowUntrusted>true</allowUntrusted> to the configuration:

gradle-enterprise.xml
<gradleEnterprise>
  <server>
    <url>https://«gradle-enterprise-hostname»</url>
  </server>
  <buildCache>
    <remote>
      <server>
        <allowUntrusted>true</allowUntrusted>
      </server>
    </remote>
  </buildCache>
</gradleEnterprise>

Remote nodes are available via http://«remote-cache-node-hostname»/cache/ (or with https if configured):

gradle-enterprise.xml
<gradleEnterprise>
  <server>
    <url>https://«gradle-enterprise-hostname»</url>
  </server>
  <buildCache>
    <remote>
      <server>
        <url>http://«remote-cache-node-hostname»/cache/</url>
      </server>
    </remote>
  </buildCache>
</gradleEnterprise>

For more information about using a build cache from Maven, please consult the Gradle Enterprise Maven Extension User Manual.

Using multiple caches

When leveraging replication, the build configuration should allowing using the best available cache node. One approach is to allow users to override it for their environment.

This can be done by defining the remote cache address in the user’s gradle-enterprise.xml, located at <user-home>/.m2/gradle-enterprise.xml. This file has precedence over any other defined gradle-enterprise.xml configuration files.

<user-home>/.m2/gradle-enterprise.xml
<gradleEnterprise>
  <server>
    <url>https://«gradle-enterprise-hostname»</url>
  </server>
  <buildCache>
    <remote>
      <server>
        <url>https://my-cache/cache/</url>
      </server>
    </remote>
  </buildCache>
</gradleEnterprise>

Alternatively, in particular on CI, you can define a cache configuration in a shared gradle-enterprise.xml and pin the remote cache address at runtime through system properties. You can pull in the cache configuration for your CI builds by using the -Dgradle.user.config system property and pin the cache address by using the system property gradle.cache.remote.url.

$ mvn clean verify -Dgradle.user.config=gradle-enterprise-ci.xml -Dgradle.cache.remote.url=https://my-cache-1/cache/

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 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 manual for 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.

Uninstalling Gradle Enterprise

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

This release contains a database structure change that may prolong the first startup after upgrading, depending on the number of build scans stored. With modest hardware, the change is expected to take roughly one minute per 100,000 build scans to complete. If your installation currently stores many build scans, please plan for an appropriate downtime window for the upgrade.