Skip to content

Containerising AMI

This guide will walk you through creating a docker image containing a licensed copy of 3forge AMI. You will need to be able to find the AMI install directory which will usually be:

  • Windows C:/Program Files/ami/amione/
  • Unix /home/ubuntu/ami/amione
  • Mac /Applications/AMI One.app/Contents/java/app/amione

Installing AMI

  1. Register an account on 3forge if you have not already done so.
  2. Login and click Files on the navigation pane on the left of the window.
  3. Download the installer appropriate to your Operating System.
  4. Run the installer.

See here for more detailed instructions and further information.

Modify the Startup Script

AMI comes with a startup script that only needs minor changes to be used in a container.

Backup

We advise that you create a backup of the file before making changes.

  • First, navigate to the AMI install directory and locate the file start.sh in the scripts directory.

  • Remove the ampersand ( & ) on the end of line 65:

    script.sh
    64
65
    ...
java  ${JAVA_OPTIONS} $* -classpath $CP $APPCLASS >> log/stdout.log 2> log/stderr.log &

  • Remove all lines in script.sh after line 65.

Create a License

Existing Licenses

If you have an existing license for a hostname that will not be used for the containerised version you should move it to another location before continuing.

If you wish to run AMI in unlicensed mode you can skip the rest of this step.

You should now decide on the hostname you wish to use for the containerised AMI instance. For the purposes of this guide we will be using the hostname ami_demo.

  1. Create a license either via the the 3forge website or from within AMI for the host ami_demo.
  2. Store the ami_demo license in a file called f1license.txt in the AMI install directory (amione).

Create the Dockerfile

  • Go to the AMI install directory and create a new file called Dockerfile.
  • Copy the text below into this new file:
Dockerfile
FROM ubuntu:18.04

RUN apt-get update && apt-get install -y openjdk-8-jdk && apt-get -y install gettext-base
RUN cp /etc/profile /root/.profile

WORKDIR amione

COPY . /amione

EXPOSE 33332

CMD ["/bin/bash", "/amione/scripts/start.sh"]
  • If you need to stream realtime data to AMI you should also expose port 3289 by adding (separated by a space) it to the highlighted line above.

Creating and Running the Docker Image

Run the following command to create a Docker image using the Dockerfile we created in the previous step.

docker build -t amidocker .

This will build the image using the Dockerfile and tag it (-t) with the tag amidocker.

Run the following command to run the docker instance, map the relevant port(s) and set the hostname.

docker run -p 33332:33332 -h <YOUR_CHOSEN_HOSTNAME> amidocker

If you want to expose the realtime streaming port you should run:

docker run -p 33332:33332 -p 3289:3289 -h <YOUR_CHOSEN_HOSTNAME> amidocker

Once the container has started up you should be able to visit: http://localhost:33332/portal/portal.jsp in your browser and login.

The image can be stopped using the following command: 

docker stop amidocker

Troubleshooting

If your docker image is failing to start there could be a number of reasons.

  • If the exit code is 0, the image does not have a foreground process attached. Double check that the last line in the start.sh script is the java command and that there IS NOT an & at the end of the line.
    • The exit code can be shown (in most unix shells) using the command: echo $?

  • A useful debugging tool is to comment out the standard error and standard out redirects used on the java command in the start.sh file.

    script.sh
    64
65
    ...
java  ${JAVA_OPTIONS} $* -classpath $CP $APPCLASS # >> log/stdout.log 2> log/stderr.log

After rebuilding the docker image, when running the container AMI should output more information that may be useful for troubleshooting.