SITS Docker Images

This is the official repository of Docker images for the SITS R package. In this repository, you can find the recipes to build RStudio-based and Jupyter-based environments to use the SITS package.

Available images

The composable images approach was adopted in this repository to facilitate the construction of SITS-enabled environments that allow the full use of the SITS package features. In this approach, following a hierarchical structure, the installations and configurations are done at different levels. The lower level provides the base capabilities and resources for the higher level images. Because of this, the relationship of these images generates a tree of dependencies, which is presented below.

In total, five images are available, with the following responsibilities:

• SITS Base: Provides the base resources for building an R environment to allow the use of the SITS package (e.g., OS libraries for compiling geospatial dependencies, resources for using LaTeX, etc);
• SITS R: Provides an environment with R installed along with all the libraries and dependencies needed to use SITS (e.g., gdal, terra, sf). It does not include the SITS package;
• SITS: Provides installation of the SITS package;
• SITS Rstudio: RStudio environment with SITS-enabled;
• SITS Jupyter: Jupyter Notebook environment with SITS-enabled. It also provides access to an RStudio Server.

If you want to get started, see below for a step-by-step guide to using the RStudio and Jupyter Notebook images that are ready to use and are available on DockerHub. However, you can also build these images on your machine if you prefer. To do this, see the Building the Docker Image section.

Using the SITS R Package with RStudio

To use the RStudio environment with SITS-enabled, you can run a container from the brazildatacube/sits-rstudio:1.4.1 image, which is made available on DockerHub. For this, the following command can be used:

docker run --detach \
           --publish 127.0.0.1:8787:8787 \
           --name my-sits-rstudio \
           brazildatacube/sits-rstudio:1.4.1

Then, open the URL http://127.0.0.1:8787 in a web browser:

firefox http://127.0.0.1:8787

To login use sits as user and password.

Using the SITS R Package with Jupyter Notebook

In this image, its available the Jupyter Notebook environment together with RStudio.

To use the Jupyter Notebook environment with SITS-enabled, you can run a container from the brazildatacube/sits-jupyter:1.4.1 image, which is made available on DockerHub. For this, the following command can be used:

docker run --detach \
           --publish 127.0.0.1:8888:8888 \
           --name my-sits-jupyter \
           brazildatacube/sits-jupyter:1.4.1

After running the above command, it is necessary to recover the Jupyter access token. To do this, use the command below:

docker exec -it my-sits-jupyter jupyter lab list

The Jupyter server should respond with a message that looks like this:

Currently running servers:
http://cea9535dd267:8888/?token=d8817e283ad216ef1d920bb5cdd125a1cd104c4374df20bf :: /home/sits

Use the access token shown on your server output to access the Jupyter environment in your browser at the local address of the host machine. Example:

firefox http://127.0.0.1:8888/?token=d8817e283ad216ef1d920bb5cdd125a1cd104c4374df20bf

Building the Docker Images

To build the images with the Dockerfiles contained in this repository, it is possible to use the build.sh utility script. This script presents options for the customization of the images generated for the use of the SITS package. The script has the following options that can be used to customize the generated images:

• -n: Build with --no-cache flag (Default uses pre-built image cache).
• -t: SITS Tag version used in generated image (Default is 1.4.1).
• -p: Image name prefix (Default is bdc).
• -e: SITS environment type (full or minimal. Default is full).
• -h: show a help message.

Below is an example of using the utility script. The tag name defined for the SITS image is 1.4.1.

./build.sh -n -p brazildatacube -t 1.4.1

The above command will create the following images:

docker image ls | grep sits

brazildatacube/sits-jupyter   1.4.1     c84b566b3919   7 days ago          9.82GB
brazildatacube/sits-rstudio   1.4.1     1a5bfbfb0493   7 days ago          9.56GB
brazildatacube/sits           1.4.1     e5a8029eb6c1   7 days ago          8.75GB
brazildatacube/sits-r         1.4.1     f6d54ebcb385   7 days ago          6.2GB
brazildatacube/sits-base      1.4.1     2ef474f5c2fa   7 days ago          3.57GB