Upgrading VISA from Version 2.X to 3.X

Upgrading VISA from Version 2.X to 3.X#

[18/11/2024]

In 2024 VISA was redevelopped to run using the Quarkus framework (migrating from Dropwizard). While attempting to maintain backward compatibility with the previous version of VISA some minor changes to the deployment are necessary when doing the upgrade.

Environment variable changes#

File Logging#

The following changes are needed if you want to specifically save the application log in a file.

  • VISA_LOGGING_FILE_ENABLED

    New. You can now explicitly activate/deactivate the file logging. By default it is activated.

  • VISA_LOGGING_FILE_MAX_FILE_SIZE

    Updated. Format has changed from (eg) 100MB to 100M

  • VISA_LOGGING_FILE_FORMAT

    Updated. The format pattern has changed. See the Quarkus documentation for full details. An example of the changes is shown below.

    Old format: %d{yyyy-MM-dd HH:mm:ss.SSS,CET} %-5level [%-40.40logger{10}] - %msg%n

    New format: %d{yyyy-MM-dd HH:mm:ss.SSS} %-5p [%-40.40c{3.}] - %s%e%n

Syslog configuration#

The following changes are needed for syslog setup.

  • VISA_LOGGING_SYSLOG_ENABLED

    New. You can now explicitly activate/deactivate the syslog logging. By default it is activated.

  • VISA_LOGGING_SYSLOG_HOST

    Deprecated. See VISA_LOGGING_SYSLOG_ENDPOINT for the replacement.

  • VISA_LOGGING_SYSLOG_PORT

    Deprecated. See VISA_LOGGING_SYSLOG_ENDPOINT for the replacement.

  • VISA_LOGGING_SYSLOG_ENDPOINT

    New. To configure the syslog server you now need to specify both the host and the port together, eg mysyslog.server.org:514

  • VISA_LOGGING_SYSLOG_APP_NAME

    New. You must specify the application name as registered by syslog.

  • VISA_LOGGING_SYSLOG_TYPE

    New. Defines the syslog protocol. Defaults to rfc3164 but can also be rfc5424.

  • VISA_LOGGING_SYSLOG_FACILTY

    Updated. The syslog facilty values have chanegd. For example local0 becomes local-use-0. See the Quarkus documentation for more details.

Email notification of errors#

VISA provides the capability of sending emails (to the dev team for example) when errors occur.

  • VISA_LOGGING_EMAIL_APPENDER_ENABLED

    New. You can now explicitly activate/deactivate the email notifications. By default they are deactivated.

  • VISA_LOGGING_EMAIL_SUBJECT

    Updated. Previously each individual error produced an email and the error was used injected into the VISA_LOGGING_EMAIL_SUBJECT template. Now the VISA_LOGGING_EMAIL_SUBJECT is simply a prefix to an email subject. For example [VISA]: An error occurred %logger{20} - %msg is now simply [VISA]: Error report

General#

  • VISA_LOGGING_TIMEZONE

    Deprecated. Previously it was possible to set a logging timezone for all loggers. This is no longer possible and must be set in individual log formats.

Reverse proxy changes#

A couple of changes have been made to the backend endpoints, namely for GraphQL and websockets. If you use reverse proxy (eg Nginx) to redirect trafic arriving on certain endpoints then you will need to update your configuration. Below we give examples of the new configuration for Nginx.

GraphQL#

Previously GraphQL calls arrived to the /graphql endpoint. With Quarkus this has had to be changed to /api/graphql. As such you no longer need to explicitly manage this (as it should already be managed by a /api configuration). If you have an entry such as

    location /graphql {
      proxy_pass       http://api:8086/graphql;
      proxy_set_header X-Real-IP $remote_addr;
      proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
      proxy_set_header Host $http_host;
    }

you can now delete this.

Websockets#

Previously Socket.io was used for remote desktop communication. Now a standard websocket is used and with Quarkus the endpoint is now with a base path of /api/ws. In fact 2 principal websockets are opened with this base path. Unlike Socket.io, no rewrite rule is needed either.

The websockets managed by the api-server are now configured with the following Nginx configuration:

    # New websocket connections configuration
    location /api/ws {
          proxy_pass http://api:8086/api/ws;
          proxy_set_header Upgrade $http_upgrade;
          proxy_set_header Connection "upgrade";
          proxy_http_version 1.1;
          proxy_redirect off;
          proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
          proxy_set_header Host $http_host;
    }

Previous configs on the old endpoint, such as

    # Old socket.io connections configuration
    location /ws/vdi {
          proxy_set_header Upgrade $http_upgrade;
          proxy_set_header Connection "upgrade";
          proxy_http_version 1.1;
          proxy_redirect off;
          proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
          proxy_set_header Host $http_host;
          proxy_pass http://api:8087/socket.io;
    }

can be deleted.

Websocket server port#

Note that there is another difference for the api-server websockets: they are now exposed on the port 8086, the same as the api-server REST API.

You no longer need to explicity expose the legacy port 8087.

PostgreSQL version#

The minimum version of PostgreSQL is currently 9.6 but shortly this will be increased to 12.0. Quarkus officially only supports versions of 12.0 and above but the current version of VISA still works with 9.6.

Please update your database version accordingly.

Docker Container Registry#

The new Docker containers for VISA are now available on the GitHub Container Register (ghcr.io):

Dockerhub currently still has the same Docker images but will be deprecated shortly and more recent versions of VISA images may not be available.

Upgrade procedure#

The upgrade of VISA has no non-reversible impacts on the database so rolling back to 2.X versions is simple. We do however recommend saving copies of the environment variable files and any Nginx (or equivalent) configuration files.

Once modifications (outlined above) to the environment variables and Nginx configuration files are done then the process of updating the Docker image versions is trivial.

Version Rollback#

To revert to the 2.X version, please replace your copied environment variables file and Nginx configuration and change to the latest 2.X version of VISA.

Database changes to the 3.X version are trivial and do not impact the 2.X version.

Contents