Skip to main content

3.5.1 to 3.6.0

New Aerie Workspace Service​

Aerie v3.6.0 contains a significant change to how user sequences are stored in workspaces. Previously, they were stored in our database, but in v3.6.0+ they are stored as files (within a Docker volume), and served to the UI through a new backend web service called Workspace Service. This may require changes to your deployment to ensure it's configured correctly.

PUBLIC_WORKSPACE_CLIENT_URL in docker-compose.yml​

If you are upgrading a deployment on a remote host (ie. not localhost), you will need to provide the environment variable PUBLIC_WORKSPACE_CLIENT_URL to the aerie-ui container to tell the UI where to reach the workspace service. If this applies to you, you should already have something like this in the aerie-ui: section of your docker-compose.yml:

  aerie_ui:
    environment:
      PUBLIC_GATEWAY_CLIENT_URL: https://YOUR_HOST_NAME:9000
      # ...

Add the following line to the same environment section within aerie-ui:

      PUBLIC_WORKSPACE_CLIENT_URL: https://YOUR_HOST_NAME:28000

Open Workspace Service port (28000)​

The workspace service communicates with the UI on its own port (28000 by default, configurable through docker-compose) which must be accessible. If your Aerie instance is running behind a proxy, load-balancer or firewall, you may need to configure it to allow connections on this port. This port must be reachable from both the UI, and the other backend services (ie. from your users' network, and from the server itself).

New docker volume workspace_file_store​

A new docker volume called 'workspace_file_store' was added to our docker-compose - if you're maintaining your own list of aerie volumes in your docker-compose, you'll need to add this to the list.

Workspaces Database Migration​

This release includes an updated database migration script to preserve your existing sequences and migrate them to the new filesystem storage. If you don't care about preserving your data through this upgrade, just drop your Docker volumes and skip this section. If you want to keep your data, you'll need to run the database migration script as outlined in the Production Deployment docs. A few notes:

  • This is a more complex migration than most, so we recommend you backup your database first in case anything goes wrong. Instructions for performing a Postgres dump & restore can be found in this older upgrade guide
  • Generally, the upgrade process is to bring containers down → upgrade → bring containers up → run migration script. Both the postgres and the new aerie_workspace server must be up and running before the migration script is run or else migration will fail (check with docker ps).
  • Before running migration, make sure you have the latest version of the aerie_db_migration.py script (from the v3.6.0 deployment folder or Deployment.zip) rather than reusing an old copy, as the script has changed.

Migration troubleshooting​

In general, if things go wrong during data migration, the database will be rolled back with an error message and you can safely re-run it once the underlying problem has been fixed.

There is one exception to this in the new migration - if something goes wrong halfway through the process of writing new sequence files to the filesystem, the new files could be left in a halfway-copied state. This would manifest itself as an error after this line has been printed to the logs:

This migration will move your user sequences onto the Workspace Server.

...but before this line:

Successfully applied workspace file migration

If this occurs, the safest move is to remove your workspace_file_store docker volume before retrying migration.

Aerie Actions​

caution

As discussed elsewhere in the docs, Aerie Actions are included in this release as an experimental feature. Aerie intentionally defaults to only allowing users with the aerie_admin role to upload actions, and you should not change this setting. Actions should be authored and reviewed by trusted users only, as a malicious action could get access to other parts of the Aerie database besides the workspace within which it is run.