
Architecture
A whole instance of XStudio can be deployed using adocker-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 |