Alternative: Docker

This section describes how to install the FRED Local product using a Docker image, and running an initial FRED model to verify the installation.

Note

This documentation assumes use of the bash shell for Linux / macOS environments; use of another shell is expected to be compatible but may require slight modifications to the commands shown in this document.

Warning

While this documentation provides instructions for running the Docker image on a Windows environment, Epistemix does not recommend using FRED in a Windows environment. Instead, we recommend setting up Ubuntu for Windows per the instructions at https://ubuntu.com/wsl.

The FRED Docker image is based on the Ubuntu Linux LTS (Long Term Support) distribution. This image is known to run properly on macOS, Ubuntu Linux, and Microsoft Windows 10 with WSL 2 (The Windows Subsystem for Linux). Other host operating systems may be viable, though they have not been tested and are not recommended or supported by Epistemix at this time.

Preparing to Install

requirements

Before you install the FRED Local with Docker solution, please review the installation requirements. These instructions require users install:

You should also have been granted a username and password (known in AWS parlance as a client ID and client secret) to access the Epistemix Container Registry. Please contact Epistemix customer service if you need these credentials.

create FRED directories

It is useful to have a local fred directory to serve as the root of your working area for FRED. Under this directory we recommend creating the following directories. It is not technically required to organize your directories in this manner, though this document will assume you have done so in the examples and discussion.

The following illustrates how to create these directories from a shell / command-line:

$ cd $HOME
$ mkdir fred
$ mkdir fred/results
$ mkdir fred/models
$ mkdir fred/data

configuring FRED_HOME

It is also useful to create a local environment variable FRED_HOME that points to the location of your fred directory. We will assume this environment variable exists in our examples and discussions. It is suggested but not required that you make this environment variable “permanent” via mechanisms appropriate to your operating system (such as modifying your .bashrc file).

$ FRED_HOME=$HOME/fred
$ cd $FRED_HOME

Installing FRED

download the FRED Docker image

Start a terminal or command window and log in to the Epistemix container repository, 335566905560.dkr.ecr.us-east-1.amazonaws.com, using the aws configure and aws ecr get-login-password commands and piping results to docker login. You will be prompted for your AWS Access Key ID and AWS Secret Access Key. Replace the placeholders below with the values provided to you by Epistemix.

$ aws configure
AWS Access Key ID [None]: YOUR_KEY_ID_PROVIDED_BY_EPISTEMIX
AWS Secret Access Key [None]: YOUR_SECRET_ACCESS_KEY_PROVIDED_BY_EPISTEMIX
Default region name [None]: us-east-1
Default output format [None]:

$ aws ecr get-login-password --region us-east-1 | docker login --username AWS \
--password-stdin 335566905560.dkr.ecr.us-east-1.amazonaws.com
Login Succeeded

Once you are logged in, retrieve the latest FRED image from the repository using docker pull. This will make the image available locally. The example output below will likely differ from what you see as it depends on the specific version of the Docker image.

$ docker pull 335566905560.dkr.ecr.us-east-1.amazonaws.com/fred-local
Using default tag: latest
latest: Pulling from fred-local
f08d8e2a3ba1: Pull complete
3baa9cb2483b: Pull complete
94e5ff4c0b15: Pull complete
1860925334f9: Pull complete
123eba5a6d56: Pull complete
81d2ef2d3de4: Pull complete
f838d164515f: Pull complete
51261d5cb74a: Pull complete
cfbbb1179df2: Pull complete
588ede05e9b6: Pull complete
1bd07ab3b240: Pull complete
cd198a91dc5a: Pull complete
Digest: sha256:23c959bb1471d8ba734b3e864d5da0de7e5cdd2272c9f0e48d817d7f2a639108
Status: Downloaded image for 335566905560.dkr.ecr.us-east-1.amazonaws.com/fred-local:latest
335566905560.dkr.ecr.us-east-1.amazonaws.com/fred-local:latest

optional: download model tutorials

Epistemix provides a public tutorials repository with a collection of models that demonstrate essential features of the FRED Modeling Language. The documentation for these models is part of the Epistemix Documentation, and you can download this repository from GitHub.

$ cd $FRED_HOME/models
$ git clone https://github.com/Epistemix-com/FRED-tutorials.git
Cloning into 'FRED-tutorials'...
remote: Enumerating objects: 300, done.
remote: Counting objects: 100% (300/300), done.
remote: Compressing objects: 100% (175/175), done.
remote: Total 300 (delta 176), reused 231 (delta 120), pack-reused 0
Receiving objects: 100% (300/300), 2.14 MiB | 6.32 MiB/s, done.
Resolving deltas: 100% (176/176), done.

Verifying the Installation

run the FRED Local container

With the image available and directories configured, you can now run the FRED Docker image in a container. The following command establishes a local container with the data, results, and models directories accessible within the model.

$ docker run -dit -v "$FRED_HOME"/data:/fred/data \
-v "$FRED_HOME"/results:/fred/results \
-v "$FRED_HOME"/models:/fred/models \
--name fred 335566905560.dkr.ecr.us-east-1.amazonaws.com/fred-local

Note

These instructions use the environmental variable FRED_HOME created in a prior section.

Note

Should you need to redo these commands for any reason, you will have to stop your running container (if it’s running) and possibly remove and rebuild the docker image. This can be accomplished with docker stop fred and docker rm fred commands, respectively. Please see the Docker documentation for more details.

verify container configuration

Once the container has finished start-up activities, verify that the container is properly configured for FRED modeling with the following command.

$ docker exec -it fred fred_verify_container_configuration
No issues found! Container configuration verified!

If a problem is found, an error message will appear instead.

run a sample model

Now that the FRED Docker container is running and verified, you can run a sample model using the tutorials optionally downloaded earlier.

Note

Running a sample model will access the synthetic population optionally downloaded in the previous section.

You can execute the sample model in the FRED-tutorials directory. This was mounted in the container as the /fred/models directory, and the container’s current working directory should be this location as well.

You will see a few models in the directory. While any of these can be used, in our example we will use the model in the simpleflu directory, which simulates a simple influenza strain in Jefferson Country, Pennsylvania.

By convention, the core FRED program file for a model is called main.fred and a sample run script file to test the model is called METHODS. The following command executes the METHODS script found in the FRED-tutorials/simpleflu directory within the container. A successful output is shown.

$ docker exec -it fred /bin/bash -c "cd /fred/models/FRED-tutorials/simpleflu && ./METHODS"

fred_job: starting job simpleflu at Wed Mar 10 15:47:35 GMT 2021

fred_compile -p main.fred
No errors found.
No warnings.

fred_job: running job simpleflu id 55 run 1 ...
fred_job: running job simpleflu id 55 run 2 ...
run_set 0 completed at Wed Mar 10 15:47:37 GMT 2021

fred_job: running job simpleflu id 55 run 3 ...
fred_job: running job simpleflu id 55 run 4 ...
run_set 1 completed at Wed Mar 10 15:47:39 GMT 2021

fred_job: finished job simpleflu 55 at Wed Mar 10 15:47:40 GMT 2021

fred_plot: image_file = daily.pdf
fred_plot: image_file = weekly.pdf

If you run this command more than once, you will see a call to fred_delete in the output as well, which deletes the output from the prior run. This output is not shown here.

The METHODS file calls fred_plot, which creates an image of the results as a PDF file. This and other tutorials are discussed in the FRED Language Tutorials available on the Epistemix Documentation site. Here, the PDF files daily.pdf and weekly.pdf are created in your model directory. You can display these by opening the PDF files directly or in the viewer of your choice to see the results of this simulation.

$ cd $FRED_HOME/models/FRED-tutorials/simpleflu
$ open daily.pdf
$ open weekly.pdf

Direct Shell Access with Docker

Running a model in Docker works well, and you can certainly use this approach to run your own models. Another approach for Docker is to run a shell directly in the container and use FRED commands more directly. This section walks through how to run the sample model using this other approach.

You should have a FRED Local container already running called fred. Run a shell script with the following commands:

$ docker exec -it fred /bin/bash
[email protected]:/fred/models# pwd
/fred/models

After this command, you are running directly in the Docker container, so the instructions are identical regardless of the underlying platform. The Docker container provides an Ubuntu environment, so this works much like the local installation on Ubuntu discussed in local installation instructions.

Note

Your actual shell prompt within the Docker container will vary since it includes a portion of the container identifier. The Docker prompt will look something like root@a48b40b88a53:/fred/models#. We will continue to use a simple dollar sign $ in our examples.

You can now run FRED Simulation Information Management System (SIMS) commands directly, as described in the FRED SIMS documentation.

As we showed in previous sections, you can invoke the METHODS script here. In this example, execute the SIMS commands listed in the METHODS script directly.

$ cd FRED-tutorials/simpleflu/

$ fred_delete -f -k simpleflu
fred_delete: KEY = simpleflu  JOB = 129
fred_delete: /fred/results/JOB/129 deleted

$ fred_job -k simpleflu -p main.fred -n 4 -m 2

fred_job: starting job simpleflu at Mon May  3 14:33:06 GMT 2021

fred_compile -p main.fred
No errors found.
No warnings.

fred_job: running job simpleflu id 130 run 1 ...
fred_job: running job simpleflu id 130 run 2 ...
run_set 0 completed at Mon May  3 14:33:09 GMT 2021

fred_job: running job simpleflu id 130 run 3 ...
fred_job: running job simpleflu id 130 run 4 ...
run_set 1 completed at Mon May  3 14:33:12 GMT 2021

fred_job: finished job simpleflu 130 at Mon May  3 14:33:13 GMT 2021

$ fred_plot -o weekly -k simpleflu -v INFLUENZA.newExposed -b \
-t "Simple Flu Model" -l "Weekly Incidence" -d 0 -w --clean
fred_plot: image_file = weekly.pdf

Using the shell directly is often easier than invoking commands externally. For more information on the FRED command-line tools, see the document FRED Simulation Information Management Guide available on the Epistemix Documentation site.

Next Steps

At this point, your FRED Local with Docker installation is complete, verified, and ready! As a next step, new FRED users may want to review more of FRED platform and language documentation on the Epistemix Documentation site.