# Desuto Platform
This Docker Compose configuration allows building and running a functional Desuto Web Viewer from scratch on any Docker-enabled host.

This README file aims to describe the structure of the containers and any possible configuration changes that may be required when setting up the system on a new host.

## Prerequisites
To run the platform, you will need to install at least:

* A recent version of Docker CE : https://docs.docker.com/install/linux/docker-ce/ubuntu/
* A recent version of Docker Compose : https://docs.docker.com/compose/install/

## Containers
The ``docker-compose.yml`` file is made up of the following containers:

1. **proxy** : Proxy facade for all services (based on nginx)
1. **couchdb** : CouchDB database for storing image annotation data from the Web Viewer
1. **webviewer** : Node.js server for the Web Viewer / Annotation tool
1. **iipsrv** : IIPImage server for generating the image tiles for the Web Viewer
1. **slideprops** :  Python Web Service for extracting slide properties (using Openslide)

## Ports
The following ports need to be open on the host machine to run all services correctly:
1. **80** : Port 80 is used by the proxy facade to expose all underlying services

## Environment variables
The following default environment variables should be declared in the ``.env`` file.  All current values assume that the server runs on ``localhost`` and all services are behind the **proxy** container. All these variables are injected in various configuration files required by Javascript and Node.js applications. 

If no special setup is required on the test host, you can simply copy the ".env.template" file to ".env" and replace the values in brackets (`COUCHDB_ADMIN_PASS` and `SLIDEVIEWERDATA_LOCAL_PATH`).

1. **COUCHDB_ADMIN_USER** : Username of the CouchDB administrator
1. **COUCHDB_ADMIN_PASS** : Password for the CouchDB administrator
1. **COUCHDB_DB_NAME** : Name of the database created for the Web Viewer annotation data
1. **COUCHDB_PROTOCOL** : Protocol used by CouchDB (http by default, https can be managed by the proxy)
1. **COUCHDB_PORT** : Default port to reach the CouchDB container (not exposed, but can be used internally by the other Docker containers)
1. **COUCHDB_HOST** : Hostname of the CouchDB server (public-facing, localhost by default)
1. **COUCHDB_ROOT_URL** : Public-facing URL of the CouchDB database
1. **COUCHDB_BACKEND_ROOT_URL** : Backend URL for the CouchDB database
1. **IIP_ROOT_URL** : Default URL of the IIP server
1. **SLIDEPROPS_ROOT_URL** : Default URL of the Slide Properties Web Service
1. **VIEWER_ROOT_URL** : Default URL of the Web Viewer
1. **SLIDEVIEWERDATA_LOCAL_PATH** : Default path of the data for the Web Viewer (uploaded images, converted images, overlays, etc.)

## Running the platform

### Set up the data folder
Before running the platform, you should set up the folder structure for the Web Viewer data. The data is organised with the following hierarchy:

```
root
|-- converted
    |-- Files converted automatically by the Web Viewer into the pyramidal, 
        Deep-Zoom-compatible TIFF format
|-- overlays
    |-- NAME_OF_UPLOADED_IMAGE.tif
        |-- feature-name.png
        |-- ...
|-- uploaded
    |-- WSI files uploaded via the Web Viewer interface   
```

The structure is fairly simple, only the "overlays" directory is a bit special. This folder must contain a subfolder for each WSI uploaded to the platform. 
Each of these subfolders may contain one or more PNG files representing an overlay for the WSI of that subfolder.

### Define the path in the ".env" file
Whether you created the folder structure above manually or received a sample ZIP file with some images, you need to map the folder into the Docker container by setting the `SLIDEVIEWERDATA_LOCAL_PATH` variable in your ".env" file.
Simply set it to the path of the folder you created:

```
# Linux example
SLIDEVIEWERDATA_LOCAL_PATH=/home/slideviewer/slideviewerdata/

# Windows example
SLIDEVIEWERDATA_LOCAL_PATH=C:/SlideViewerData/
```

Once this variable is defined, you should be able to correctly build and start all the containers.

### Starting the containers
To create/start/restart all containers (in background mode), type the following command in the terminal **from the folder containing the docker-compose.yml file**:

```
docker-compose up -d
```

To stop the containers, type:

```
docker-compose stop
```

To remove all the containers (clean-up), type:

```
docker-compose down
```

### Accessing the Web Viewer
Wait for about a minute, then access your browser at ``http://localhost`` to access the Web Viewer.

You can then log in with one of the following default user accounts defined in the ``docker-entrypoint.sh`` file in the ``desuto-couchdb`` directory:

* User : ``user``, Password : ``userpass`` (Read-only access)
* User : ``pathologist1``, Password : ``pathologistpass``
* User : ``pathologist2``, Password : ``pathologistpass``