Smile Guide: Installing Smile CDR

II. Background

Smile CDR is an innovative, secure, flexible and fast clinical data repository that enables interoperability within an organization’s health systems. Smile is powered by HAPI-FHIR which is an open source FHIR server that was built to the HL7 FHIR standard. Learn more about HAPI-FHIR here. With Smile CDR, your valuable data is stored in the (open) FHIR format in a database you control—there’s never any vendor lock-in. Smile CDR offers a number of advanced features—from integrated consent and identity services to MDM and FHIR Gateways. In this document, we’ll focus on the absolute basics; installing and using Smile CDR for the first time.

To explore Smile CDR’s rich feature set, please visit our extensive platform documentation. Visit our website to understand how Smile CDR’s modular design can be customized to address various use cases.

III. Objective

The intent of this document is to provide a step-by-step guide to installing Smile CDR on your Mac or Windows computer. You should be able to successfully complete the installation with little to no technical background. There are various applications you will need to have installed prior to and after installing Smile CDR. A step-by-step guide to installing these ancillary applications is in the prerequisites and next steps sections of this document.

IV. Prerequisites

Smile CDR can be installed and configured in minutes. It is not necessary to have development experience to install the Smile CDR application, however, the following items are required:

1. A fundamental understanding of how to operate within MacOS or Windows (for example, if you are a Mac user, you should be familiar with the Finder application and how to access various folders within your computer). If you are new to either of these operating systems, the following videos will provide an introduction to using MacOS and Windows:
   
   

   1. Mac OS - introduction
      
      

   2. Windows -introduction
      
      

2. An understanding of your system requirements.

    

If you're a Windows user, please take note of the following system requirements:

1. You'll need at least 1GB of disk space available to install all necessary software.
   
   

2. You'll need a 64-bit operating system. To check if your system is such:
   
   

1. 1. Select the “Start” button, which has the Windows logo.
      
      

   2. Select the “Settings” gear.
      
      

   3. Select the “System” option.
      
      

   4. Select “About” at the bottom of the left-hand side.
      
      

   5. Check the “System Type” and ensure that it shows “64-bit operating system”.
      

      If it shows 32-bit, stop; you cannot install Smile CDR on your Windows system.
      
      

2. You'll need to install Docker prior to installing Smile CDR. For detailed instructions on how to do so, please see the following Docker installation document.
   
   

3. Note: you'll need administrative rights on your computer to download and install software. If you are using a corporate laptop you may need to speak to your IT administrator.

If you're a Mac user, please take note of the following system requirements:

You'll need roughly 1GB of disk space available to install all necessary software.

1. A basic understanding of your terminal (Mac) or Command Prompt (Windows) application. This is what you'll use to accomplish and automate tasks without the use of a graphical user interface. If you would like to educate yourself on these applications, see the following tutorials for Terminal and Command Prompt.
   
   

   1. As a Mac user, if you are following this document and would like to open your terminal:
      
      

      1. First click on the Launchpad desktop icon (see below):
         
         

         

1. 1. 1. Then, in the search bar at the top, type terminal, and click on the following application:
         
         

         

          

As a Windows user, if you're following this document and would like to open your command prompt:

1. First select “Start” or the Windows icon in the bottom left corner of your desktop.
   
   

2. In the search bar, type “cmd”
   
   

3. The Command Prompt application should appear, click on this application.
   
   

It's highly recommended that you install Java SE Development Kit (JDK) prior to Smile CDR. This is to avoid encountering a Java Runtime error. Please see the following document to install the JDK most compatible for your system. If you still manage to encounter a Java Runtime error after installing a JDK, please contact your Smile CDR Account Representative.

V. Installing Smile CDR: MacOS Installation

For a video tutorial on installing Smile CDR for MacOS, click here. 

Note: if you're a Mac user, you are able to install Smile CDR natively. However, you also have the option to install and run Smile from a container environment such as Docker. Should you prefer to do so, an instructional document on installing Docker can be found here. 

If you have a 2020 (or newer) Apple Mac computer (which uses the ARM M1 processor as opposed to the Intel x86 processor), it's highly recommended that you follow the instructions outlined in this document, which will guide you through installing the correct Java environment for your computer. 

1. Let’s download the most current version of Smile CDR. Navigate to the following URL: https://docker.smilecdr.com/downloads/
   
   

2. Once opened, a login prompt will appear, use the following:
   
   

   1. Username: <<use the one supplied to you by Smile CDR>>
      
      

   2. Password: <<use the one supplied to you by Smile CDR>>
      
      

3. Once logged in, the following screen should appear:
   
   

   

4. Click release/
   
   

5. A list of the most recent Smile CDR releases will appear. We recommend that you select the most recent one, which at the time of this writing is the September 1, 2021 release.
   
   

   

6. Click on the release that ends with tar.gz (Note: DO NOT select the release that ends with “docker.tar.gz”).
   
   

   

7. Once you have clicked on the correct release, Smile should begin downloading as shown below:
   
   

   
   

8. When the download is complete, click on it.
   
   

   1. Your Finder application will launch automatically and will have already selected the “Downloads” folder.
      
      

   2. In an effort to follow good housekeeping practices on your computer, it’s recommended that you move smilecdr out of your downloads folder and into your system’s local drive. To do this:
      
      

      1. Open your terminal application. Once open, it should look similar to the below image:
         
         

         
         

      2. Run the following command (copy and paste it into your terminal, then press enter):
         
         

         sudo mv ~/downloads/smilecdr /usr/local/smilecdr
         
         

         This will prompt you to enter your computer password. Do so, then press enter.
         
         

9. Now we will access the directory in which we can locate our Smile CDR instance. To do so, run the following command:
   
   

   cd /usr/local/smilecdr/bin
   
   

10. Time to start up our instance of Smile CDR! Lets run the following command:
    
    

    ./smilecdr start
    
    

    The following should appear:
    
    

    
    

11. Once you’ve hit enter, Smile CDR will begin running in your terminal. For someone who has never used their terminal before, this might look like hundreds of seemingly random lines of code typing themselves out. Don’t be alarmed!
    
    

12. Once Smile has finished starting up, the bottom of your terminal should read: “Smile, we’re up and running! :)”:
    
    

    
    

13. You’ve now downloaded and started up Smile CDR! To open and log into Smile CDR:
    
    

    1. Open a new Google Chrome tab.
       
       

    2. In the search bar, type localhost:9100 and hit enter
       
       

    3. The following login page should appear:
       
       

       

14. Click the green Sign In button and fill out the prompt page with the following information:
    
    

    1. Username: admin
       
       

    2. Password: password
       
       

15. Congratulations, you’re now running Smile CDR! Should you run into trouble, contact your Smile CDR Account Rep.
    
    

16. It’s advised that you stop your Smile CDR instance when you shut down your computer. If you want to stop your instance of Smile CDR, run the following command in your terminal:
    
    

    ./smilecdr stop
    
    The shutdown procedures will then begin. As soon as this has completed, your terminal will read “Shutdown has completed” (see below):
    
    

    

VI.  Installing Smile CDR: Windows Installation

It’s important to note that Smile CDR is an application that installs natively on Mac, but not so easily on Windows. You will need to download Docker, which is a container environment that allows us to replicate the software our application requires regardless of the operating system you are using! Smile CDR will run within Docker. 

Important update: Docker now requires licenses for their product. Before installing, please reach out to your organization for a Docker license. 

For a video tutorial on installing Smile CDR and Docker for Windows, click here. 

There are two approaches to installing Smile CDR on your Windows computer. The first approach is more detailed and mirrors the MacOS installation. The advantage to this is you will understand each step on a more fundamental level. The second approach is arguably faster, but involves a somewhat deeper familiarity with your command prompt and Docker should you run into any problems. Generally speaking, if you’re comfortable using your command prompt and have a more technical background, you should be able to follow Approach 2 without difficulty. If this isn’t the case, we advise you to follow Approach 1.

Approach 1

1. For a detailed guide on installing Docker, see the following document.
   
   

2. Let’s download the most current version of Smile CDR. Open the following link: https://docker.smilecdr.com/downloads/
   
   

3. Once opened, a login prompt will appear, use the following:
   
   

   1. Username: <<use the one supplied to you by Smile CDR>>
      
      

   2. Password: <<use the one supplied to you by Smile CDR>>
      
      

4. Once logged in, the following screen should appear:
   
   

   

5. Click release/
   
   

6. A list of the most recent Smile CDR releases will appear. We recommend that you select the most recent one, which at the time of this writing is the September 1, 2021 release.
   
   

   

7. Click on the release that ends with docker.tar.gz (Note: do not select the release that does not have “docker” in its name).
   
   

   

8. A zip file should then begin downloading. There’s no need to open this file quite yet, but note that it’ll appear later in your computer’s downloads folder.
   
   
   
   

9. Open your Command Prompt application, then follow these instructions to open Smile CDR:
   
   

   1. Run the following command (copy and paste it into your Command Prompt, then hit enter) to open the directory of your Smile CDR instance:
      
      

      cd downloads
      
      

   2. Run the following command to load Smile CDR as a Docker image:
      
      

      docker image load --input="smilecdr-2021.08.R03-docker.tar.gz"
      
      Note that the above command that consists of “2021.08.R03” is specific to the version of Smile CDR you choose to download. Make sure to keep this consistent with the name of the file you have selected in Step 7
      
      

   3. If you’ve followed instructions correctly, a Docker image should begin loading layers in your command prompt. Once finished, it should look like the image below.
      
      

      

   
   

   1. Run the following command to create a docker container for Smile CDR to operate within:
      
      

      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 smilecd
      
      

10. Now you can open your Docker application. You should see a container titled “smilecdr.” Hover over this row and select the play button.

     

    
    

11. After a few seconds, you’ll notice that the red box to the left of “smilecdr” will turn green.
    
    

    
    Note: even after the box next to “smilecdr” turns green, it might take a minute or two for Smile CDR to begin running. If you run into trouble with Step 12, it’s likely for this exact reason. Simply wait a few minutes before trying to proceed.
    
    

12. You’ve now downloaded Smile CDR! To open and log in:
    
    

    1. Open a new Google Chrome tab.
       
       

    2. In the search bar, type localhost:9100 and hit enter.
       
       

    3. The following login page should appear:
       
       

13. Click the green Sign In button and fill out the prompt page with the following information:
    
    

    1. Username: <<use the one supplied to you by Smile CDR>>.
       
       

    2. Password: <<use the one supplied to you by Smile CDR>>.
       
       

14. Congratulations, you’re now running Smile CDR! Should you run into trouble, contact your Smile CDR Account Rep.
    
    

15. If you would like to stop your Smile CDR instance from running, simply hover over the docker container and click on the stop button.

Approach 2

1. For a detailed guide on installing Docker, see the following document.
   
   

2. Now that Docker is installed, let’s download the most current version of Smile CDR!
   We’re first going to log into docker.smilecdr.com. To do so, open your command prompt, type the following command into your prompt, then hit enter:
   
   

   docker login docker.smilecdr.com
   
   

3. Fill out the prompt page with the following information (this sometimes takes a minute to authorize):
   
   

   1. Username: <<use the one supplied to you by Smile CDR>>
      
      

   2. Password: <<use the one supplied to you by Smile CDR>>
      
      

4. Now that you’ve successfully logged in, we will pull the most recently updated Docker images. To do so, paste the following command into your prompt, then hit enter:
   
   

   docker pull docker.smilecdr.com/smilecdr:latest
   
   

5. A Docker image should begin loading layers in your command prompt. Give your computer a few minutes to complete this process. Once finished, it should look somewhat like the image below.
   
   

   

6. Now that the Docker image has loaded, we have to create a container within the Docker application. To do so, paste the following command into your prompt and hit enter:
   
   

   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:latest
   
   

7. At this point, your command prompt will begin displaying various, seemingly meaningless lines of code. Give your computer a few minutes to complete this process. Once finished, your command prompt will looks something like the following and the last line will read: “Smile, we’re up and running :)” :
   
   

   
   
8.  

   

9. If the container is already running, then the box to the left will be green. If this box is red, this means that the container is not running. To run the container, hover over the area highlighted within the red box, then click on the play button.
   
   

   
   

10. You’ve now downloaded Smile CDR! To open and log in:
    
    

    1. Open a new Google Chrome tab
       
       

    2. In the search bar, type localhost:9100 and hit enter
       
       

    3. The following Login page should appear:
       
       

11. Click the green Sign In button and fill out the prompt page with the following information:
    
    

    1. Username: <<use the one supplied to you by Smile CDR>>
       
       

    2. Password: <<use the one supplied to you by Smile CDR>>
       
       

12. Congratulations, you’re now running Smile CDR! Should you run into trouble, contact your Smile CDR Account Rep.
    
    

13. If you would like to stop your Smile CDR instance from running, simply hover over the Docker container and click on the stop button.

VII. Next Steps

Tell us about your experience! Fill out this short survey to let us know if this document helped.

It’s recommended that you take some time to review the following documents to familiarize yourself with topics that will allow you to enhance your knowledge of the Smile CDR application and its capabilities:

1. SMART on FHIR—Useful for developing apps that access protected information with authorization.
   
   

2. RESTful API—Useful for understanding FHIR’s RESTful API and how to use it. 
   
   

3. Channel Import using Kafka—Navigating Smile CDR’s channel import functionality as a means of pushing data between systems in real-time. 

VII. Glossary

Command Prompt/Terminal:

This is what people use to accomplish and automate tasks without the use of a graphical user interface.

For example, rather than opening Microsoft Word by clicking on the little desktop app, I can open it from the command terminal by typing in some lines only my computer can really comprehend.

If you are a Windows user, learn more about your Command Prompt here. If you are a Mac user, learn more about your Terminal here.