Smile CDR v2023.05.PRE
On this page:

3.1Docker Container Installation

 

This page provides additional details and guidance regarding installing Smile CDR in a Docker container. This section can be skipped if Smile CDR is being installed as a server application.

3.1.1Quick Start

 

Option 1: Deploying and Launching Smile CDR Using the Smile CDR Registry

The following steps will result in a basic deployment of Smile CDR with out-of-the-box configuration in a Docker container.

  1. Login to the private Docker registry
docker login docker.smilecdr.com

Note: You will need to contact the Customer Success team to obtain your login information.

  1. Pull the Docker image with the following command (substituting the image tag as appropriate)
docker pull docker.smilecdr.com/smilecdr:2020.08.R02
  1. Launch the Smile CDR Docker container

Replace :2020.08.R02 with the version of Smile CDR you wish to use

docker run -p 8000:8000 -p 8001:8001 -p 9000:9000 -p 9100:9100 -p 9200:9200 -p 9201:9201 \
-v smilecdr_log:/home/smile/smilecdr/log \
-v smilecdr_db:/home/smile/smilecdr/database \
-v smilecdr_mq:/home/smile/smilecdr/activemq-data \
--name smilecdr \
docker.smilecdr.com/smilecdr:2020.08.R02
  • -p – The port to forward from the container to the host. ex: -p 8080:80 would forward port 80 from the container to the host
  • -v – A docker volume to mount into the container. ex: -v smilecdr_log:/home/smile/smilecdr/log creates a docker volume if it doesn't yet exist or uses the volume named smilecdr_log and mounts it to /home/smile/smilecdr/log in the container
  • --name – The container name
  1. Check logs

To monitor the progress of the launch, you can view the logs using the following command:

docker container logs -f smilecdr

Option 2: Deploying and Launching Smile CDR Using the Prebuilt Docker Image Tarball

The following steps will result in a basic deployment of Smile CDR with out-of-the-box configuration in a Docker container.

  1. Load the image into Docker using a command similar to the following (substituting the actual name of the Docker image file provided):
docker image load --input="/path/to/smilecdr-2019.05.R01-image.tar.bz2"
  1. Create a Docker container from the image
docker container create -p 8000:8000 -p 8001:8001 -p 9000:9000 -p 9100:9100 -p 9200:9200 -p 9201:9201 \
-v smilecdr_log:/home/smile/smilecdr/log \
-v smilecdr_db:/home/smile/smilecdr/database \
-v smilecdr_mq:/home/smile/smilecdr/activemq-data \
--name smilecdr \
smilecdr
  • -p – The port to forward from the container to the host. ex: -p 8080:80 would forward port 80 from the container to the host
  • -v – A docker volume to mount into the container. ex: -v smilecdr_log:/home/smile/smilecdr/log creates a docker volume if it doesn't yet exist or uses the volume named smilecdr_log and mounts it to /home/smile/smilecdr/log in the container
  • --name – The container name

The above command will create a container for Smile CDR with the following attributes:

  • Container will be based on the previously loaded image "smilecdr" (as per the final argument).
  • Container will be named "smilecdr" (as per the "--name" option).
  • The ports configured inside the container out-of-the-box, 8000, 8001, 9000, 9100, 9200 and 9201, will be published and mapped to the same numbers outside of the container (as per the "-p" options). Note that a port will need to be forwarded for each module you wish to communicate with outside of Docker.
  • Docker volumes will be created and mapped to the folders containing the Smile CDR logs, the H2 database data, and Active MQ data inside the container (as per the "-v" options). The contents of these folders will be managed separately by Docker allowing the data to persist even if the container changes.
  1. Launch Smile CDR Docker container
docker container start smilecdr

The above command will launch Smile CDR in the Docker container. Smile CDR will run in the background.

  1. Check logs

To monitor the progress of the launch, you can view the logs using the following command:

docker container logs -f smilecdr

Option 3: Deploying and Launching Smile CDR Using docker-compose Command

Alternatively, you can both build and run a Docker container using the docker-compose command with a docker-compose.yml file. Steps are as follows:

  1. Load the image into Docker as previously described in Option 1 or Option 2.

  2. Create a docker config file

    Create a file named docker-compose.yml containing the following:

    version: "3.8"
    services:
      smilecdr:
        container_name: smilecdr
        image: smilecdr
        ports:
          - "8000:8000"
          - "9000:9000"
          - "9100:9100"
          - "8001:8001"
          - "9200:9200"
          - "9201:9201"
        volumes:
          - db:/home/smile/smilecdr/database
          - log:/home/smile/smilecdr/log
          - mq:/home/smile/smilecdr/activemq-data
        restart: "unless-stopped"
    volumes:
      db:
      log:
      mq:
    

    The docker-compose.yml file above specifies the port mappings to be used between the container and the host machine and the volumes to be used to persist the database, logs, and activemq files.

  3. Launch Smile CDR in Docker container

    Execute the following command

    docker-compose -f /path/to/docker-compose.yml -p smilecdr up -d
    

    The options above specify the location of the docker-compose.yml file (-f), prefix to use when creating names for the volumes (-p) and to run Smile CDR in the background (-d). To monitor the progress of the launch, you can view the logs using the following command:

    docker logs -f smilecdr
    

    Docker supports a variety of options for creating and/or launching containers using the docker container and docker-compose commands. For more information about other options available, refer to the Docker Reference documentation here.

Verifying Deployment

Assuming you see the phrase Smile, we're up and running! :) in the logs, you have now started the software. To exit the logs without stopping the container, simply type (ctrl-c).

With the software started, you can try a few things (replace localhost in the URLs below with the host name of your server if you are installing to a remote server):

  • Log into the Web Admin Console at http://localhost:9100.
    • This is the administration UI for configuring the system.
    • Username: admin (by default a single user with full privileges is created)
    • Password: password
  • Log into the FHIRWeb Console at http://localhost:8001.
    • This is a FHIR testing tool which lets you explore the FHIR API.
  • Make FHIR requests against the endpoint at http://localhost:8000
    • This is an actual FHIR endpoint, so it is best to use a REST utility such as Postman to work with this endpoint. Note that by default the endpoint is secured with HTTP Basic auth, and will not accept anonymous requests.
  • Explore the JSON Admin API at http://localhost:9000.
    • This API may be used to configure the system via REST calls.

Troubleshooting Problems

If Smile CDR fails to start or does not appear to be responsive, here are a couple things that you can check:

  • Check whether the container is running by executing the command docker container ls. If the container is running, you should see output similar to the following:
CONTAINER ID        IMAGE               COMMAND                  CREATED             STATUS              PORTS                                                                                                                NAMES
7e401352ab80        smilecdr            "/home/smile/smilecd…"   22 minutes ago      Up 17 minutes       0.0.0.0:8000-8001->8000-8001/tcp, 0.0.0.0:9000->9000/tcp, 0.0.0.0:9100->9100/tcp, 0.0.0.0:9200-9201->9200-9201/tcp   smilecdr
  • Retrieve and/or examine the Smile CDR logs. There are a couple of options available for this:
    • Use the command docker logs smilecdr to see recent console output.
    • Copy the log files from the container to a local folder as follows:
    docker cp smilecdr:/home/smile/smilecdr/log /path/to/local/folder/log 
    

Clean Up

When you are finished with this initial test, you can stop and delete the container and volumes for database and log:

$ docker container stop smilecdr
smilecdr
$ docker container rm smilecdr
smilecdr
$ docker volume rm smilecdr_db smilecdr_log smilecdr_mq
smilecdr_db
smilecdr_log
smilecdr_mq
$ 

Alternatively, if you you used docker-compose to create and start your Docker container instance, than you can also use it to stop and clean up the container deployment:

docker-compose -f /path/to/docker-compose.yml -p smilecdr down -v

This command will stop the container, remove it and the three volumes.

3.1.2Basic Configuration

 

To retrieve and review copies of the bin/ and classes/ folders deployed to the container when it is not running, you can use the docker cp command as follows:

  • docker cp smilecdr:/home/smile/smilecdr/bin /path/to/copy/bin
  • docker cp smilecdr:/home/smile/smilecdr/classes /path/to/copy/classes

Before starting Smile CDR for the first time, there are two files you will want to examine for settings.

1. Environment Settings

In the bin/ directory you will find a file called setenv. This file may be used to change the amount of RAM available to Smile CDR, as well as number of other low level settings. It is a good idea to glance over it and ensure that the default settings make sense for your installation.

2. Application Configuration

In the classes/ directory you will find a file called cdr-config-Master.properties. This file contains all of the configuration for the modules which will be created the first time the system is started.

If changes are required to either of the configuration files above, these can be made by editing local copies of the configuration in the container and then copying the modifications back to the container using the docker cp command:

docker cp /path/to/copy/bin/setenv smilecdr:/home/smile/smilecdr/bin

3.1.3Customizing Smile CDR in Docker Container

 

If there is a need to change the configuration files or environment settings or to add jars to the customerlib/ directory in the Smile CDR container you can do this by creating a customized Smile CDR image based on the provided Smile CDR image and then re-creating the container using the command shown previously here.

To create a customized Smile CDR image:

  1. Setup Docker context

    When building Docker images, you need to specify a single folder or context where Docker can find all of the build dependencies. Ensure that all of your configuration changes and additions are contained within a single folder, or create a new subfolder and copy all of your changes there.

  2. Create a Dockerfile

    Create a new Dockerfile that uses the original Smile CDR image as the base image and includes instructions for any additions or updates needed for the new image. For example:

    # Use base Smile CDR image as parent image
    FROM smilecdr
    
    # Set the smilecdr folder as working directory
    WORKDIR /home/smile/smilecdr
    
    # Copy modified properties file to the container.
    copy ./cdr-config-Master-modified.properties ./classes/cdr-config-Master.properties
    
    # Copy modified environment settings file to the container.
    copy ./setenv_modified ./bin/setenv
    
    # Add jar files to customerlib folder.
    copy ./sitelib.jar ./customerlib/sitelib.jar
    
  3. Build a new Docker image

    Execute the docker image build command to build a new image, for example:

    docker image build -f path/to/Dockerfile --tag=smilecdr_site path/to/Docker/context 
    

    The -f option above is used to specify the path and name of the Dockerfile, the --tag option is used to specify a tag or name for the new Smile CDR image (the base image will have tag "smilecdr"). The last parameter is the location of the Docker context folder which contains all of the changes and additions that are to be copied/added to the image.

    NOTE: If you need to add or change any port numbers in relation to the above changes, then you will also need to update the port mappings specified by the -p options included with the docker create command.

3.1.4Using System Environment for Variable Substitution

 

Environment variables can be set inside the Smile CDR Docker container using the -e, --env or --env-file options in the docker container create or docker run commands.

Configuration Properties

For example, if different environments use a different database password, you can create a custom Smile CDR Docker image that includes a cdr-config-Master.properties file with the following parameters:

module.clustermgr.config.db.password    =#{env['DB_PASSWORD_MGR']}
module.persistence.config.db.password   =#{env['DB_PASSWORD_FHIR']}

Then you can build your container, setting a different password for each environment using a command similar to the following:

docker container create -e DB_PASSWORD_MGR=MySecretPassword -e DB_PASSWORD_FHIR=SmileCDR -p 8000:8000 -p 8001:8001 -p 9000:9000 -p 9100:9100 -p 9200:9200 -p 9201:9201 -v smilecdr_log:/home/smile/smilecdr/log -v smilecdr_db:/home/smile/smilecdr/database -v smilecdr_mq:/home/smile/smilecdr/activemq-data --name smilecdr smilecdr

Runtime Environment Settings

Alternatively, Docker container environment variables can be used to override default JVM and other environment settings normally determined by the setenv script. For example the following command could be used to build and launch a Smile CDR Docker container with the JVMARGS setting determined by an external file (jvmargs.env in the example below):

docker run --rm -d --env-file=./jvmargs.env -p 8000:8000 -p 8001:8001 -p 9000:9000 -p 9100:9100 -p 9200:9200 -p 9201:9201 -v smilecdr_log:/home/smile/smilecdr/log -v smilecdr_db:/home/smile/smilecdr/database -v smilecdr_mq:/home/smile/smilecdr/activemq-data --name smilecdr smilecdr

3.1.5Configuring Databases for Smile CDR Installed in Container

 

When configuring a database that requires a URL with a hostname such as PostgreSQL or MySQL, the hostname "localhost" will not be recognized by Smile CDR implementations running in a Docker container. Instead, you will need to specify one of the following:

  • If deploying on a Windows or OSX server, use host.docker.internal in place of "localhost".
  • If deploying on a Linux server, use the actual IP address of the server hosting the database. Note that for this to work, you will need to first ensure that the database is configured to listen for connections on the server's IP address. For example, in PostgreSQL it may be necessary to add an entry for the IP address in the pg_hba.conf configuration file.

An alternative approach is to install both Smile CDR and the database in a Docker stack. See this page for an example of how this could be done.