Getting started¶

Getting started with SlideAtlas¶

This document describes setting up SlideAtlas on linux, in particular on ubuntu releases 12.04 and 14.04, but it should be easy to interpret these instructions for platforms as well.

Python, pip and subversion-tools required, they can be installed by using

$ sudo apt-get install subversion-tools python2.7 python-pip

Third party libraries¶

SlideAtlas depends on several third party softwares and expects them to be installed on the system.

ubunbu 14.04 lts¶

Required packages libtiff5-dev and openslide-tools are both available in ubuntu release 14.04

Install them using

$ sudo apt-get install openslide-tools libtiff5-dev

ubunbu 12.04 lts¶

Latest versions of libtiff and openslide must be compiled from source. Following packages are required for successful compilation

$ sudo apt-get install autoconf automake libtool pkg-config libgtk2.0-dev
$ sudo apt-get install libxml2-dev libjpeg-dev liblzma-dev liblz-dev zlib1g-dev lzma libmatio-dev
$ sudo apt-get install libexif-dev libfftw3-dev swig python-dev liborc-0.4-dev libsqlite3-dev

Building Libtiff4¶

wget ftp://ftp.remotesensing.org/pub/libtiff/tiff-4.0.3.tar.gz

tar xvzf tiff-4.0.3.tar.gz
cd tiff-4.0.3/
./configure
make
sudo make install

Building Openslide¶

git clone git://github.com/openslide/openslide.git
cd openslide
autoreconf -i
./configure
make
sudo make install

Warning

If any plugins are enabled, their dependencies should be installed accordingly. For more details see Plugins

Install python packages¶

Once third party libraries are installed on the system, the required python packages mentioned in requirements.txt can be installed with

$ sudo pip install -r requirements.txt

Note

none

Some more packages may be required at this stage

Building documentation¶

Detailed documentation can be built using sphinx

$ cd docs
$ make html

Testing¶

CMake is required for testing.

$ cd testing
$ ctest -S ctest_driver.cmake

Running SlideAtlas¶

$(export SLIDEATLAS_CONFIG_PATH=/home/dhan/projects/slideatlas-config-kitware/localhost/site_slideatlas.py ;  gunicorn -k flask_sockets.worker run_websockets:app -b localhost:8080 --log-level=debug)

To run without websockets support¶

Unless actively debugging, the fast way to run slide-atlas for serving tiles is to use gunicorn. This can start multiple workers.

$ EXPORT SLIDEATLAS_CONFIG_PATH=/path/to/site_config
$ gunicorn --reload run_gunicorn:app -b 0.0.0.0:8080 -w 4 --log-level=DEBUG

$ EXPORT SLIDEATLAS_CONFIG_PATH=/path/to/site_config
$ python run.py

$(export SLIDEATLAS_CONFIG_PATH=/home/dhan/projects/slideatlas-config-kitware/localhost/site_slideatlas.py ;  python run.py)

“/path/to/site_config” should be the absolute path to a configuration file with any locally-specific configuration changes.

If such a configuration file is not provided, SlideAtlas will use sensible defaults (e.g. connecting to a MongoDB at ‘localhost:8080’).

Sample Apache configuration¶

<VirtualHost admin.slide-atlas.org:80>
     ServerName admin.slide-atlas.org
     ServerAdmin dhanannjay.deo@kitware.com

     WSGIDaemonProcess slideatlas user=www-data group=www-data threads=1
     WSGIScriptAlias / /var/slideatlas-admin/run_apache.wsgi

     <Directory /var/slideatlas-admin>
         WSGIProcessGroup slideatlas
         WSGIApplicationGroup %{GLOBAL}
         Order deny,allow
         Allow from all
     </Directory>

      ErrorLog ${APACHE_LOG_DIR}/error.log

      # Possible values include: debug, info, notice, warn, error, crit,
      # alert, emerg.
      LogLevel warn

      CustomLog ${APACHE_LOG_DIR}/access.log combined

</VirtualHost>

Configuring SlideAtlas¶

During runtime, slidetlas looks for environment variable “SLIDEATLAS_CONFIG_PATH” and loads the configuration variables from the python file pointed by it. A sample configuration file “site_config.py” that overrides few settings is as follows -

# The MongoDB database name of the admin database.
SLIDEATLAS_ADMIN_DATABASE_NAME = 'my_slideatlas_admin_database'

#The password to authenticate to the admin database with, if any.
SLIDEATLAS_ADMIN_DATABASE_PASSWORD = "super_secret_password"

#The username to authenticate to the admin database with, if any.
SLIDEATLAS_ADMIN_DATABASE_USERNAME = "secret_username"

For example, when running from bash, location of this file should be stored in “SLIDEATLAS_CONFIG_PATH” as follows

$ export SLIDEATLAS_CONFIG_PATH="/home/projects/path_to_config/site_config.py"
$ python run.py

List of default configuration paramters for slideatlas are as follows -

slideatlas.default_config.APPLICATION_ROOT = None¶

The root of the application in the URL path. (None defaults to ‘/’)

If the application does not occupy a whole domain or subdomain this can be set to the path where the application is configured to live. This is for session cookie as path value. If domains are used, this should be None.

slideatlas.default_config.DEBUG = False¶: Enable Flask’s debug mode.

slideatlas.default_config.LOGIN_DISABLED = False¶: Disable login and role requirement access controls.

slideatlas.default_config.MAIL_DEBUG = False¶

Set the email debug output level.

A non-false value results in debug messages for connection and for all messages sent to and received from the SMTP server.

slideatlas.default_config.MAIL_MAX_EMAILS = None¶

The maximum number of emails to send before reconnecting.

Some mail servers set a limit on the number of emails sent in a single connection.

slideatlas.default_config.MAIL_PASSWORD = None¶: The password to authenticate to the SMTP server with.

slideatlas.default_config.MAIL_PORT = 25¶: The port to connect to the SMTP server with.

slideatlas.default_config.MAIL_SERVER = 'localhost'¶: The hostname of the SMTP server to send email via.

slideatlas.default_config.MAIL_SUPPRESS_SEND = False¶: Prevent emails from actually being sent.

slideatlas.default_config.MAIL_USERNAME = None¶: The user name to authenticate to the SMTP server with.

slideatlas.default_config.MAIL_USE_SSL = False¶: Connect to the SMTP server using SSL.

slideatlas.default_config.MAIL_USE_TLS = False¶: Connect to the SMTP server using TLS.

slideatlas.default_config.REMEMBER_COOKIE_NAME = 'remember_token'¶: The name of the remember user cookie.

slideatlas.default_config.SECRET_KEY = 'WRa/y5PVGdFNoaEfgoBENdUm9IYPs5DW'¶

A random value used for signing cookies and other cryptographic operations.

This should always be changed when setting up a production instance.

A simple cross-platform PRNG is to run the command:: python2 -c ‘import os; print repr(str(os.urandom(24)).encode(“base64”).rstrip())’

slideatlas.default_config.SECURITY_EMAIL_SENDER = 'no-reply@localhost'¶: The email address to send outgoing emails as.

slideatlas.default_config.SECURITY_PASSWORD_HASH = 'pbkdf2_sha512'¶

Specifies the password hash algorithm to use when encrypting user passwords.

Recommended values for production systems are ‘bcrypt’, ‘sha512_crypt’, or ‘pbkdf2_sha512’. ‘plaintext’ is also possible, but not recommended.

slideatlas.default_config.SECURITY_PASSWORD_SALT = '6IRWyQdC19raLaJf/Lm6gAfmMleXlO7i'¶

A random value, used as the salt when hashing passwords.

This does not apply if the password hash type is ‘plaintext’.

slideatlas.default_config.SERVER_NAME = None¶

The name and port number of the server.

Required for subdomain support (e.g.: ‘myapp.dev:5000’). Note that localhost does not support subdomains, so setting this to “localhost” does not help.

slideatlas.default_config.SESSION_COOKIE_NAME = 'session'¶: The name of the session cookie.

slideatlas.default_config.SLIDEATLAS_ADMIN_DATABASE_AUTH_DB = None¶: The database name to authenticate to the admin database with, if any.

slideatlas.default_config.SLIDEATLAS_ADMIN_DATABASE_HOST = 'localhost:27017'¶: The hostname and port of the MongoDB SlideAtlas admin database.

slideatlas.default_config.SLIDEATLAS_ADMIN_DATABASE_NAME = 'slideatlas'¶: The MongoDB database name of the admin database.

slideatlas.default_config.SLIDEATLAS_ADMIN_DATABASE_PASSWORD = None¶: The password to authenticate to the admin database with, if any.

slideatlas.default_config.SLIDEATLAS_ADMIN_DATABASE_REPLICA_SET = None¶: The name of the replica set for the admin database, if it is a member of one, or None otherwise.

slideatlas.default_config.SLIDEATLAS_ADMIN_DATABASE_USERNAME = None¶: The username to authenticate to the admin database with, if any.

slideatlas.default_config.SLIDEATLAS_ADMIN_EMAIL = 'no-reply@localhost'¶: The email address for SlideAtlas administrators, for sending application notifications.

slideatlas.default_config.SLIDEATLAS_ENABLED_PLUGINS = []¶: The list of SlideAtlas plugins to be enabled, empty list by default.

slideatlas.default_config.SLIDEATLAS_FACEBOOK_APP_ID = None¶: The Facebook App ID (OAuth client ID) used for Facebook user authentication.

slideatlas.default_config.SLIDEATLAS_FACEBOOK_APP_SECRET = None¶: The Facebook App secret (OAuth client secret) used for Facebook user authentication.

slideatlas.default_config.SLIDEATLAS_GOOGLE_APP_ID = None¶: The Google App ID (OAuth client ID) used for Google user authentication.

slideatlas.default_config.SLIDEATLAS_GOOGLE_APP_SECRET = None¶: The Google App secret (OAuth client secret) used for Google user authentication.

slideatlas.default_config.SLIDEATLAS_HTTPS = False¶: Whether the app is being served over HTTPS.

slideatlas.default_config.SLIDEATLAS_LINKEDIN_APP_ID = None¶: The LinkedIn App ID (OAuth client ID) used for LinkedIn user authentication.

slideatlas.default_config.SLIDEATLAS_LINKEDIN_APP_SECRET = None¶: The LinkedIn App secret (OAuth client secret) used for LinkedIn user authentication.

slideatlas.default_config.SLIDEATLAS_LOG_PATH = '/tmp/slideatlas'¶: Path to a directory where log files will be written.

slideatlas.default_config.SLIDEATLAS_SHIBBOLETH = False¶: Whether Shibboleth login is available.

slideatlas.default_config.TESTING = False¶: Enable Flask’s testing mode.

slideatlas.default_config.TRAP_HTTP_EXCEPTIONS = False¶: If this is set to True Flask will not execute the error handlers of HTTP exceptions but instead treat the exception like any other and bubble it through the exception stack.