How to Upgrade Exploratory Server

Please follow the steps below to upgrade your existing Exploratory Server.

Note <<version>> in the examples below should be replaced with the version you are upgrading to. (e.g. 6.8.0.19)

1. Download the New Docker Images File

Download the latest Exploratory Server docker images file from the "For Upgrade" link in this release note.

2. Load Docker Images

Run the following command to load the downloaded docker images file.

docker load -i exploratory-server-images-<<version>>.tar.gz

3. Stop Existing Exploratory Server

Go to your existing exploratory directory and stop the Exploratory Server.

cd exploratory
docker-compose down

4. Update docker-compose.yml

To update docker image versions etc. in docker-compose.yml file, download and execute the migration script.

Download the migration script into the existing exploratory directory.

curl -O https://exploratory-download.s3-us-west-2.amazonaws.com/collab-server/migrate_docker_compose_<<version>>.sh
curl -O https://exploratory-download.s3-us-west-2.amazonaws.com/collab-server/migrate_docker_compose_<<version>>.js

Execute the downloaded migration script.

bash migrate_docker_compose_<<version>>.sh

This will update the existing docker-compose.yml file so that it can run the latest Exploratory Server.

Add License Key

If you already have obtained the license key, add it under the environment section, which can be found at around line 22, as follows. Note that you want to replace xxxxxxxxxx with your license key.

  exploratory:
    image: exploratory:<<version>>
    environment:
      - EXPL_ADMIN_FIRSTNAME=Admin
      - EXPL_ADMIN_LASTNAME=User
      - EXPL_ADMIN_EMAIL=hideaki@exploratory.io
      - EXPL_CRYPTOKEY=secretkey
      - EXPL_LICENSEKEY=xxxxxxxxxx

5. Update Nginx configuration (default.conf)

In version 6.8.0, the URL of the Schedule Admin Screen was moved from the one with a different port number (default 3001) to the one with the same port number as the rest of the pages (default 8080). To make this work after upgrading, please complete the following modifications to the default.conf file, which is the configuration file for Nginx.

Also, in version 6.8.4, we added a new piece of configuration to make CSV download in the middle of a Parameter session work. We recommend adding this configuration when upgrading from previous versions.

If SSL is not used

If you have not configured SSL for the Exploratory Server, follow the instructions in this section.

Upgrade from version 6.8.0 or newer

If you are upgrading from version 6.8.0 or newer, the configuration for the Schedule Admin Screen should be already there. Please insert only the following additional configuration for Safari into the location below.

Additional Configuration:

    location /socket.io/ {
        proxy_pass http://exploratory:3000/socket.io/;
        proxy_set_header Host $http_host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto http;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
    }

Location to insert the configuration above:

server {
    listen       80;
    server_name  localhost;
        ...
        ...Insert the above additional configuration at this location right before the following line...
        location / {
        proxy_pass http://exploratory:3000/;
        ...

Upgrade from version 6.7 or older

If you are upgrading from version 6.7 or older, please insert both the configuration for Schedule Admin Screen and the configuration for Safari into the location below.

Additional Configuration:

    location = /schedule {
        proxy_pass http://agendash:3001/;
        proxy_set_header Host $http_host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto http;
    }
    location /agendash-css/ {
        proxy_pass http://agendash:3001/agendash-css/;
        proxy_set_header Host $http_host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto http;
    }
    location /agendash-js/ {
        proxy_pass http://agendash:3001/agendash-js/;
        proxy_set_header Host $http_host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto http;
    }
    location /agendash-api/ {
        proxy_pass http://agendash:3001/agendash-api/;
        proxy_set_header Host $http_host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto http;
    }
    location /socket.io/ {
        proxy_pass http://exploratory:3000/socket.io/;
        proxy_set_header Host $http_host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto http;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
    }

Location to insert the configuration above:

server {
    listen       80;
    server_name  localhost;
        ...
        ...Insert the above additional configuration at this location right before the following line...
        location / {
        proxy_pass http://exploratory:3000/;
        ...

If SSL is used

If you have followed this document to set up SSL, please follow the instructions in this section.

Upgrade from version 6.8.0 or newer

If you are upgrading from version 6.8.0 or newer, the configuration for the Schedule Admin Screen should be already there. Please insert only the following additional configuration for Safari into the location below.

Additional Configuration:

    location /socket.io/ {
        proxy_pass http://exploratory:3000/socket.io/;
        proxy_set_header Host $http_host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto https;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
    }

Location to insert the configuration above:

server {
    listen       443;
    server_name  localhost;
        ...
        ...Insert the above additional configuration at this location right before the following line...
        location / {
        proxy_pass http://exploratory:3000/;
                ...

Upgrade from version 6.7 or older

If you are upgrading from version 6.7 or older, please insert both the configuration for Schedule Admin Screen and the configuration for Safari into the location below.

Additional Configuration:

    location = /schedule {
        proxy_pass http://agendash:3001/;
        proxy_set_header Host $http_host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto https;
    }
    location /agendash-css/ {
        proxy_pass http://agendash:3001/agendash-css/;
        proxy_set_header Host $http_host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto https;
    }
    location /agendash-js/ {
        proxy_pass http://agendash:3001/agendash-js/;
        proxy_set_header Host $http_host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto https;
    }
    location /agendash-api/ {
        proxy_pass http://agendash:3001/agendash-api/;
        proxy_set_header Host $http_host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto https;
    }
    location /socket.io/ {
        proxy_pass http://exploratory:3000/socket.io/;
        proxy_set_header Host $http_host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto https;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
    }

Location to insert the configuration above:

server {
    listen       443;
    server_name  localhost;
        ...
        ...Insert the above additional configuration at this location right before the following line...
        location / {
        proxy_pass http://exploratory:3000/;
                ...

6. Extend timeout for handling larger data (Optional)

At version 6.1.3.0, we changed the default for the following timeout configurations, so that Insights with larger data can be handled without problems. If you are upgrading from a version older than 6.1.3.0, we recommend the following changes.

Timeout for the execution of R

Extend the timeout for execution of R from 10 minutes (600 seconds) to 30 minutes (1800 seconds).

  • Around line 70 of docker-compose.yml, locate the scheduler: section, and the environment section under the scheduler: section. Update the value of EXPL_SCHEDULER_R_TIMEOUT in the environment: section from 600 to 1800.

Before the change:

  scheduler:
    image: scheduler:<<version>>
    environment:
      - EXPL_SCHEDULER_R_TIMEOUT=600

After the change:

  scheduler:
    image: scheduler:<<version>>
    environment:
      - EXPL_SCHEDULER_R_TIMEOUT=1800

Extend Nginx timeout for sending/receiving data

Here we extend Nginx's timeout for sending/receiving data. Nginx is the server that sits at the front end of the Exploratory Server, which receives requests from the Exploratory Desktop or web browser and passes them down to the Node Express server at the backend of the Exploratory Server. We are extending the timeout around this passing of data so that the timeout is not easily reached while uploading a larger EDF file from Exploratory Desktop.

Edit dafault.conf file, which is the configuration file of Nginx, adding the following 3 configurations.

  • proxy_read_timeout 1200s; This extends the timeout for Nginx to read response data from Node Express to 1200 seconds.
  • proxy_send_timeout 1200s; This extends the timeout for Nginx to pass down the request from Exploratory Desktop or web browser to the Node Express to 1200 seconds.
  • proxy_next_upstream_timeout 3600s; This extends the timeout for Nginx to wait for the response from Node Express to 3600 seconds.

**Example of content of default.conf file:**

server {
    ...
    location / {
        ...
        proxy_read_timeout 1200s;
        proxy_send_timeout 1200s;
        proxy_next_upstream_timeout 3600s;
     }

7. Restart Exploratory Server

Restart the Exploratory Server with the following command from under your exploratory folder.

docker-compose up -d

If you have a problem at starting up the Exploratory Server, please check the "Errors While Starting Up Exploratory Server" section in the How to Fix Common Exploratory Server Problems note.

8. Upgrade MongoDB version if you are upgrading to Exploratory Server v8 or above from v7 or below.

If you upgraded your Exploratory Server from v7 or an earlier version to v8 or above, you need to upgrade the MongoDB database version to version 6.

  • Make sure the Exploratory Server is up and running by the docker ps command. It should show a list of docker containers running. If you don't see any containers running, start the system first.
  • Go to your existing exploratory directory and download the migration script. Make sure the file upgrade_mongodb_to_6.0.sh is created.
cd exploratory
curl -O https://exploratory-download.s3.us-west-2.amazonaws.com/collab-server/upgrade_mongodb_to_6.0.sh
  • Run the upgrade script. It will upgrade the MongoDB and restart the Exploratory Server automatically.
bash upgrade_mongodb_to_6.0.sh

9. Update database records if you are upgrading from v8 to v9.

If you upgraded your Exploratory Server from v8 to v9, you need to update the database records for the published contents in the MongoDB database to take advantage of the v9 new features.

  • Make sure the Exploratory Server is up and running by the docker ps command. It should show a list of docker containers running. If you don't see any containers running, start the system first.
  • Go to your existing exploratory directory and download the migration script. Make sure the file upgrade_v8_to_v9.sh is created.
cd exploratory
curl -O https://exploratory-download.s3.us-west-2.amazonaws.com/collab-server/upgrade_v8_to_v9.sh
  • Run the upgrade script. It will update the database records in the MongoDB.
bash upgrade_v8_to_v9.sh

10. Update database records if you are upgrading from v9 to v10.

If you upgraded your Exploratory Server from v9 to v10, you need to update the existing access logs for the viewing access log feature introduced in v10. Here is how.

  • Make sure the Exploratory Server is up and running by the docker ps command. It should show a list of docker containers running. If you don't see any containers running, start the system first.
  • Go to the exploratory directory and run the following command. You don't need to update the file paths. You can just run it as is.
cd exploratory
docker-compose exec exploratory /root/.nvm/versions/node/v14.21.3/bin/node  /exploratory/datablog/tools/update_accesslog.js
  • If the updating process is done successfully, you will see the "Done." message at the end of the output.
Export Chart Image
Output Format
PNG SVG
Background
Set background transparent
Size
Width (Pixel)
Height (Pixel)
Pixel Ratio