Installation


1. Docker image (cross-platform)

Docker image is the fastest way to test-drive Giotto or to deploy Giotto on your machine. You can skip all the installation instructions and start using Giotto right away. The Docker image is compatible with all environments where Docker can be installed (that means Windows, macOS, Linux). See more information about the benefit of Docker and performance of Docker. We have built a Docker image containing the latest version of Giotto Analyzer and Giotto Viewer.

1.0. Install Docker Desktop
Go to the official link to download and install Docker Desktop. Installation instructions and help manual can be found here for Windows, macOS, and Linux. After installation, there is no need to open Docker Desktop. The next few steps of tutorial uses the docker command-line utility, not the GUI interface.
Verify that the Docker daemon is started. To check the running status, click on the docker icon on the task bar.

1.1. Download the image docker-giotto-1.0.2.7z (~1111 MB)
Unzip the 7zip image file.
Linux: 
$ 7z e docker-giotto-1.0.2.7z
Windows 10: Please use the 7-Zip File Manager to extract the image 7zip file.
macOS: Please use the app Keka - the free Mac OS X file archiver (link). Do not double-click on the 7zip file or use the standard Archiver App that comes with macOS to extract the image. It will not work.
The extracted file, named docker-giotto-1.0.2 in the same directory, should be around 4GB.

1.2. Import image
Open a shell/command line/terminal.
Windows 10: the Windows PowerShell is a very useful terminal for this purpose. In the bottom left of the horizontal launch bar, click on Search icon, and enter "PowerShell". Select Windows PowerShell app to launch it.
In macOS, it is called Terminal App.
Once in the terminal, do the following: 
$ cd ~/Downloads #directory containing uncompressed image
$ docker import docker-giotto-1.0.2 giotto-1.0.2
$ docker images
REPOSITORY                TAG                 IMAGE ID            CREATED             SIZE
giotto-1.0.2              latest              1ccabdc0bc43        21 hours ago        4.00GB

1.2. Testing the image
$ docker run --name giotto-test -it giotto-1.0.2 /bin/bash
root@5d05178a3efe:/#
What happened was that docker has created a container for this image (a container is an instance of image). The container name is giotto-test.
Now test if giotto library can be loaded 
root@5d05178a3efe:/# R
R version 3.6.0 (2019-04-26) -- "Planting of a Tree"
...
> library(Giotto)
Loading required package: data.table
data.table 1.12.8 using 4 threads (see ?getDTthreads).  Latest news: r-datatable.com
Loading required package: ggplot2
> quit() #exit R
Exit the docker container. 
root@5d05178a3efe:/# exit    #exit the container
The status of the container should be changed to exited: 
$ docker ps -a
CONTAINER ID        IMAGE                     COMMAND             CREATED             STATUS                         PORTS               NAMES
5d05178a3efe        giotto-1.0.2              "/bin/bash"         52 seconds ago      Exited (0) 26 seconds ago                          giotto-test
Note that this container preserves all the changes (files, etc) after exiting. Next time you start "docker run -it" it will create a new container of a different name. So, let's delete the container with the following command, so that we can start image properly (note that the container name is indicated in the last column (NAMES)). 
$ docker rm giotto-test

1.3. Real Run
Start using Giotto. Requirements:
- We need to open the port 8000 and link it to host (for Giotto Viewer).
- We need to open the port 8787 and link it to host (for RStudio).
- We need to define a volume on host to share with the docker image, so that changes made within docker will persist after exiting docker. Host volume that's shared with docker will allow modifications.

Designate a directory to share with Docker
By default, the operating system in the Docker image cannot see files outside of Docker. We need to share a directory on the host system with docker. The shared directory should be a location to store the dataset, intermediary files and the results. To designate a host directory for sharing, we use the "-v" parameter of docker run command: -v <host_path>:<docker_path>. This means that the host_path will be shared and mounted as docker_path in the docker image. Both paths must be absolute paths.
  • host_path:
    The host_path specification is host system-dependent. For example, on Windows, the host_path can be c:\Users\Qian\Downloads\workspace. On macOS, it may be /Users/qzhu/Downloads. On Linux, it may be /home/qzhu/Downloads. These are examples only. Users should change this to what they want to share.
  • docker_path:
    For docker_path, set it to /data and do not change this.
  • Important note
    Only absolute paths must be used. For example here are some correct examples:
    • -v /home/qzhu/Downloads:/data
    • -v c:\Users\Qian\Downloads\workspace:/data
    Here are some bad examples to avoid:
    • -v Downloads:/data. Does not work. Not absolute path.
    • -v ~/Downloads:/data. Does not work. Not absolute path.
    • -v ../Downloads:/data. Does not work. Not absolute path.
    Space in the path?
    • Enclose both paths in one-set of quotation marks, like this: -v "a:b", not this -v "a":"b".
    • Example: -v "c:\Users\Qian Zhu\Downloads:/data"
    • Example: -v "/Users/Ruben Dries/Downloads:/data"
Putting everything together
Windows
$ docker run -it --user dean --name giotto-1.0.2 -p 8000:8000 -p 8787:8787 -v "c:\Users\Qian Zhu\Downloads:/data" giotto-1.0.2 /bin/bash
Where c:\Users\Qian Zhu\Downloads is the directory to share with Docker (should be changed). /data is mapped directory in Docker. Use absolute path for both. Space in the path? See here.

Linux
$ docker run -it --user dean --name giotto-1.0.2 -p 8000:8000 -p 8787:8787 -v /home/qzhu/Downloads:/data giotto-1.0.2 /bin/bash
Please change the host directory /home/qzhu/Downloads to what you want to share. Use absolute path. It will be shared and mounted in /data in Docker. Space in the path? See here.

macOS X
$ docker run -it --user dean --name giotto-1.0.2 -p 8000:8000 -p 8787:8787 -v /Users/qzhu/Downloads:/data giotto-1.0.2 /bin/bash
Please change the host directory /Users/qzhu/Downloads to what you want to share. Use absolute path. It will be shared and mounted in /data in Docker. Space in the path? See here.

Command explanation
Here, port 8000 is mapped to 8000 on host. Port 8787 (used for RStudio environment) is also linked. The -v specifies the sharing of directory between host and guest system (i.e. Docker). The name of the docker container is called giotto-1.0.2. The user that will log in once in container is called dean.


Upon entering the above command, you should see the following prompt: 

dean@e527827b2943:/$

Optional: if something wrong happened with the above command, it is possible that it is just a warning and Docker created an container anyway. If this is the case and you want to correct the error in the command, be sure to remove the container created by mistake. docker rm giotto-1.0.2.
The shared directory is /data in the Docker image. It is the work directory, and directory where you can store your spatial dataset to be processed in Docker giotto.

1.4. RStudio start up
We recommend working in RStudio so you can have all the benefits of the R environment. Once in docker, restart rstudio server in case it is not: 
dean@e527827b2943:/$ sudo rstudio-server restart
[sudo] password for dean: 
 * Restarting RStudio Server rserver [ OK ] 
rsession: no process found
You may be prompted to enter dean's sudo password. The password is dean. The warning rsession: no process found can be safely ignored.

Then open a browser and enter http://localhost:8787. You should be greeted with a RStudio welcome screen. Enter username: dean, password: dean. Then you have entered R environment.
In RStudio R prompt, set the working directory to /data: 
> setwd("/data")

2. Optional: Docker resource allocation

You can use Docker Desktop to configure how much resource (CPU and memory) you want the Docker container to use.
  • See the user manual for Windows, and this user manual for macOS. Read the "Resources" section of the manual.
  • By default, Docker imposes a limit of half of available CPU cores and 2GB of physical memory. This may not be desirable for using Giotto on large datasets. So you will need to change this default setting.
  • For Windows system, if your Docker uses the WSL2 backend mode rather than Hyper-V, the resource configuration is outside of Docker Desktop app. See this link to use resource limits in WSL2, or this link to reclaim cached memory in WSL2.
  • For Linux system, there is no limit on how much CPU and memory that the Docker container can use.

3. First time Docker usage

It is important to check out the first time Docker usage information. This is important when you follow the dataset examples on this website.

Remember: input files should be put in the host directory that is shared with docker (i.e. -v parameter you specified in docker run -it). Set the working directory to /data in docker so that files (input and results) can be shared between host and docker. See "Communicate files between Docker and host: where to find results". Also note other things for Giotto Analyzer, and Giotto Viewer.
After reading the first time page, the next step is follow along the Giotto vignettes such as the dataset examples.

4. Finishing and restarting

When you are finished, you can exit the container. Note that after exiting, the changes (files, etc) will persist into the container. There is no need to delete the container if you plan to use the same container in future. To start an existing container in future, do the following: 
$ docker start giotto-1.0.2
$ docker attach giotto-1.0.2
#remember to restart rstudio-server upon restarting the Docker container
dean@e527827b2943:/$ sudo rstudio-server restart