This tutorial shows how to install and run Gradle Enterprise on Amazon EC2.

You can complete this tutorial in:

  • 10 minutes (read the tutorial)

  • 30 minutes (read the tutorial and perform the installation)

Gradle Enterprise can be installed on most modern Linux servers. The majority of this tutorial is a quick start guide to creating and minimally configuring an EC2 instance for a Gradle Enterprise installation. If you already have EC2 expertise and are able to provision an instance, you may wish to follow the general Gradle Enterprise installation instructions for generic Linux servers.


1. AWS Account

You can create a free account if you do not already have one.

2. Gradle Enterprise license

You can request a Gradle Enterprise trial here. If you have purchased Gradle Enterprise, you will already have a license file.

3. Hostname (optional)

Amazon EC2 machines are provisioned with generated host names such as If you want to access Gradle Enterprise by a host name of your choosing (e.g., you will need the ability to create the necessary DNS record to route this name to the Amazon EC2 address.

You are able to easily update this later. You can start with the name generated by AWS and later reconfigure to use a custom name if desired.

4. SSL Certificate (optional)

Your Gradle Enterprise instance will be accessible via the public Internet. By default, all communication with Gradle Enterprise is encrypted over HTTPS, either via self-signed certificate or a certificate issued to you by a trusted certificate authority. Once Gradle Enterprise is installed, you may switch off HTTPS via the Gradle Enterprise Admin Console if you prefer.

Using a self-signed certificate will require some extra configuration for the users of your Gradle Enterprise installation, but will also result in traffic being encrypted.

Creating an EC2 Server

In this section you will create an EC2 instance to run Gradle Enterprise.

1. Sign in to the AWS Console

Sign in to Amazon AWS via the console page. Then, select “Services” from the top menu bar, and choose “EC2” in the “Compute” section of the dropdown that appears. Then, choose where you want your instance to run using the drop down on the top-right of the console screen.

You should generally pick the region closest to you geographically to ensure the best performance.

2. Generate a key-pair for SSH access

If you do not already have a key-pair for accessing AWS resources, you will need to create one. If you already have a key-pair that you wish to use, you can skip this step.

In the left hand menu on the EC2 page, click “Key Pairs” under the “Network and Security” heading. Click “Create Key Pair” and give it the name “Gradle Enterprise Keypair”. The keypair will appear in the list on screen, and your browser will download a file GradleEnterpriseKeypair.pem.

SSH requires that only you have permissions to read PEM files, so you need to change the file permissions. Under Unix/Linux/OS X, this can be done by using the chmod command:

chmod 400 /path/to/GradleEnterpriseKeypair.pem

3. Choose a virtual server image

Now in the left hand menu, you will see a link “Instances” under the “Instances” heading. Click this, and it will take you to a list of your current instances running in the AWS region you have selected. Create a new instance, by clicking the big blue “Launch Instance” button on this page.

ec2 instances empty

You will be presented with a list of Amazon Machine Images to choose from.

If you do not have a preference, choose the most recent “Amazon Linux AMI” version that is supported by Gradle Enterprise. At the time of writing this is “2017.09.1”.

The list of supported operation systems supported by Gradle Enterprise can be found here.

4. Choose an instance type

At the time of writing, the simplest instance type that meets Gradle Enterprise’s minimum requirements is “t2.xlarge”. This instance type will be adequate for all but very heavily used installations.

Select your chosen instance type, and click “Review and Launch”.

5. Add storage

Scroll down the review page until you see the “Storage” section, and click “Edit Storage”.


The suggested minimum storage space for Gradle Enterprise is 250 GiB.

For trial installations, the “General Purpose SSD” option is suitable. Production class installations should consider using “Provisioned IOPS SSD” for better performance.

Click “Review and Launch” to go back to the review screen.

6. Assign a security group

The EC2 instance needs to be assigned to a security group that exposes the networking ports required to access Gradle Enterprise.

Scroll down the review page until you see the “Security Groups” section, and click “Edit security groups”. Choose “Create a new security group”, give the group a sensible name and description, and then add the following rules (as shown in the screenshot)

  • Port 22 for SSH

  • Port 80 for HTTP

  • Port 443 for HTTPS

  • Port 8800 for the admin console

Select “Anywhere” in the “Source” column, to allow access from any address (, ::/0).

security groups

Click “Review and Launch” to return to the review screen.

7. Launch the machine

Click “Launch” on the review screen.

You will be asked to select a key-pair to allow you to SSH in to the instance.

keypair chooser

Select the key-pair you created earlier (or an existing one you wish to use), and click the checkbox.

Click “Launch Instance” to start your server.

8. Configure the hostname

If you intend to use a custom hostname to access your Gradle Enterprise instance, you now need to add the appropriate DNS records.

Add an A record for your hostname that points to the public IP address of your EC2 instance. You can find this IP address in the “IPv4 Public IP” field of the details panel when your instance is selected in the Instances table. A

Alternatively, you can use the hostname generated by AWS. You can find the generated hostname in the “Public DNS (IPv4)” field of the details panel when your instance is selected in the Instances table (there’s even a handy “copy” icon next to it to copy the hostname to the clipboard).

Whichever you choose, from now on we will refer to this as «hostname».

Installing Gradle Enterprise

In this section you will install Gradle Enterprise on your newly created EC2 instance.

1. Install the admin console

SSH into your instance with the following command:

ssh -i /path/to/pem/GradleEnterpriseKeypair.pem ec2-user@«hostname»
The username ec2-user differs depending on which virtual server image you chose. For “Amazon Linux AMI” images it is ec2-user, but may be different if you chose a different AMI. You can find out how to access your chosen AMI by selecting the instance and clicking the “Connect” menu item under the “Actions” button at the top of the instances table.

Once you’re on the machine, start the installation by issuing the command:

curl -sSL | sudo bash

The installer will ask if you require a proxy to access the internet. Choose “No” to continue.

2. Configure your hostname

Once that has finished installing, open a web browser and navigate to https://«hostname»:8800 to access the admin console (you will need to accept the warning in your browser due to there not being a valid SSL certificate).

install ssl 2017.7

Enter «hostname» into the hostname field.

If you have a trusted SSL certificate for your hostname, you can upload it here. Otherwise, click “Use Self-Signed Cert”.

3. Upload your license

Select “Choose license” and specify your license file.

install license 2017.7

4. Secure the admin console

Choose a method for securing the admin console “Continue”.

install password 2017.7

5. Finish installation

The system will then perform some pre-flight checks, after which you can select “Continue”, and then select “Dashboard” from the navigation menu at the top of the page.

The latest version of Gradle Enterprise will begin downloading and will start automatically.

update started 2017.7

Once the dashboard shows “Started” in the left-hand panel, you can access Gradle Enterprise by either clicking “Open”, or by navigating to https://«hostname».

Using Gradle Enterprise

Please consult the Getting Started with Gradle Enterprise guide for how to configure your Gradle builds to leverage your new Gradle Enterprise installation.

Stopping your instance

When you wish to shut down your instance, you simply need to browse to the “Instances” table, select your instance, and using the “Actions” drop-down click “Terminate” under the “Instance State” submenu. This will ask you if you are sure, and clicking “Yes, terminate” will shut down the machine and delete the storage volume.

Further reading