Gradle Proxy Configuration

1. Overview

A proxy server acts as an intermediary between a client and a server. It helps evaluate requests from a client before forwarding them to target servers based on certain criteria. This gives a system flexibility to determine which network to connect to or not.

In this tutorial, we’ll learn how to configure Gradle to work behind a proxy server. In our example, our proxy is running on localhost with a proxy port 3128 for both HTTP and HTTPS connections.

2. Proxy Configuration

We can configure Gradle to work behind a proxy server with or without authentication credentials.

2.1. Basic Proxy Configuration

To begin with, let’s set up a basic proxy configuration that doesn’t require authentication credentials. First, let’s create a file named gradle.properties in the root directory of a Gradle project.

Next, let’s define the system properties for the proxy server in the gradle.properties file:

systemProp.http.proxyHost=localhost
systemProp.http.proxyPort=3128
systemProp.https.proxyHost=localhost
systemProp.https.proxyPort=3128

Here, we define system properties that Gradle will use during the build process. We define system properties for both HTTP and HTTPS connections. In this case, they both have the same hostname and proxy port.

Also, we can specify a host in the gradle.properties file to bypass the proxy server:

systemProp.http.nonProxyHosts=*.nonproxyrepos.com
systemProp.https.nonProxyHosts=*.nonproxyrepos.com

In the configuration above, the subdomain nonproxyrepos.com will bypass the proxy server and request resources directly from a server.

Alternatively, we can run the ./gradlew build command with the system properties as an option via the terminal:

$ ./gradlew -Dhttp.proxyHost=localhost -Dhttp.proxyPort=3128 -Dhttps.proxyHost=localhost -Dhttps.proxyPort=3128 build

Here, we define the system properties to connect to the proxy server via the terminal.

Notably, defining the system properties via the terminal overrides the configuration of the gradle.properties file.

2.2. Adding Authentication Credentials

In a case where the proxy is secured, we can add authentication credentials to the gradle.properties file:

systemProp.http.proxyUser=Baeldung
systemProp.http.proxyPassword=admin
systemProp.https.proxyUser=Baeldung
systemProp.https.proxyPassword=admin

Here, we add authentication credentials by defining the system properties for the username and password. Also, we implement authentication credentials for both HTTP and HTTPS connections.

Alternatively, we can specify the username and password via the terminal:

$ ./gradlew -Dhttp.proxyHost=localhost -Dhttp.proxyPort=3128 -Dhttps.proxyHost=localhost -Dhttps.proxyPort=3128 -Dhttps.proxyUser=Baeldung -Dhttps.proxyPassword=admin build

Here, we include the authentication credentials in the terminal command.

3. Possible Errors

An error may occur if the hostname and the proxy port are incorrect:

> Could not get resource 'https://repo.maven.apache.org/maven2/io/micrometer/micrometer-core/1.12.0/micrometer-core-1.12.0.pom'.
> Could not GET 'https://repo.maven.apache.org/maven2/io/micrometer/micrometer-core/1.12.0/micrometer-core-1.12.0.pom'.
> localhosty: Name or service not known

Here, the build failed because we mistakenly wrote the proxy host as “localhosty” instead of “localhost”.

Also, in a case where we define the system properties in a gradle.properties file and command line, the command line definition has the highest precedence during the build:

$ ./gradlew -Dhttp.proxyHost=localhost -Dhttp.proxyPort=3120 -Dhttps.proxyHost=localhost -Dhttps.proxyPort=3120 build

Here, the proxy port value in the command line is 3120, which is wrong. The gradle.properties file proxy port value is 3128, which is correct. However, the build fails with the following error message:

> Could not get resource 'https://repo.maven.apache.org/maven2/io/micrometer/micrometer-core/1.12.0/micrometer-core-1.12.0.pom'.
> Could not GET 'https://repo.maven.apache.org/maven2/io/micrometer/micrometer-core/1.12.0/micrometer-core-1.12.0.pom'.
> Connect to localhost:3120 [localhost/127.0.0.1, localhost/0:0:0:0:0:0:0:1] failed: Connection refused

Here, the proxy server rejects the connection because the proxy port definition in the command line argument is wrong though the gradle.properties file proxy port value is right. The command line parameters definition takes precedence over gradle.properties values.

Furthermore, the proxy server will reject the connection when the authentication credentials are wrong in a secured proxy server. To avoid these errors, it’s required to check the configuration properly.

4. Conclusion

In this article, we learned how to configure Gradle to work behind a proxy by defining the required system properties in a gradle.properties file. Also, we saw how to define the system properties via the terminal. Finally, we saw a few easy-to-make errors and how to avoid them.

As always, the complete example code is available over on GitHub.