Get Started with DevPoPs

Developer Points of Presence (DevPoPs) is an isolated Akamai environment you can use for testing development versions of property configurations before deploying.

Read the Akamai Sandbox overview to learn more about the benefits.

Who should use this guide

Developers who want to rapidly test Akamai configurations in a local development environment.

These instructions are specifically for Akamai customers participating in the DevPoPs Tech Preview.

Objectives

Upon completion of this exercise, you will be able to:

Create a sandbox from an Akamai property.
Connect your local development machine to the sandbox.
Verify that requests are routed through the sandbox.

Required setup

Before beginning this exercise:

Create an API client in Luna for DevPoPs with READ-WRITE access. Follow the Get Started with APIs instructions to learn how to configure credentials to access the API.
Set the JAVA_HOME variable to the path to your home directory for Java (Java 1.8+ required). Example code (path may vary):
export JAVA_HOME=/Library/Java/JavaVirtualMachines/jdk1.8.0_60.jdk/Contents/Home/

Step 1: Create a sandbox

In this step, you’ll create a sandbox from an existing Akamai property. For details on all the options available, review the DevPoPs API.

Include the propertyName and propertyVersion of the property you want to add to your sandbox in the JSON request object, and assign the sandbox a unique name:
```
{
"createFromProperty": {
    "propertyName": "example.com"
    "propertyVersion": 123,
}, 
"name": "mysandbox-123"
}
```
NOTE: If you don’t include the version number, the sandbox will default to the propertyVersion currently on production.
Make a POST request.

POST https://akzz-XXXXXXXXXXXXXXXX-XXXXXXXXXXXXXXXX.luna.akamaiapis.net/devpops-api/v1/sandboxes

View the response.

{
  "sandboxId": "12a3b4c5-d678–4e8b-a3dc–8273dde7dc3a",
  "jwtToken": "abC0deFGhiOJKL123mn456PqR7.st89uv3WxOYZa2FtYWkgU2FuZGJveCIsInNhbmRib3hJRCI6ImU1OTQ5MDZmLTZhOWYtNDRmZS1hNzY2LTFhMjg1MDQ5MmI4ZSIsImV4cCI6MTU1NDMxMTY2Nn0.eClj9mNVyBPFHRFt-hgC4qL4YqBRSudKpY5VoxrH6sQdFCkNfYtud18gvmb9pRzFhGQVxtEDMnTCdc7uzmYy_OIyiipcsZmwnEgGLQmRCsexDYqziIAmFMZs3PgcJ_N6K3Kscfp6u4B4m1GFjhg_N-yR5pnrzTEFChIHIXs9GxZQwbD-QgpEJh09MQwQznzItJVCR8XaqgrqX9JW6WUs8cbphj411WmwOuSnuD0v-emS55vGvw9bJAEi_PjkcOwXrI3v8-9B2cShBgyTbQkh1jd29NhkPyd8C9yxSXdu3OJxPmTsK8P-cY8PwnWXOVoLLKWQwd8axWPbOnCCv5HAIA",
  "_links": {
"sandbox": {
  "href": "/devpops-api/v1/sandboxes/12a3b4c5-d678–4e8b-a3dc–8273dde7dc3a"
},
"rules": {
  "href": "/devpops-api/v1/sandboxes/12a3b4c5-d678–4e8b-a3dc–8273dde7dc3a/properties/0zyx0414-5w1a-7b69-cd28-032mn4828p9s4/rules"
},
"property": {
  "href": "/devpops-api/v1/sandboxes/12a3b4c5-d678–4e8b-a3dc–8273dde7dc3a/properties/0zyx0414-5w1a-7b69-cd28-032mn4828p9s4"
},
"rotateJWT": {
  "href": "/devpops-api/v1/sandboxes/12a3b4c5-d678–4e8b-a3dc–8273dde7dc3a/rotateJWT"
}
  }
}

NOTE: It takes about a minute to create the sandbox. If you get a timeout error, adjust the settings in your client (e.g., httpie or egcurl).

Copy the jwtToken from the response, and save it in a text editor. In the next step, you’ll paste it into the DevPoPs Client configuration.
Copy the sandbox href from the response, and make a GET request.

GET /devpops-api/v1/sandboxes/12a3b4c5-d678–4e8b-a3dc–8273dde7dc3a.

Note details of the sandbox you created, including the requestHostnames associated with the property.

{
  "sandboxId": "12a3b4c5-d678–4e8b-a3dc–8273dde7dc3a",
  "createdBy": "developer@example.com",
  "createdOn": "2018-10-01:02:34.222Z",
  "name": "mysandbox-123",
  "isClonable": false,
  "status": "OK",
  "properties": [
{
  "sandboxPropertyId": "0zyx0414-5w1a-7b69-cd28-032mn4828p9s4",
  "requestHostnames": [
    "www.exampledevops.com",
    "shop.devops.com"
  ],
  "_links": {
    "property": {
      "href": "/devpops-api/v1/sandboxes/12a3b4c5-d678–4e8b-a3dc–8273dde7dc3a/properties/0zyx0414-5w1a-7b69-cd28-032mn4828p9s4"
    },
    "rules": {
      "href": "/devpops-api/v1/sandboxes/12a3b4c5-d678–4e8b-a3dc–8273dde7dc3a/properties/0zyx0414-5w1a-7b69-cd28-032mn4828p9s4/rules"
    }
  }
}
  ],
  "_links": {
"self": {
  "href": "/devpops-api/v1/sandboxes/12a3b4c5-d678–4e8b-a3dc–8273dde7dc3a"
},
"rotateJWT": {
  "href": "/devpops-api/v1/sandboxes/12a3b4c5-d678–4e8b-a3dc–8273dde7dc3a/rotateJWT"
}
  }
}

NOTE: The requestHostnames in the sandbox match those contained within the property configuration.

Step 2: Configure the DevPoPs Client

The DevPoPs Client is a proxy server that routes bidirectional requests between your development machine and the Akamai network via a secure gateway. In this step, you’ll set up the connection to your sandbox and configure it to point to your development environment as origin.

Download the DevPoPs Client and extract the files.
Open config.json in a text editor.
Set the originMappings appropriate for your dev environment. For this example, the DevPoPs Client is running over HTTPS on port 443 and the development site is running over HTTP at localhost on port 9001. Change <ORIGIN HOST> to the hostname defined in your property configuration for origin requests.
Paste your jwtToken where it says <ENTER JWT HERE>, then save the file.

NOTE: If you neglected to copy the jwtToken when you created the sandbox, make a POST request to /devpops-api/v1/sandboxes/{sandboxId}/rotateJWT to generate a new one.
In a command-line tool, navigate to the directory that contains the DevPoPs Client, then run the script appropriate for your operating system.

Operating System	Script
Windows	`/bin/connector.bat`
Linux/Mac	`/bin/connector.sh`

Step 3: Test a request through your sandbox

In this step, you’ll point a requestHostname to your sandbox so that the browser will retrieve content from the development machine rather than the production origin, and validate that the DevPoPs Client is routing requests securely through your sandbox.

Open your /etc/hosts/ file, and add the requestHostname.
Enter a URL into your browser, such as www.example.com.
Confirm that the response is returned from your developer sandbox. You’ll see the response header X-Akamai-Sandbox=true.

Examples

In this quick exercise, you tried one simple way to create a sandbox. Here are a few examples of other methods you can try.

Create from hostname

To create a sandbox based on a hostname (for this example, make it clonable), form a JSON object as shown, then issue a POST request to /devpops-api/v1/sandboxes.

 {
     "createFromProperty": {
        "hostname": "www.anotherexample.com"
        "isClonable": true     }, 
     "name": "mysandbox-456"
 }

Specify request hostnames

To specify one or more request hostnames when you create a sandbox, form a JSON object as shown, then issue a POST request to /devpops-api/v1/sandboxes.

{  
   "createFromProperty":{  
      "propertyName":"example.com"
   },
   "name":"mysandbox-789",
   "requestHostnames":[  
      "portal.example.com",
      "store.example.com"
   ]
}

Clone a sandbox

To clone a pre-configured sandbox created by another developer, ask the developer to give you the sandboxId, then issue a POST request to /devpops-api/v1/sandboxes/{sandboxId}/clone.