Xstudio Docker


Architecture

A whole instance of XStudio can be deployed using a docker-compose file that references the 3 official docker images that we provide ready-to-be-used in Docker Hub.


Docker images

Each of the three docker images can be fetched from Docker Hub the usual way with the following tags:
  • xqual/xstudio-mariadb:v88
  • xqual/xstudio-backup:v1
  • xqual/xstudio-tomcat:4.1sp3

The source Docker files and scripts used to generate these Docker images are provided in a separate package and are delivered as open-source here

xqual/xstudio-mariadb

This Docker image runs the database server (which is MariaDB a real open-source fork of MySQL)
The tag (i.e. "v88") represents the version of the database schema.
Please refer to the compatibility table below to use a version compatible with the xqual/xstudio-tomcat image's version.

The docker needs a few parameter to be customized with your own preferences:
Parameter Description Example
MYSQL_ROOT_PASSWORD Root password of the MariaDB database server rootpwd
MYSQL_DATABASE Name of the database that will host XStudio's data xstudiodb
MYSQL_USER Name of the MariaDB account that XStudio will use xstudio
MYSQL_PASSWORD Clear password of the MariaDB account that XStudio will use xstudiopwd


Based on the above example values, the image can be run individually in a container using the command:

docker run --name xstudio-mariadb-container --publish 3306:3306
-e MYSQL_ROOT_PASSWORD=rootpwd
-e MYSQL_DATABASE=xstudio_db
-e MYSQL_USER=xstudio
-e MYSQL_PASSWORD=xstudiopwd
xqual/xstudio-mariadb:v88


It is not really useful to run this container by itself though. You should use Docker-compose to run it as part as an integrated instance.
Please refer the section Run all the images in an integrated environment for more details.

xstudio-backup

This Docker image runs the backup operations of the database (operated by the xqual/xstudio-mariadb image)
The tag (i.e. "v1") just represents the version of the image and has no compatibility constraint with the other images.

This docker image can take optional parameters which are used only if you wish to transfer the latest backup once a week on a third-party FTP server.

The daily backups are create at 2am local time and stored locally in the /home/backup folder.
The weekly transfer to a third-party FTP server is executed at 3am local time (if configured).

The docker needs a few parameter to be customized with your own preferences:
Parameter Description Example
MYSQL_DATABASE Name of the database that will host XStudio's data xstudiodb
MYSQL_USER Name of the MariaDB account that XStudio will use xstudio
MYSQL_PASSWORD Clear password of the MariaDB account that XStudio will use xstudiopwd
BACKUP_FTP_HOST (opt.) FTP host where the latest backup can be sent on a weekly basis ftp-server.acme.com
BACKUP_FTP_USER (opt.) Username to connect to the FTP server ftpuser
BACKUP_FTP_PASSWORD (opt.) Clear password to connect to the FTP server ftpuserpwd
CUSTOMER_INSTANCE_NAME (opt.) Name of the folder that will store the weekly backup acme_prod_1


Based on the above example values, the image can be run in a container using the command:

docker run --name xstudio-backup-container
-e MYSQL_DATABASE=xstudio_db
-e MYSQL_USER=xstudio
-e MYSQL_PASSWORD=xstudiopwd
-e BACKUP_FTP_HOST=ftp-server.acme.com
-e BACKUP_FTP_USER=ftpuser
-e BACKUP_FTP_PASSWORD=ftpuserpwd
-e CUSTOMER_INSTANCE_NAME=acme_prod_1
xqual/xstudio-backup:v1


Thanks to the optional parameters, once a week, the latest recorded backup will be transfered to the FTP server ftp-server.acme.com (connecting as ftpuser with password ftpuserpwd) in the root folder acme_prod_1

It is not really useful to run this container by itself though. You should use Docker-compose to run it as part as an integrated instance.
Please refer the section Run all the images in an integrated environment for more details.

xstudio-tomcat

This Docker image runs the core system of the XStudio server. This server includes a servlet container (Tomcat) listening on port 8080 in HTTP (and optionally on port 8443 in HTTPS if you provide an optional certificate).

The server will expose interface for:
  • the front-end interface for XStudio.web
  • the front-end interface for XStudio JNLP client
  • the REST API server

This docker image can take optional parameters which are used only if you wish to:
  • Insert a license key
  • Customize the visuals of XStudio with your own logo, icon, splashscreen or title in the header of the application or the reports
  • Expose the XStudio.web URL as HTTPS


The docker needs a few parameter to be customized with your own preferences:
Parameter Description Example
MYSQL_DATABASE Name of the database that will host XStudio's data xstudiodb
MYSQL_USER Name of the MariaDB account that XStudio will use xstudio
MYSQL_PASSWORD_ENCRYPTED Encrypted password of the MariaDB account that XStudio will use
You can encrypt a clear password using our REST API service, however we advise to start with the default value which is 560B599C2331BE79C3ADD6621DBE8BDC which corresponds to the user xstudio with clear password xstudiopwd)
-
LICENSE_KEY (opt.) The license key you purchased from us
If you do not provide a license key, the server will stay in community version with all its limitations
-
CUSTOMER_REPOSITORY (opt.) A URL where you can store your custom visuals and/or SSL certificate http://acme-server.com/docker
CUSTOMER_INSTANCE_NAME (opt.) Name of the folder on the customer repository that will store the custom visuals and/or SSL certificate acme_prod_1
SSL_KEYSTORE_ALIAS (opt.) The alias to use with the Java Keystore containing the certificate for the SSL access 1
SSL_KEYSTORE_FILENAME (opt.) The file name of the java Keystore containing the certificate for the SSL access acme.jks
SSL_KEYSTORE_PASSWORD (opt.) The password to use with the Java Keystore containing the certificate for the SSL access acmepwd


Based on the above example values, the image can be run in a container using the command:

docker run --name xstudio-backup-container
-e MYSQL_DATABASE=xstudio_db
-e MYSQL_USER=xstudio
-e MYSQL_PASSWORD_ENCRYPTED=560B599C2331BE79C3ADD6621DBE8BDC
-e LICENSE_KEY=<license_key>
-e CUSTOMER_REPOSITORY=http://acme-server.com/docker
-e CUSTOMER_INSTANCE_NAME=acme_prod_1
-e SSL_KEYSTORE_ALIAS=1
-e SSL_KEYSTORE_FILENAME=acme.jks
-e SSL_KEYSTORE_PASSWORD=acmepwd
xqual/xstudio-tomcat:4.1sp3




If you wish to customize your XStudio instance with some custom visuals and a SSL certificate, your repository must be accessible from the docker image.
Based on the above example, the repository should serve the files this way:
http://acme-server.com/docker/acme_prod_1/ssl/acme.jks
http://acme-server.com/docker/acme_prod_1/visuals/icon.png
http://acme-server.com/docker/acme_prod_1/visuals/logo.png
http://acme-server.com/docker/acme_prod_1/visuals/splashscreen.png
http://acme-server.com/docker/acme_prod_1/visuals/custom.app_title.txt
http://acme-server.com/docker/acme_prod_1/visuals/custom.report.docx_header.txt



You can include only the visuals you are interested in.
Here is a description of each files your repository can host:
Filename Description Requirements
icon.png Will be used as the JNLP client's icon PNG file with a dimension 16x16 pixels
logo.png Will be used for instance in the header of the paper reports PNG file with a dimension preferably not exceeding 300x300 pixels
splashscreen.png Will be used as splashscreen of the JNLP client PNG file with a dimension preferably not exceeding 700x700 pixels
custom.app_title.txt Will be used as application title in the JNLP client's header Text file containing only a one-line text (do NOT add a new line feed at the end)
custom.report.docx_header.txt Will be used in the header of the .docx paper reports Text file containing only a one-line text (do NOT add a new line feed at the end)


It is not really useful to run this container by itself though. You should use Docker-compose to run it as part as an integrated instance.
Please refer the section Run all the images in an integrated environment for more details.

Run all the images in an integrated environment

All three images can be run individually in containers as explained above but what is still missing is:
  • Make the three containers communicate together
  • Make some of the data persistent (such as the database data!)
  • Make some of the data shared among different containers (such as the backup repository)

That's where Docker-compose enter in the game.
Docker-compose needs a docker-compose.yml file that describes how the 3 containers are integrated together, which volumes are necessary, which container can access them etc.

Then, Docker-compose fetch the images from Docker Hub, run them in a common network, mount some volumes and make them accessible by some of the containers.
The volumes are persistent and stored in the docker environment of the host.



  (green parts are optional)

You can pass all the customization parameters by having them in a dedicated file named .env

In the end, the only things you need to do to create a new XStudio instance is:
  • create a dedicated folder on the docker daemon host
  • put the docker-compose.yml in that folder
  • create a .env file in that folder containing all the parameter values you want
  • execute the command docker-compose up

Docker-compose will search for a .env file (in the same directory) to get all the parameters, and will run the three containers accordingly.

Versions

The xqual/xstudio-mariadb and xqual/xstudio-tomcat services must have some compatible versions to work together (without any additional step).

xqual/xstudio-tomcat xqual/xstudio-backup
5, 5sp1, 5sp2, 5sp3 v89
4.1, 4.1sp1, 4.1sp2, 4.1sp3, 4.1sp4, 4.1sp5, 4.1sp6, 4.1sp7, 4.1sp8, 4.1sp9, 4.1sp10 v88