Skip to content

Upgrade from 2.16 to 2.17.0

Because of the broad scope of the 2.17.0 version, this page describes the upgrade procedure in detail. Notable changes in this version include:

  • New concepts of computational resources and profiles.
  • Updates of the application settings.
  • Users cannot self-register through OAuth any more.
  • A user must meet more conditions in order to access the API (namely being marked as both active and verified, and being associated to a computational profile).

Note: Automatic data migration for version 2.17.0 is only supported for Fractal instances attached on a SLURM cluster, and not for local instances.

Preliminary checks (with fractal-server 2.16)

These checks should be performed on a working 2.16 Fractal instance, before starting the upgrade procedure.

  1. In the user list, identify all users who are actually meant to use this Fractal instance, and mark them as both "active" and "verified".
    • The automated data-migration script described below will only look for users who are both active and verified.
    • Settings for other users won't be modified, and they won't be able to use Fractal without a manual admin intervention.
  2. For all active&verified users, make sure that their project_dir is set. The data-migration script will fail if it is not set for some active&verified user - because project_dir becomes a required user property.

Upgrade procedure

  1. Make a copy of the current .fractal-server.env file and name it .fractal-server.env.old.
  2. Make sure that .fractal_server.env.old includes the FRACTAL_SLURM_WORKER_PYTHON variable. If this variable is not set, add it and set it to the absolute path of the Python interpreter which runs fractal-server.
  3. Make a backup of the current database with pg_dump (see example).
  4. Stop the fractal-server running process (e.g. via systemctl stop fractal-server).
  5. Edit .fractal_server.env to align with the new version. List of changes:
    • Edit the FRACTAL_RUNNER_BACKEND value so that it is one of slurm_sudo or slurm_ssh.
      • NOTE: This must be changed in the fractal-web configuration as well.
    • Rename FRACTAL_VIEWER_AUTHORIZATION_SCHEME into FRACTAL_DATA_AUTH_SCHEME - if present.
    • Rename FRACTAL_VIEWER_BASE_FOLDER into FRACTAL_DATA_BASE_FOLDER - if present.
    • Add FRACTAL_DEFAULT_GROUP_NAME=All (note: the same variable must be set also in the fractal-web environment file).
    • Update OAuth-related variables to comply with the new expected ones.
      • Add the OAUTH_CLIENT_NAME variable.
      • Remove the client name from the names of all other variables, e.g. as in OAUTH_XXX_CLIENT_ID --> OAUTH_CLIENT_ID (if OAUTH_CLIENT_NAME="XXX").
    • If FRACTAL_EMAIL_PASSWORD is set, replace its value with the non-encrypted password.
    • Drop all following variables (if set):
      • FRACTAL_DEFAULT_ADMIN_EMAIL
      • FRACTAL_DEFAULT_ADMIN_PASSWORD
      • FRACTAL_DEFAULT_ADMIN_USERNAME
      • FRACTAL_TASKS_DIR
      • FRACTAL_RUNNER_WORKING_BASE_DIR
      • FRACTAL_LOCAL_CONFIG_FILE
      • FRACTAL_SLURM_CONFIG_FILE
      • FRACTAL_SLURM_WORKER_PYTHON.
      • FRACTAL_TASKS_PYTHON_DEFAULT_VERSION
      • All FRACTAL_TASKS_PYTHON_3_* variables
      • FRACTAL_PIXI_CONFIG_FILE.
      • FRACTAL_SLURM_POLL_INTERVAL.
      • FRACTAL_PIP_CACHE_DIR
      • FRACTAL_EMAIL_PASSWORD_KEY
  6. Verify that the following files are available in the current directory:
  7. .fractal_server.env.old
  8. .fractal_server.env
  9. The JSON file with the SLURM configuration (as defined in the FRACTAL_SLURM_CONFIG_FILE variable of .fractal_server.env.old).
  10. The JSON file with the pixi configuration, if defined in the FRACTAL_PIXI_CONFIG_FILE variable of .fractal_server.env.old.
  11. Replace the current fractal-server version with 2.17.0 (e.g. via pip install fractal-server==2.17.0 - within the appropriate Python environment).
  12. Run the database-schema-migration command fractalctl set-db.
  13. Run the database-data-migration command fractalctl update-db-data.
  14. It is recommended to also upgrade to versions 2.17.1, right after the previous steps, because this patch release completes the migration process (by applying some schema migrations which could not be included in 2.17.0). This version update is much simpler than the previous one, since it only involves two steps:
    • pip install fractal-server==2.17.1
    • fractalctl set-db
  15. The same applies to 2.17.2, which is already available with several small fixes or updates.
  16. Restart the fractal-server process (e.g. via systemctl start fractal-server).

Post-upgrade cleanup

  • Upgrade fractal-web to version 1.21.1.
  • Edit fractal-web configuration as follows:
    • Add FRACTAL_DEFAULT_GROUP_NAME=All to the environment file
    • Edit the FRACTAL_RUNNER_BACKEND value so that it is one of slurm_sudo or slurm_ssh.
  • Restart the fractal-web process.
  • Verify that log-in still works (including via OAuth).
  • Review the names of resources/profiles.
  • Review the association between users and profiles.
  • Verify that job execution works as expected.
  • Verify that task collection works as expected.
  • Verify that the OME-Zarr viewer works as expected (if configured).