# Pulling a custom Docker image from an authenticated repository

You can create a custom start script to configure the TERR service to log in to a remote authenticated repository and pull a custom Docker image.

## About this task

This option is available if you want to specify a base image for the docker container, but it is in a repository that requires authentication to access. To set the appropriate authentication credentials, you can execute a Docker login command when you start the service, but before starting the Docker container, as part of a startup hook script.

This task demonstrates accessing a Docker image stored in the AWS Elastic container Registry, which is an authenticated repository.

## Before you begin

- You must have a Linux computer where the node manager is installed. (Your node manager and Spotfire Server are usually on different computers).

Custom docker images for the service must contain the following.

- The Java 17 Runtime.
- The JAVA_HOME environmental variable, correctly defined.

      ENV JAVA_HOME=</correct/path/to/java>

## Procedure

1. If you have already installed the service from the Spotfire Server Nodes & Services administration page, and if it is running, then stop the service.
2. Install the AWS command-line interface (CLI) tool on the computer running the node manager.
   See https://docs.aws.amazon.com/cli/latest/userguide/awscli-install-bundle.html for more information.
   1. Run the command `aws configure`, and then connect to your account using your AWS Access Key and AWS Secret Access Key.
   2. Verify that the user running the TERR service can run the `aws` process.
3. Determine your `docker.image.name` property.
   1. In your AWS account, navigate to Amazon ECR > Respositories.
      The docker image name is listed after `Repository URI`, and the tag is listed after `Image Tags`.

          Repository URI 123456.dkr.ecr.us-west-2.amazonaws.com/terr/terrsrv-sample
          Image Tags: latest

   The `docker.image.name` property is a concatenation of those two values.

       docker.image.name: 123456.dkr.ecr.us-west-2.amazonaws.com/terr/terrsrv-sample:latest

4. On the computer running the Spotfire Server, export the custom.properties.
5. On the computer running the Spotfire Server, create a custom script and save it to your custom configuration directory <server installation dir>/tomcat/spotfire-bin/config/root/conf/.
   The script uses the AWS `get-login` command to fetch the `docker login` command. See the following links for more information:
   - https://docs.aws.amazon.com/cli/latest/reference/ecr/get-login.html
   - https://docs.docker.com/engine/reference/commandline/login/
   In the script, use the absolute path to the `aws` command (usr/local/bin/aws).

   We named this sample script awsScript.sh.

   If saved to a custom configuration, it resides at the relative path conf/awsScript.sh.

   Important: Remember that for any script you write, the line endings must be appropriate for the operating system where the service runs. Many text editors can perform end-of-line (EOL) conversion.

       #!/bin/bash
           # Request a login from AWS
           # The command will return a 'docker login' string
       DOCKER_LOGIN=`/usr/local/bin/aws ecr get-login --no-include-email --region us-west-2`
       echo Retrieved the command ${DOCKER_LOGIN}
           # Execute that 'docker login'
       ${DOCKER_LOGIN}
       echo docker login authentication completed.

6. From the command line, manually test your script at this stage to ensure that everything works correctly.
7. Edit the relevant properties in the file custom.properties with the appropriate values.

       docker.image.name: 123456.dkr.ecr.us-west-2.amazonaws.com/terr/terrsrv-sample:latest
       use.engine.containers: TRUE
       startup.hook.script: conf/awsScript.sh

8. From the command line, manually test the script again to make sure that it works correctly.
9. On the computer running the Spotfire Server, import the custom.properties.
10. From the Spotfire Server Nodes & Services administration page, install the service, specifying the configuration to use, and then start the service.

    If you have already installed the service, then, under the node manager, select the service and click Edit. From the Configuration drop-down list, select the new configuration.

## What to do next

If problems occur, troubleshoot by examining the Dockerfile that the service writes. After the service runs, this Dockerfile is available at the root service directory on the computer running the node manager. For example, /opt/nodemanager/<version>/nm/services/<language>-service-linux-<version_#_ID>/dockerfile/Dockerfile.