Athens Go proxy

Search the Azure Marketplace for Athens, select the SecureAnyCloud publisher, and choose Create.

Configure the NSG to allow TCP 443 from the developer workstations and build agents that will use the proxy, and TCP 22 for administration. Restrict port 443 to the networks you serve, because a module proxy rarely needs to be reachable from the whole internet.

RG="athens-prod"; LOCATION="eastus"; VM_NAME="athens1" IMAGE_URN="sac1647283583153:athens-go-proxy-ubuntu-24-04:default:latest" SSH_KEY="$(cat ~/.ssh/id_rsa.pub)" az group create --name "$RG" --location "$LOCATION"
# Accept the Marketplace terms once per subscription (required before the first CLI deploy)
az vm image terms accept --urn sac1647283583153:athens-go-proxy-ubuntu-24-04:default:latest
az vm create \
  --resource-group "$RG" --name "$VM_NAME" \
  --image "$IMAGE_URN" \
  --size Standard_B2s \
  --admin-username azureuser \
  --ssh-key-values "$SSH_KEY" \
  --public-ip-sku Standard
az vm open-port --resource-group "$RG" --name "$VM_NAME" --port 443 --priority 1001
az vm open-port --resource-group "$RG" --name "$VM_NAME" --port 22 --priority 1002

On first boot, the image resolves this VM's IP address. It generates a per-instance HTTP basic authentication username and password and a per-instance TLS certificate, and writes everything to /root/athens-credentials.txt. This completes within seconds.

SSH in as azureuser and read the credentials file:

sudo cat /root/athens-credentials.txt

The file is 0600 root:root. It records the proxy user and password, the HTTPS proxy URL, and a ready-to-paste GOPROXY example. These values are unique to this instance.

Run the commands below. Confirm that athens.service and nginx.service are both active and that athens -version reports 0.18.1. The ss output shows that nginx owns port 443 while the Athens proxy is bound to loopback only on port 3000.

systemctl is-active athens.service nginx.service /opt/athens/athens -version sudo ss -tlnp | grep -E ':443 |:3000 '

The module proxy is reachable only through nginx on port 443, and only with the per-instance HTTP basic authentication. An unauthenticated module request returns 401. A request with the per-instance credentials returns 200. Only the /healthz load balancer probe is served without credentials.

The block below reads the credentials from the instance credentials file, so it works unchanged on any instance.

PROXY_USER=$(sudo grep -E '^ATHENS_PROXY_USER=' /root/athens-credentials.txt | cut -d= -f2-)
PROXY_PASS=$(sudo grep -E '^ATHENS_PROXY_PASSWORD=' /root/athens-credentials.txt | cut -d= -f2-)
curl -sk -o /dev/null -w 'healthz (no auth) -> HTTP %{http_code}\n' https://127.0.0.1/healthz
curl -sk -o /dev/null -w 'list (no auth) -> HTTP %{http_code}\n' https://127.0.0.1/rsc.io/quote/@v/list
curl -sk -u "$PROXY_USER:$PROXY_PASS" -o /dev/null -w 'list (with auth) -> HTTP %{http_code}\n' https://127.0.0.1/rsc.io/quote/@v/list

The -k flag tells curl to accept the self-signed per-instance certificate. The authenticated request returns the list of versions Athens can serve for the module, which it assembles from its own cache and the upstream mirror.

Set GOPROXY to the authenticated HTTPS URL of this proxy and run go mod download. The module is fetched through Athens, which caches it and serves it.

The block below runs entirely on this VM against 127.0.0.1 to demonstrate the round trip. On a workstation, use this VM's address instead (see Step 8).

PROXY_USER=$(sudo grep -E '^ATHENS_PROXY_USER=' /root/athens-credentials.txt | cut -d= -f2-)
PROXY_PASS=$(sudo grep -E '^ATHENS_PROXY_PASSWORD=' /root/athens-credentials.txt | cut -d= -f2-)
export PATH=/usr/local/go/bin:$PATH export SSL_CERT_FILE=/etc/nginx/tls/athens.crt
# trust this VM's self signed certificate export GOSUMDB=off export GOPROXY="https://$PROXY_USER:$PROXY_PASS@127.0.0.1/" export GOPATH=$(mktemp -d) GOMODCACHE=$(mktemp -d) HOME=$(mktemp -d)
cd "$(mktemp -d)" go mod download -x github.com/pkg/errors@v0.9.1 echo "go mod download exit code: $?"

Every request in the trace is served with HTTP 200 through the proxy on 127.0.0.1, and go mod download exits 0. The module has now been fetched once and cached.

Athens stores every fetched module in its on-disk cache on the dedicated data disk mounted at /var/lib/athens. The cache has room to grow and is separate from the operating system disk.

Confirm the mount and inspect the cache:

df -h /var/lib/athens
sudo find /var/lib/athens/storage -maxdepth 3 -mindepth 1 -type d

The output shows the data disk mounted at /var/lib/athens. The cache lists every module Athens has fetched so far, each ready to be served to your whole team without touching the internet again.

On any developer workstation or CI agent, point the Go toolchain at this instance. Replace <vm-ip> with this instance's address (or a DNS name you point at it), and use the per-instance credentials from /root/athens-credentials.txt.

# trust this instance's certificate (copy /etc/nginx/tls/athens.crt from the VM), then:
export SSL_CERT_FILE=/path/to/athens.crt
export GOPROXY="https://<user>:<password>@<vm-ip>/"
export GOSUMDB=off go mod download go build ./...

For CI, set the same GOPROXY, GOSUMDB and certificate trust as environment variables in your pipeline. Every job then pulls modules from the shared cache instead of the public internet, which is faster and keeps your builds reproducible.

The per-instance certificate is self-signed, so clients must trust it explicitly. For production, put a DNS name and a CA-signed certificate in front of the proxy by replacing the per-instance certificate in /etc/nginx/tls. Clients then trust the transport with no extra configuration.

# replace the self signed certificate with your CA signed certificate + key, then reload nginx
sudo cp your-cert.crt /etc/nginx/tls/athens.crt
sudo cp your-cert.key /etc/nginx/tls/athens.key
sudo systemctl reload nginx
# point GOPROXY at https://<your-domain>/ with the per instance credentials

• Restrict the NSG. Allow TCP 443 only from the developer subnets and build agents that use the proxy, and TCP 22 only from your administration network. A module proxy rarely needs to be public.
• Protect the proxy password. It lives in /root/athens-credentials.txt (0600 root:root). The proxy is reachable only through nginx and only with this password. To rotate it, update /etc/nginx/athens.htpasswd with htpasswd and reload nginx.
• Use a real certificate for production. The per-instance certificate is self-signed. Put a CA-signed certificate and a DNS name in front of the proxy so clients trust the transport without extra configuration.
• Size the data disk for your module graph. The cache grows as your team pulls more modules. Monitor /var/lib/athens and enlarge the data disk when needed.
• Keep the OS patched. Unattended security upgrades remain enabled on the running VM.

Athens is open-source software distributed under the MIT License. This SecureAnyCloud image bundles the unmodified official Athens release binary and the official Go toolchain.

SecureAnyCloud provides the packaging, the systemd hardening, the nginx TLS front, the loopback-only proxy with per-instance basic auth, the per-instance credential automation, the dedicated data disk for the cache, this deployment guide, and 24/7 support with a guaranteed 24 hour response SLA.

SecureAnyCloud is not affiliated with or endorsed by the Athens project. Athens is a mark of its respective owner and is used here only to identify the software.

Deploy on Azure

Find Athens Go Module Proxy on Ubuntu 24.04 LTS on the Azure Marketplace, published by SecureAnyCloud. Deploy from the Portal or the Azure CLI as shown above.

Need help?

Email sales@secureanycloud.com for deployment help, configuration questions, or licensing enquiries.

Deploy on Azure

Launch Athens Go Module Proxy 0.18.1 on Ubuntu 24.04 LTS on Azure with 24/7 support from SecureAnyCloud.

View this image

Need Help?

Our support team is available 24/7.

sales@secureanycloud.com

Sign in to the AWS Management Console, open the EC2 service, and choose Launch instance. Under Application and OS Images, choose AWS Marketplace AMIs and search for Athens Go Module Proxy. Select the SecureAnyCloud listing, choose Select, then choose Continue on the subscription summary.

Pick an instance type of m5.large or larger. Choose your EC2 key pair under Key pair (login). Under Network settings, select your VPC and subnet, then create or select a security group that opens port 22 from your management network and port 443 from your developer and CI networks.

Leave the root volume at the default size or larger. The module cache lives on a separate data volume that is provisioned automatically.

Choose Launch instance. First-boot initialisation takes a few seconds after the instance state becomes Running and the status checks pass.

Run the following block to launch an instance from the SecureAnyCloud Athens Marketplace AMI into an existing subnet and security group.

Replace <ami-id> with the AMI ID shown on the Marketplace listing, <key-name> with your EC2 key pair name, <subnet-id> with your subnet ID, and <security-group-id> with a security group that opens port 22 and port 443.

aws ec2 run-instances \
  --image-id <ami-id> \
  --instance-type m5.large \
  --key-name <key-name> \
  --subnet-id <subnet-id> \
  --security-group-ids <security-group-id> \
  --tag-specifications 'ResourceType=instance,Tags=[{Key=Name,Value=athens-go-proxy}]'

When the instance reaches the Running state and its status checks pass, note its public IP address or DNS name from the EC2 console or with aws ec2 describe-instances.

Connect over SSH with your key pair and the login user for your operating system variant.

OS variant SSH login user

Ubuntu 24.04 ubuntu

ssh -i /path/to/your-key.pem ubuntu@<public-ip>

The unique username and password generated on first boot are in a root-only file. Read them with sudo:

sudo cat /root/athens-aws-credentials.txt

The file contains:

• ATHENS_PROXY_USER and ATHENS_PROXY_PASSWORD: the HTTP basic auth username and password for this instance
• ATHENS_PROXY_URL: the HTTPS proxy URL, https://<instance-public-ip>/
• A ready-to-paste GOPROXY example

Keep this file secret. It holds the credentials for your private module proxy.

Athens runs as a systemd service bound to 127.0.0.1:3000 only. nginx terminates TLS on port 443 as the single network-facing service.

Confirm that both services are active and that Athens is listening on loopback only:

systemctl is-active athens.service nginx.service
sudo ss -ltnp | grep -E ':3000|:443' /opt/athens/athens -version

Athens listens on 127.0.0.1:3000 and never on a public interface, while nginx owns port 443. This is what keeps the proxy from being an open module relay.

nginx fronts the entire proxy with HTTP basic authentication. An unauthenticated request is rejected, and an authenticated request serves the module protocol. An unauthenticated /healthz probe is available for load balancers.

Run the following, substituting the username and password from your credentials file:

# no credentials -> 401 Unauthorized (the proxy is never open)
curl -sk -o /dev/null -w '%{http_code}\n' https://127.0.0.1/rsc.io/quote/@v/list
# with the per instance credentials -> 200 and the list of module versions
curl -sk -u "$ATHENS_PROXY_USER:$ATHENS_PROXY_PASSWORD" https://127.0.0.1/rsc.io/quote/@v/list
# unauthenticated load-balancer liveness probe -> 200
curl -sk -o /dev/null -w '%{http_code}\n' https://127.0.0.1/healthz

On each workstation and CI agent, trust this instance's self-signed certificate and set GOPROXY to the authenticated HTTPS URL. First copy the certificate off the instance (it is at /etc/nginx/tls/athens.crt), then run:

# trust this instance's certificate (or add it to your system trust store)
export SSL_CERT_FILE=/path/to/athens.crt
# point the go toolchain at your private Athens proxy
export GOPROXY="https://<user>:<password>@<public-ip>/"
export GOSUMDB=off
# every module now flows through Athens and is cached on the instance go mod download rsc.io/quote@v1.5.2

The first time a module version is requested, Athens fetches it from the upstream Go mirror (falling back to the module's version control host), stores it in its on-disk cache on the data volume, and serves it. Every later request for that version is served straight from the cache.

Confirm that the module landed in the cache and that the cache is on the dedicated data volume:

ls -la /var/lib/athens/storage/rsc.io/quote/v1.5.2/ df -h /var/lib/athens

To roll the proxy out across a team, set the same GOPROXY and SSL_CERT_FILE on every developer machine and CI runner.

For production, replace the self-signed certificate with one signed by your own certificate authority or a public CA for your domain. Place the instance behind a load balancer if you need horizontal scale.