In this blog, we’ll learn how to run Akamai Sandbox within a Docker container to test changes before deployment. To streamline the process of setting up your developer environment, we’ll take a look at the Akamai Docker image first.

The Akamai Docker image is loaded with tools including the Akamai CLI, CLI packages, and 3rd-party tools like HTTPie, cURL, and Terraform. It’s the easiest way to get started, ease dependency management, and stay up to date with the newest CLI versions. 

When we combine the Docker image with Sandbox, we’ll have our CLI packages and other tools quickly at our fingertips for effective and streamlined testing.

Using The Akamai Sandbox 

Akamai Sandbox is a great way to quickly test that our changes are compatible with any other services we use.

Our Sandbox consists of 2 components:

• Sandbox CLI - Enables you to quickly set up Sandbox

• Sandbox Client - Connects your browser to Sandbox network and can map origins to your local machine (the client is managed by Sandbox CLI automatically)

In order to use Sandbox, we’ll need the following installed: 

• Node

• Python 

• Java

• The Akamai Docker Image

When you install the Akamai Docker image, the Sandbox CLI package is automatically included in the container. Let's take a look at what’s  inside the Sandbox Docker image:

Each folder contains the following: 

• /bin
  This contains the files that make up the Akamai CLI wrapper. 

• /cli
  This contains the Akamai Sandbox CLI files.

• /sandboxes
  This folder stores the information about the instances we create. Sandbox CLI needs to locally store some data that is used whenever we invoke Sandbox CLI to perform an operation, so we’ll need to ensure that the content stored in the /sandboxes folder is available during the whole session and when we’re working with Akamai Sandbox. The easiest way to do this is to map to a Docker volume or local folder on your machine. This will ensure that the content inside survives when the Docker container is stopped and removed.

• /workspace
  This folder should be mapped to the local folder on your machine where you store our JSON properties. Docker has no way to access our local files other than through directory mapping.

Configure The Environment

In order to prepare our environments to ensure that our data is organized and available, we’ll need two folders:

• /instances
  This folder will store our JSON properties and whatever else we need to build final JSON property.

• /.datastore
  This folder will store our Sandbox CLI cache (can be subfolder of the first one)

Here is how it looks on my PC:

Once everything is set up, we can use the Sandbox Docker image to start a new container with all folders and files mapped:

❯ docker run -it --rm --name akabox -p 9550:9550 -v $HOME/.edgerc:/root/.edgerc -v $(pwd)/instances:/sandboxes -v $(pwd):/workspace akamai/sandbox cat

Let’s dig into that code above. Here are several of the most common and useful commands:  

It can often look like the command is unresponsive, but the container is initialized and working when it looks like this:

The cat command is simply waiting for user input, which keeps the container running. We’ll see in a second why this pattern is convenient.

Note: You can stop the container by either pressing Ctrl+d or by entering stop akabox

Using Your Sandbox

1) Open your terminals.

Now we’re ready to create a new sandbox and deploy JSON to it. We’ll need three terminal windows or tabs. 

1. Long running Docker container

2. Sandbox client

3. Sandbox update and testing

2) Create a new sandbox.

In order to create a new sandbox, we’ll run the following command in the long running docker container terminal (1st terminal window):

❯ docker exec -it akabox akamai sandbox create --name lczerpak --property lczerpak-a2s.stg.webperf.it:403
 
building origin list
Detected the following origins: kr.czerpak.eu
? Do you want the Sandbox Client to proxy the origins in your dev environment to the destination defined in the Akamai config? Enter **y** and the CLI will automatically update your configuration file. If you w
ant to route sandbox traffic to different development origins, enter **n** to customize the origin mappings. Yes
registering sandbox in local datastore
sandbox_id: 11acd32a-dfc2-4a29-9828-5574e00ae205 lczerpak is now active
Successfully created sandbox_id 11acd32a-dfc2-4a29-9828-5574e00ae205 Generated sandbox client configuration at /cli/.akamai-cli/cache/sandbox-cli/sandboxes/lczerpak/config.json Edit this file to specify the port and host for your dev environment.

Note: The command above doesn't spin up a new container; it just executes akamai sandbox list inside of the already-running container: akabox 

3) Check that your sandbox has been created.

Now, let's check to ensure that it has been created by entering the following command:

❯ docker exec -it akabox akamai sandbox list
Local sandboxes:
 
current  name      sandbox_id
-------  --------  ------------------------------------
YES      lczerpak  11acd32a-dfc2-4a29-9828-5574e00ae205

4) Configure your port mapping.

We’ll need to ensure that our port mapping settings are correctly configured. Port mapping doesn't require any adjustments when using the Akamai Docker image. If you are not using the official Akamai Docker image, ensure the host attribute inside the sandboxServerInfo section in the instances/lczerpak/config.json file is set to 0.0.0.0. 

So the file - after the change - should look like this:

{
 "sandboxServerInfo": {
     "secure": false,
     "port": 9550,
     "host": "0.0.0.0"
 },
 "advanced": {
     "requestDetail": false
 },
 "originMappings": [
     {
         "from": "kr.czerpak.eu",
         "to": "pass-through"
     }
 ],
 "jwt": "........."}

5) Start your sandbox.

Let’s start our Sandbox instance in the sandbox client terminal window (2nd terminal window):

❯ docker exec -it akabox akamai sandbox start

Note: The command is executed inside the already-running container: akabox.

6) Update your sandbox.

Deploy rules JSON to the sandbox (3rd terminal window). Any further changes to the rules require only the last command to run in order to update the sandbox:

❯ docker exec akabox akamai sandbox update -r /workspace/rules.json 11acd32a-dfc2-4a29-9828-5574e00ae205

7) Check to see that the new rules are working.

Once we’ve run the command above, we should see the new rules working:

❯ curl -IXGET http://www.mytestingwebsite.com/ --connect-to ::localhost:9550
HTTP/1.1 200 OK
Server: nginx/1.16.1
Content-Type: text/html
...headers removed for brevity...
X-Akamai-Request-ID: 16c6b9a

Watch the Demo

Our demo video guides you through the whole process we outlined in this blog: 

Next Steps

At this point, you should have a working Sandbox and be more familiar with all of the steps needed to reproduce this in your own project. If you find yourself needing to do this often, look for ways to automate the process.

Here are a few other links you may find useful to learn more: 

• Read the docs for Akamai Sandbox.

• Get an overview of Akamai Sandbox.

• Learn about the Akamai Sandbox API.

• Install the Akamai Docker Image from Github.

About the Author

Łukasz Czerpak is a Senior Enterprise Architect at Akamai based in Kraków, Poland. He has 10+ years of experience designing, developing, and managing software projects, ISP infrastructure, and cloud services. Lukasz works with Akamai customers on some of our most advanced and complex integrations, he also provides consulting and DevOps training, and is a regular speaker at Technology Days.