View source for Installing ADE in a Docker image

[[Category: ADE User Guide]]
{{ReleaseBar}}

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 since 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 [https://hub.docker.com/editions/community/docker-ce-desktop-windows 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: <code>D:\ADE_image</code>.  Create a subfolder inside named <code>D\Ade_image\Content</code>.

If you have previously installed ADE {{#svarget:anarelease|5.4}} on this development computer, then copy the <code>"C:\Program Files\Lumina\ADE {{#svarget:anarelease|5.4}}"</code> folder into your <code>Content</code> folder.  If it is not installed on your computer and you won't be using ADE on this computer, you can run the [https://analytica.com/support-2/analytica-downloads/ ADE installer] and install it into <code>"D:\ADE_image\Content\ADE {{#svarget:anarelease|5.4}}"</code>, 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 [https://hub.docker.com/_/microsoft-windows-servercore Windows Server Core] image.  The image you use for your container image [https://docs.microsoft.com/en-us/virtualization/windowscontainers/deploy-containers/version-compatibility?tabs=windows-server-20H2%2Cwindows-10-20H2 must be compatible with your host operating system]. Here I use the <code>mcr.microsoft.com/windows/servercore:20H2</code> image. This image works with Windows 10 20H2 as well as Windows Server 20H2.

At a command line, type:
:<code>docker run -i --name core0 mcr.microsoft.com/windows/servercore:20H2</code>

If your host system is not compatible with this image (see [https://docs.microsoft.com/en-us/virtualization/windowscontainers/deploy-containers/version-compatibility?tabs=windows-server-20H2%2Cwindows-10-20H2 these tables]), you may need to changed the <code>20H2</code> 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:
:<code>ipconfig /all</code>
and note the "Physical address", which is 12 hex digits and looks something like <code>00-51-D5-63-F9-12</code>.  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:
:<code>exit</code>
which terminates the container instance and returns you to your own computer's CMD prompt.  Then type:
:<code>docker container rm code0</code>

== 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 [https://analytica.com/support-2/activate-analytica/ Manual Activation Page]. Select ADE+Individual and enter the remaining info. ''When you enter the host id, enter the 12 hex digits from your MAC address in lower case and without any hyphens or other punctuation''.  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 (<code>ade_0_2</code> 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 <code>D:\ADE_image\Content</code> directory.  Your Content folder now contains:
 > DIR /w Content
 [.]&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;[..]&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;[ADE {{#svarget:anarelease|5.4}}]&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;ade_0_2.lic&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;TestAde.vbs

== Create the Dockerfile ==

Create and edit the file <code>D:\ADE_image\Dockerfile</code> 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
 &nbsp;
 WORKDIR /Tools
 COPY ./Content/rlmhostid.exe .
 COPY ./Content/AdeNews.exe .
 COPY ./Content/TestAde.vbs .
 &nbsp;
 WORKDIR "c:/ProgramData/Lumina/Licenses"
 COPY ./Content/*.lic .
 &nbsp;
 WORKDIR "c:/Program Files/Lumina/ADE {{#svarget:anarelease|5.4}}"
 COPY ["./Content/ADE {{#svarget:anarelease|5.4}}/", "."]
 # *** IMPORTANT: In the next line, substitute your ADE license name!! ***
 RUN ade64.exe /w /lic:ade_0_2
 &nbsp;
 WORKDIR /Tools

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

After saving, build the image by executing the following at a command line:
<code>
:cd D:\ADE_image
:docker build -t coreWithAde .
</code>

You now have your docker image!  To see that it is there, type:
:<code>docker images</code>

== 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 (<code>00-51-D5-63-F9-12</code> in my example). You're doing to replace the hyphens with colons and launch your container from a CMD line as follows:
<code>
:docker run -i --mac-address=00:51:D5:63:F9:12 --name adeServer coreWithAde
</code>

You should now see the command line prompt:
<code>
:'''C:\Tools>'''
</code>

You are inside your server core instance. To test that ADE in correctly installed, type:
<code>
:'''C:\Tools>''' CScript TestAde.vbs
</code>

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.