Leveraging Docker Containers to Manage Sauce Connect Tunnels

In this article we will leverage Docker containers to create Sauce Connect tunnels, both Regular and High Availability versions. As a sales engineer I often need to create multiple Sauce Connect tunnels in many Sauce Labs environments—Sauce Headless, Desktop Web, Real Device Cloud—in our U.S. or European data centers. Now I want to share these techniques with our customers. This is on the Sauce roadmap as a potential project for 2020, but I thought it was too great an idea not to share with you first. After showing it to some customers, I have been asked to make this blog post, and I was happy to do it!

This will be useful if you’re an existing customer, managing your Sauce Connect tunnels manually, and you want to know how to automate and scale this solution with Docker. If you’re looking to become a Sauce Labs customer, this will give you a good idea of how to Dockerize one of the most important components of your test infrastructure.

What is Sauce Connect?

Here is documentation about what Sauce Connect does and how it works.

NOTE: At the time of this writing, the methodology described below is not supported by our product team. Use at your own risk, and modify as needed. If you are good at shell scripting and have some background in Docker this should be easy. The shell script took me 30 minutes to create, and all I started with was a few Docker tutorials on YouTube. In all, it took me a few hours to get this working, and I had a lot of fun along the way!

Why Docker?

If you’re not sure where Docker fits, consider these use cases:

1. If you’re creating automation (or manual testing) for multiple applications that reside in different environments, say for example: Desktop Web and Headless. They need to create two different Sauce Connect tunnels in both environments. Keep in mind this is flexible so you could create a Sauce Connect tunnel in all the sauce environments using this approach as well.

2. If you’re creating multiple High Availability Sauce Connect tunnels on the same system, without having to manage or use different ports.

3. If you no longer want to manage Sauce Connect versions

If any of these apply to you, or are even in the neighborhood of your situation, keep reading.

Getting Started

Before we continue, there are a few prerequisites:

• Download and install Docker Desktop locally to your system or the system that will run the docker containers
• Create account by going to https://www.docker.com/
• Sign into your docker account. You will need to do this to execute docker run or docker pull

Reminder, PLEASE READ THIS BEFORE CONTINUING ANY FURTHER! If you are going to test a local web application and you intend on using ‘localhost’, it will not work. There are a number of reasons as to why this happens, but it’s beyond the scope of this article. Instead of using ‘localhost’, use the ip address of the local system (where the web app resides) or configure the app to listen on all ports.

From the command prompt, run the following command:

$ docker login

Enter your docker hub username and password

Setup

NOTE: The command line arguments used assume you are running Docker on a Mac or Linux system. If you are using Windows, the commands may vary slightly. The configuration consists of a Docker file and a shell script. The Docker file does a few things - it sets the Linux distribution version, sets the version of Sauce Connect, downloads the version of Sauce Connect, then calls the shell script (as new versions of Sauce Connect are released, this will need to be updated manually and the Docker image rebuilt).

ARG SC_VERSION=4.5.4 (example)

NOTE: There is a way to dynamically download the latest version without hard coding the version (which was easy to do in the shell script). I had an issue getting this to work in the Docker file because it requires the installation of the package xidel, however I am sure there is a way to accomplish this with more time :) . This snippet will download the Sauce Connect version by visiting the Sauce Connect proxy URL (you don't have to be logged into the platform). This is for a Linux/MacOS setup:

 echo "use this link and download the latest version now."
    versions=$(xidel --extract "//a/@href"
 https://wiki.saucelabs.com/display/DOCS/Sauce+Connect+Proxy | grep
    "osx.zip" | awk -F"[- -]" '{print $2}')
    latestversion=$(echo $versions | sort -n | awk '{print $1}')
    downloadversionURL=$(xidel --extract "//a/@href"
 https://wiki.saucelabs.com/display/DOCS/Sauce+Connect+Proxy | grep
 "osx.zip" | grep $latestversion)
    wget $downloadversionURL
    downloadedfile=$(ls | grep *.zip)
    tar -xvf $downloadedfile
    rm -rf $downloadedfile

This will download the most recent Sauce Connect version and copy it to /usr/local/sauce-connect It also calls the shell script called 'createSCTunnels.sh' (the shell script takes several command line arguments):

-sauceUser
-sauceAccessKey 
-SauceEnvironment Web|EU|US|HEADLESS
-tunnelidentifier
Syntax:
docker run -it --rm  iflanagan/sauceconnectha:first_version
<SAUCE_USERNAME> <SAUCE_ACCESS_KEY> <SauceEnvironment Web|EU|US|HEADLESS
<TunnelIdenifier> 

Example: Creates a sauce connect tunnel for desktop web and the tunnel identifier is ‘WebtunnelId’. (NOTE use spaces between all the arguments and the sauce environment is case sensitive so use ‘Web’, ‘EU’, ‘US’, ‘HEADLESS’)

docker run -it --rm  iflanagan/sauceconnectha:first_version iflanagan 11111111-1111-1111-1111-111111111111 Web WebtunnelId 
Where 1111111-1111-1111-1111-111111111111 would be your actual sauce 
access key.

Also the script looks for a valid version of Sauce Connect here /usr/local/sauce-connect.

NOTE: Also this implementation doesn’t account for a corporate proxy, but that can be easily added to the script 'createSCTunnels.sh'. Also the 'sauce environment' argument is case sensitive to if you want to create a tunnel for example in the headless environment you need to specify 'HEADLESS'.

Putting it all together:

Docker Projects:

https://hub.docker.com/iflanagan/sauceconnectha (Sauce Connect HA mode)

https://hub.docker.com/iflanagan/sctunnels (Sauce Connect regular -not HA mode)

GitHub Projects:

https://github.com/iflanagan/docker-SCHA.git https://github.com/iflanagan/docker-sauce-connect.git

You can pull down the image and build it locally below are the commands:

mkdir <directory>
cd <directory>
docker pull iflanagan/sctunnels (or iflanagan/sauceconnectha)

docker build -t <imagename> .

docker run -it --rm --restart <imagename> <sauce_username
<sauce_access_key> <Web|HEADLESS|US|EU> <TunnelIdentifierName>

Another option (preferred way which is easier and requires less overhead). Is by running directly from Docker Hub.

To create a High Availability Sauce Connect tunnel (although you can always create more than two SC tunnels—this is just an example), open a terminal window and run the following command: (NOTE: Be sure to use the same tunnel Identifier!).

docker run -it --rm --restart iflanagan/sauceconnectha:first_version
<sauce_username> <sauce_access_key> <Web|HEADLESS|US|EU>
<TunnelIdentifierName>

If you don’t want to pass the sauce_username and access key you can always export them as environment variables. On Linux or Mac edit the ~/.bash_profile and add the following line

export SAUCE_USERNAME=<sauce_username>
export SAUCE_ACCESS_KEY=<sauce_access_key

source ~/.bash_profile

Now you can execute the command this way:

docker run -it --rm --restart iflanagan/sauceconnectha:first_version
$SAUCE_USERNAME $SAUCE_ACCESS_KEY <Web|HEADLESS|US|EU
<TunnelIdentifierName>

Example: creates a tunnel for desktop web

docker run -it --rm --restart iflanagan/sauceconnectha:first_version
$SAUCE_USERNAME $SAUCE_ACCESS_KEY Web WebTunnelId

Open another terminal window and run the following command:

docker run -it --rm --restart iflanagan/sauceconnectha:first_version
$SAUCE_USERNAME $SAUCE_ACCESS_KEY Web WebTunnelId

In this example, I run two different High Availability Sauce Connect Tunnels on my workstation. I could have created many more, or I could have created various flavors of Sauce Connect Tunnels, pointing to different environments like Headless or our Real Device Cloud. Now, log in to the SauceLabs UI and click on “Tunnels”. You should see two tunnels, and it should indicate that they are shared, which means they have the same tunnel identifier.

Add the Tunnel Identifier to your script (below is a java example) in desired capabilities and then execute the script.

NOTE: The code example below is a Java example but you can use any language and add your tunnel identifier.

capabilities.setCapability("tunnelIdentifier", "WebTunnelId");

Now go to the dashboard and click on 'Automated Tests'. If you hover the mouse over each automated test in general will use different tunnel IDs, see below.

To stop the tunnel, follow these steps from the command-line where the container is running (this will also stop the container):

• Hold down control-C
• Wait a few seconds
• Hold down control-C again

The -it flag in the Docker command puts the container image in interactive mode, giving you access to the linux shell. This makes stopping the tunnel easy, as though it were running from your computer.

Additional Considerations

Sauce Connect requires a certain amount of CPU and memory to operate optimally. Shown below are a list of those requirements:

1 2 3 4 6

Click on Docker Desktop and then click on Preferences

You can determine how much CPU/memory each container is allocated and adjust as needed.

The final step would be to create a Kubernetes cluster to handle this for you, removing the need to worry about a tunnel terminating unexpectedly. We know of one Sauce customer who has done this, and it’s working well.

Was this helpful? Useful? Hopefully this process will demonstrate the value of using Docker to quickly and easily spin up Sauce Connect tunnels. Let us know how well it worked out!