Installing ADE in a Docker image

This page guides you through the process of building a Docker image with an installed ADE. The configuration will allow ADE to run in a single Container at one time.

This is not an introduction to Docker or Docker for Windows. It is assumed that the reader consults other sources for that background.

Licensing

The standard End-User License Agreement, or EULA, for the ADE individual license allows you to run ADE on one production server. This would not be consistent with an elastic deployment of containers that spins up an unlimited number of containers, each being a virtualized server instance. The instructions on this page are consistent with the ADE EULA, in that it will allow you to launch a single container with ADE. If your use case differs, you'll need to discuss alternative licensing arrangements with Lumina.

The use of a single container is still quite valuable for deployment purposes separate from the elastic use case.

To proceed you need to have purchased an ADE subscription and received an ADE activation key from Lumina.

Setup for your development computer

Before building your Docker image, you'll need to install Docker Desktop for Windows. After installing it, right-click on the Docker icon in your tray and select Switch to Windows containers.... If you don't see the docker icon in your Windows tray, or don't see the context menu, launch Docker Desktop as Administrator one time. We've found that doing so once seems to fix that problem.

Create a new folder for your docker source, for example it might be: D:\ADE_image. Create a subfolder inside named D\Ade_image\Content.

If you have previously installed ADE 6.5 on this development computer, then copy the "C:\Program Files\Lumina\ADE 6.5" folder into your Content folder. If it is not installed on your computer and you won't be using ADE on this computer, you can run the ADE installer and install it into "D:\ADE_image\Content\ADE 6.5", leaving the activation code blank.

Select Windows subsystem and MAC address

Your docker image needs to include a Windows operating system image. The Windows nano image lacks capabilities that are required for using COM objects like ADE. We recommend starting with a Windows Server Core image. The image you use for your container image must be compatible with your host operating system. Here I use the mcr.microsoft.com/windows/servercore:20H2 image. This image works with Windows 10 20H2 as well as Windows Server 20H2.

At a command line, type:

docker run -i --name core0 mcr.microsoft.com/windows/servercore:20H2

If your host system is not compatible with this image (see these tables), you may need to changed the 20H2 part accordingly. The first time you run this, it will download the entire Windows Server Core image from the docker hub, which will likely take a while. Once complete, you'll find yourself at a command line in a container instance of Windows Core.

To configure your ADE license, you'll need to select an ethernet MAC address. The instance you are running has been assigned a random one, which should make a good choice. To find it type:

ipconfig /all

and note the "Physical address", which is 12 hex digits and looks something like 00-51-D5-63-F9-12. This needs to be unique for your instance, and you can assume the one that appears here is. Carefully note these 12 hex digits, you'll need to use this in two of the steps below.

You are done for now with this instance. Type:

exit

which terminates the container instance and returns you to your own computer's CMD prompt. Then type:

docker container rm code0

Activate your ADE license

In this step, you'll activate your ADE license for your container instance. To do this, you'll need your ADE activation key provided to you by Lumina when you purchased ADE, and you'll need the MAC address from the previous section.

Go to the Manual Activation Page. Select ADE+Individual and enter the remaining info. When you enter the host id, enter the prefix "ether=" (without the quotes) followed by the 2 hex digits from your MAC address in lower case and without any hyphens or other punctuation. The "ether=" ensures the hostid will be processed correctly for this special case. So for instance if your MAC address is 00155d63f912 , you would enter ether=00155d63f912 in the hostid field. When you submit the form, the activated license is displayed on the next page (and it is emailed to you as an attachment). The license looks something like this, but has your license name (ade_0_2 in this example) and your host id (00155d63f912 in this example) that will be different from this example:

LICENSE lumina ade_0_2 9.99 10-mar-2022 uncounted hostid=00155d63f912
 share=h issuer={7}DaleRice platforms=x86_w,x64_w issued=9-mar-2021
 replace=ade64_0_2 options=ADE _ck=6aff14fa8f sig="60P0450RTT8523T2E
 5RK00QNDED3TC7Q9EUWT5G22G8681QTFN76H8RR1PE41X1R1A3KSC78IV"

Double check that there are no intervening fields in the host id (such as "disksn="). If there are, contact suppport@lumina.com for help.

When you first launch your container, you'll want to have a way to verify that ADE is installed and has a valid license. For that, copy TestAde.vbs into your Content directory.

Save this file in your D:\ADE_image\Content directory. Your Content folder now contains:

> DIR /w Content
[.]      [..]      [ADE 6.5]      ade_0_2.lic      TestAde.vbs

Create the Dockerfile

Create and edit the file D:\ADE_image\Dockerfile in a text editor (make sure your text editor doesn't append an extention like .txt). Copy this code into the file:

# A Docker image or Server Core with ADE installed
#
# The windows image needs to match the host. If not, change the tag at the end of the following as necessary.
FROM mcr.microsoft.com/windows/servercore:20H2
 
WORKDIR /Tools
COPY ./Content/rlmhostid.exe .
COPY ./Content/TestAde.vbs .
 
WORKDIR "c:/ProgramData/Lumina/Licenses"
COPY ./Content/*.lic .
 
WORKDIR "c:/Program Files/Lumina/ADE 6.5"
COPY ["./Content/ADE 6.5/", "."]
# *** IMPORTANT: In the next line, substitute your ADE license name!! ***
RUN ade.exe /w /lic:ade_0_2
 
WORKDIR /Tools

Double check that you've substituted your ADE license name where ade_0_2 appears above.

After saving, build the image by executing the following at a command line:

cd D:\ADE_image

docker build -t coreWithAde .

You now have your docker image! To see that it is there, type:

docker images

Launching the container

A Docker container is a running instance of a Docker image. You are now ready to launch your container. For this step, you'll need the unique MAC address noted previously (00-51-D5-63-F9-12 in my example). You're doing to replace the hyphens with colons and launch your container from a CMD line as follows:

docker run -i --mac-address=00:51:D5:63:F9:12 --name adeServer coreWithAde

You should now see the command line prompt:

C:\Tools>

You are inside your server core instance. To test that ADE in correctly installed, type:

C:\Tools> CScript TestAde.vbs

The output reveals whether ADE is successfully installed and whether your ADE license is valid. If so, you have yourself a Docker image of Windows Server with ADE installed (and running)!

Next tasks

Now that you are set with ADE, you'll want to add your own code or website to the Docker image. These tasks are beyond the scope of this article, but are fully within the scope of Docker's own documentation.

Finally, you'll want to publish to your DockerHub account and then migrate to a cloud hosting service like GCP, AWS or Azure. Again, beyond the scope of this article by covered by Docker's own documentation.

Other notes

In the future, I may expand this article to include running ADE in multiple container instances on the same VM with a single ADE license. This uses the UUID host id type (instead of MAC address), which is unique to the VM instance but varies by VM. Requires some additional steps to obtain the UUID for your deployment VM, plus isn't as convenient in terms of being able to run in the same docker image on your computer before deploying to the cloud.