Varnish Orca
← Tutorials

Configure your Go client to use Varnish Orca

To accelerate, control and secure access to your Go module dependencies with Varnish Orca, you need to configure your Go client and override the GOPROXY environment variable.

This tutorial describes a couple of different ways to set the GOPROXY environment variable and point it to the virtual registry endpoint of a Varnish Orca setup.

Prerequisites

Before following the instructions in this tutorial, there are a couple of prerequisites:

Here’s an example configuration for Orca that creates a virtual registry configuration named go that proxies Go module requests to https://proxy.golang.org:

virtual_registry:
  registries:
  - name: go
    remotes:
    - url: https://proxy.golang.org

This configuration allows the go virtual registry entry to be matched through the hypothetical hostname https://go.example.com and cache requested modules.

Default GOPROXY value

The go env command returns the environment variables that your Go runtime uses. Run go env GOPROXY to get the current GOPROXY value, which will be:

GOPROXY='https://proxy.golang.org,direct'

This means https://proxy.golang.org is the proxy that Go module dependencies will be fetched from. If for some reason that proxy is unavailable or the module cannot be found, direct is the alternative and implies getting dependencies directly from the source.

Imagine using the github.com/gorilla/mux Go module in your code:

  • If https://proxy.golang.org is available, the github.com/gorilla/mux module is fetched from that proxy.
  • If the proxy is not available or the dependency is not found, the direct fallback setting will get the module directly from the source at https://github.com/gorilla/mux.

How Go module dependency downloads are initiated

Prior to compiling your Go program and its dependencies with go build, the source code for these dependencies needs to be downloaded.

The go mod tidy command is typically used to initiate these downloads. go mod tidy does more than just downloading dependencies, it synchronizes them: removing unused dependencies, adding missing ones, and upgrading dependencies to the right version.

The alternative is the go get command. This only downloads dependencies, without cleaning up any unused modules. This is typically used to upgrade existing dependencies.

go get . fetches the dependencies that are defined in the go.mod file, go get github.com/gorilla/mux just downloads the one dependency.

All these commands rely on GOPROXY to know where to download the dependencies from.

Option 1: use go env -w GOPROXY to override the default proxy setting

While the go env command prints Go environment information, the -w flag can be used to override the default value of GOPROXY and persist it across sessions.

Assuming https://go.example.com is the hypothetical endpoint of the Orca virtual registry for Go, you can run the following command to configure Varnish Orca as the Go proxy:

go env -w GOPROXY=https://go.example.com

If you want to revert the GOPROXY built-in value to the factory setting, just run the following command:

go env -u GOPROXY

Option 2: set the GOPROXY environment variable in your shell

You can also set GOPROXY as an actual environment variable in your shell. This is typically done through the export command as illustrated below:

export GOPROXY=https://go.example.com

Again, this is assumes that https://go.example.com is the hypothetical endpoint of the Orca virtual registry for Go.

To persist the GOPROXY value across multiple sessions, you need to store the export in your shell configuration.

If you use the Bash shell, you can run the following commands to store the environment variable in the Bash profile of the user you’re logged in with:

echo 'export GOPROXY=https://go.example.com' >> ~/.bashrc
source ~/.bashrc

If you use ZSH are your shell, you can run the following command:

echo 'export GOPROXY=https://go.example.com' >> ~/.zshrc
source ~/.zshrc

If you’re using a CI/CD tool or another automation suite to pull in your Go dependencies, it will probably have a way to set and use environment variables during its runs.

Setting the GOPROXY environment variable will override any value that was set through go env -W GOPROXY=<proxy endpoint>

Option 3: override the GOPROXY environment variable at install time

The third way to override the GOPROXY environment variable, is by setting it every time you install or synchronize dependencies.

Here’s an example where we set https://go.example.com when running go mod tidy:

GOPROXY=https://go.example.com go mod tidy

The same can be done when running go get:

GOPROXY=https://go.example.com go get .
GOPROXY=https://go.example.com go get github.com/gorilla/mux

Configure multiple proxy endpoints

The GOPROXY environment variable can have multiple values, as mentioned earlier. The default value is GOPROXY='https://proxy.golang.org,direct'.

You can configure your Varnish Orca virtual registry with multiple endpoints:

virtual_registry:
  registries:
  - name: go
    remotes:
    - url: https://proxy.golang.org
  - name: goprivate
    remotes:
    - url: https://some.other.registry.example.com

The go virtual registry entry proxies Go module requests to the public https://proxy.golang.org proxy, while the goprivate entry routes requests to a private registry.

The following GOPROXY value first tries to fetch dependencies from the public go endpoint, and when the package is not found or the primary endpoint is unavailable, it tries the goprivate endpoint:

GOPROXY='https://go.example.com,https://goprivate.example.com'

This means that the fallback value is used whenever the primary proxy doesn’t return a 200 status code. If you only want to use the fallback in case the dependency is not found on the primary, configure GOPROXY as follows:

GOPROXY='https://go.example.com|https://goprivate.example.com'

Only if https://go.example.com returns a 404 or 410 status code, https://goprivate.example.com will be used.