Install and Update

Install and Update

The shiny-server project is composed by four different docker containers:

• db: a MySQL database which stores information about users credentials
• shiny: a rocker/shiny based images with few dependencies installed to render shiny applications
• uwsgi: a Django base image which implements views and authentication system
• nginx: used as a proxy to connect shiny and uwsgi backends. A special configuration location lets to provide shiny contents to authenticated users

Each container in manage in its own directory. Moreover, there are mysql-data and shiny-apps folder which are data folder not tracked in git. The nginx-conf.d folder contains the NgINX configuration file required to serve applications and provides authentication to shiny server relying on Django and NgINX itself

Configure and install shiny server

Install docker and docker-compose

All this stuff works inside a docker compose image and need docker and docker-compose to work. Please refer to the official documentation on how to install docker and docker-compose

Setting up the environment file

docker-compose can read environment variables from a .env placed in the working directory in which we can define all variables useful for our containers, like database credentials. Edit a new .env file in working directory and set values for such environment variables accordingly:

MYSQL_ROOT_PASSWORD=<root_password>
SHINY_DATABASE=<shiny_db>
SHINY_USER=<shiny_user>
SHINY_PASSWORD=<shiny_password>

TODO: manage sensitive data using secret in docker-compose, as described here and here

Preparing the database

All information needed to instantiate database are defined in docker-entrypoint-initdb.d directory. Database will be generated and then all the scripts placed in docker-entrypoint-initdb.d directory are executed. Ensure that mysql-data directory is not present, if not this part of the configuration cannot be executed.

NOTE: the entire system (three containers managed by Docker Compose) uses two shared volumes for ensuring the existance of persistent data: on the host the two directories are named mysql-data/ and django-data/. The django-data directory, containing the entire django environment and codes, is tracked in git while mysql-data not. When instantiated for the first time, mysql-data is generated and the database is initialized. After that, every instance of mysql will use the mysql-data directory, mantaing already generate data. If you plan to move shiny-server, you have to move all shiny-server directory with all its content

Download the latest image binaries

Shiny-server docker images are pre-builded and loaded in hub.docker.com. Download the latest image version using:

$ docker-compose pull

Build the docker-compose suite

In order to build the images according to the docker-compose.yml specifications, Docker needs download and install all required dependencies; it will need several minutes to complete. Launch this command from the working directory:

$ docker-compose build

Django configuration

Django configuration relies on a settings.py module, which loads sensitive data like password and SECRET_KEY from the same .env file in the project directory through the python decouple module. You need to define new environment variables for uwsgi container:

You need to define a new django SECRET_KEY. Start a python terminal with docker:

$ docker-compose run --rm --no-deps uwsgi python

then execute this python code, as described here:

>>> from django.utils.crypto import get_random_string
>>> chars = 'abcdefghijklmnopqrstuvwxyz0123456789!@#$%^&*(-_=+)'
>>> get_random_string(50, chars)

Copy the resulting key and the add into the previous .env file like this:

SECRET_KEY=<your SECRET_KEY>
DEBUG=False

You need also to configure additional environment variables in order that authentication staff can works as expected by sending mail to user if they forget their passwords:

ADMINS=<admin name1>:<admin email>
DEFAULT_FROM_EMAIL=<your email from>
EMAIL_BACKEND=django.core.mail.backends.smtp.EmailBackend
EMAIL_HOST=<your stmp server>
EMAIL_HOST_PASSWORD=<your smtp password>
EMAIL_HOST_USER=<your smtp password>
EMAIL_PORT=<your email port address>
EMAIL_USE_TLS=<set 'True' to use TLS, false otherwise

Please refere to django documentation for ADMIN and SMTP backend

Fixing django permissions

You will also to check file permissions in django data, expecially for media folder:

$ docker-compose run --rm uwsgi sh -c 'chmod -R g+rw media && chmod g+rwx media/thumbnails/'
$ docker-compose run --rm uwsgi sh -c 'chgrp -R www-data .'

Initialize Django tables

After inizialization, a new django user with administrative privilges is needed. This is not the default mysql user, but a user valid only in django environment. Moreover the django tables need to be defined:

$ docker-compose run --rm uwsgi python manage.py check
$ docker-compose run --rm uwsgi python manage.py migrate
$ docker-compose run --rm uwsgi python manage.py makemigrations
$ docker-compose run --rm uwsgi python manage.py migrate
$ docker-compose run --rm uwsgi python manage.py createsuperuser

The last commands will prompt for a user creation. This will be a new django admin user, not the database users described in env files. Track user credentials since those will be not stored in .env file in shiny-server directory.

Check everything works as expected

Test your fresh InjectTool installation with:

$ docker-compose run --rm uwsgi pytest

Start composed image

Pages are served by an nginx docker container controlled by Docker Compose (see the docker-compose.yml file content), which is linked to the shiny server and django instance. In order to start the application:

$ docker-compose up -d

The shiny-server interface is available for a local access through Internet browser at the URL: http://localhost:22080/.

Update the shiny-server application

You can updgrade the shiny-server application without loosing application data or user crendentials. Turn off the application and clean-up containers with:

$ docker-compose down

Inside the working directory. Then fetch and update the git repository:

$ git fetch
$ git pull

Next, update the docker compose images:

$ docker-compose pull

Test and apply changes on django database with

$ docker-compose run --rm uwsgi python manage.py check
$ docker-compose run --rm uwsgi python manage.py migrate
$ docker-compose run --rm uwsgi python manage.py makemigrations
$ docker-compose run --rm uwsgi python manage.py migrate

Finally restart the application with

$ docker-compose up -d