Development environment setup

Akamai provides a Docker container with an ESI Test Server (ETS). While this ETS is not an exact replication of the ESI functionality available on the Akamai platform, it provides a pretty good approximation and can be a very helpful development and debugging tool.

Architecture#

In order to make it as easy as possible to use the Akamai ETS container, Uniform created a Docker application. While the Docker application makes the architecture of the local ESI runtime environment more complicated than using the ETS container by itself (3 containers instead of just 1), Docker hides that complexity from you.

When using the Docker application, the flow of control from the browser to Sitecore looks like the following:

The important points are:

The browser talks to ETS through Proxy 1.
ETS talks to Sitecore through Proxy 2.

Configure Docker application#

note

The local development environment does not have to run on a Windows PC. However, these instructions assume that you are, and use some PowerShell scripts to simplify the configuration process.

Prerequisites#

Docker Desktop - Installation instructions are available at https://www.docker.com/products/docker-desktop.
note
Docker does not have to be installed on the same machine that is running Sitecore, but containers must be able to make a network connection to your Sitecore instance.
Yarn - Installation instructions are available at https://yarnpkg.com/.
Docker files - These files come in a zip file available from Uniform.
Sitecore instance - Uniform must already be installed.

Unzip Docker files#

Unzip the Uniform Docker files on your PC.
Open a PowerShell CLI in the folder where you unzipped the files.

Switch to Linux container mode#

The ETS container is a Linux container. Docker Desktop for Windows is able to run Linux and Windows containers simultaneously, but in order to configure Linux containers, you must be in Linux container mode.

caution

If your Sitecore instance is running in Docker, you will be unable to access your Sitecore instance while Docker is running in Linux container mode.

Enter the following command:
```
.\Switch.ps1 -Linux
```

Build Docker images#

Enter the following command:
```
docker run -d -p 6000:6000 --name registry registry:2
```
note
This starts a Docker container that hosts a Docker image registry. The registry will be available on port 6000. If you have another process running on this port, you will need to change 6000 to a different value.

Enter the following commands:

cd .\proxy1\yarn build:proxy1docker image tag akamai-ets-proxy-1 localhost:6000/akamai-ets-proxy-1:latestdocker push localhost:6000/akamai-ets-proxy-1docker image rm akamai-ets-proxy-1cd ..

Enter the following commands:

cd .\proxy2\yarn build:proxy2docker image tag akamai-ets-proxy-2 localhost:6000/akamai-ets-proxy-2:latestdocker push localhost:6000/akamai-ets-proxy-2docker image rm akamai-ets-proxy-2cd ..

Configure application settings#

As shown in the diagram above, Proxy 2 connects to the Sitecore instance. It is necessary to ensure that Proxy 2 will be able to connect to the Sitecore instance. This means that different steps are needed depending on where the Sitecore instance is running.

If Sitecore and Docker are running on the same PC#

Create a file .env.
Add the following to the file:
```
LOCATION=locations\default.datORIGIN=[!!! SITECORE INSTANCE HOST NAME !!!]ORIGIN_IS_DOCKER_HOST=trueREGISTRY=localhost:6000SWITCH_ENGINE_IF_NEEDED=true
```
note
If your Sitecore instance is running on a port other than 80, you can specify that in the host name (e.g. myserver:8888).

If Sitecore is not running on the same PC as Docker#

Enter the following command:
```
docker exec -it registry ping -c 5 [!!! SITECORE INSTANCE HOST NAME !!!]
```
caution
If no IP address is resolved, or if the IP address resolved is 127.0.0.1, the Docker application will not be able to reach your Sitecore instance. You cannot continue with the setup until you have determined an IP address that can be reached from within the Docker application.
Create a file .env.

Add the following to the file:

LOCATION=locations\default.datORIGIN=[!!! SITECORE INSTANCE HOST NAME !!!]ORIGIN_IP_ADDRESS=[!!! IP ADDRESS !!!]REGISTRY=localhost:6000SWITCH_ENGINE_IF_NEEDED=true

note

If your Sitecore instance is running on a port other than 80, you can specify that in the host name (e.g. myserver:8888).

Switch to Windows container mode#

Enter the following command:
```
.\Switch.ps1 -Windows
```

Start Docker application#

Enter the following command:

.\Compose.ps1

Stop Docker application#

If you need to shut down the Docker application, enter the following command:

.\Shutdown.ps1

Change location data (optional)#

The Akamai Ion product is able to map a visitor's IP address to a geographic location. Uniform Optimize can use this data in order to support location-based personalization.

The ETS server simulates the Akamai runtime environment. It does not perform real location data, but it does provide the ability to return pre-defined location data.

This location data is specified when the ETS container is started.

In order to change location data, you must:

Stop the Docker application.
Change the LOCATION variable in the .env file.
If you want to disable location data, add the following line to the .env file:
```
DISABLE_LOCATION=true
```
Start the Docker application.