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). We have built a Docker image containing the latest version of Giotto Analyzer and Giotto Viewer.

1.1. Download the image docker-giotto-4.3.7z (~859 MB)
Unzip the 7zip image file.
Linux:
7z e docker-giotto-4.3.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).

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-4.3 giotto-4.3
$ docker images
REPOSITORY                TAG                 IMAGE ID            CREATED             SIZE
giotto-4.3                latest              1ccabdc0bc43        21 hours ago        3.67GB

1.2. Testing the image
$ docker run --name giotto-test -it giotto-4.3 /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
> 
Exit R.
> 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-4.3                "/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.

$ docker run -it --user dean --name giotto-4.3 -p 8000:8000 -p 8787:8787 -v c:\cygwin64\home\berna_000\workspace:/data giotto-4.3 /bin/bash
Done! Here, port 8000 is mapped to 8000 on host. Port 8787 (used for RStudio environment) is also linked. The host directory c:\cygwin64\home\berna_000\workspace is shared and mounted in /data within the docker image. The name of the docker container is called giotto-4.3. 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-4.3.
The shared directory is c:\cygwin64\home\berna_000\workspace. 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
You may be prompted to enter dean's sudo password. The password is dean.

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")
The next step is follow along the Giotto vignettes and the Giotto Viewer tutorial.

1.5. 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-4.3
docker attach giotto-4.3