Tethys Platform
Table Of Contents
Table Of Contents

Upgrade to 3.0

Last Updated: October 2019

This document provides a recommendation for how to upgrade Tethys Platform from the last release version. If you have not updated Tethys Platform to the last release version previously, please revisit the documentation for that version and follow those upgrade instructions first.

Significant Changes

Many significant changes were made since Tethys Platform 2.1. Please note the following differences:

Source Code

Tethys in now a conda package! This means that when installing tethys you will no longer clone the source code into TETHYS_HOME. Now Tethys will be installed in your conda environment instead.

TETHYS_HOME

In 2.1 TETHYS_HOME by default was located at ~/tethys/. In 3.0 TETHYS_HOME is now, by default at ~/.tethys/

Note

If your tethys conda environment is named something other than tethys then TETHYS_HOME will be at ~/.tethys/<ENV_NAME>/. For example if your conda environment were named tethys-dev then TETHYS_HOME would be at ~/.tethys/tethys-dev/

Settings

In 2.1 custom settings were specified directly in the settings.py file. Now settings must be configured in the portal_config.yml file which is generated in TETHYS_HOME

Upgrade Steps

  1. Activate Tethys environment uninstall the previous version of tethys-platform:

    . t
    pip uninstall tethys-platform
    
  2. Install the new conda packaged version of tethysplatform:

    conda install -c tethysplatform -c conda-forge tethysplatform
    
  3. Rename ~/tethys/ to ~/.tethys/:

    mv ~/tethys ~/.tethys
    
  4. Generate a portal_config.yml file:

    tethys gen portal_config
    
  5. Port any custom settings from your old settings.py to the new portal_config.yml:

    Common settings that need to be copied include:
    • DEBUG

    • ALLOWED_HOSTS

    • DATABASES

    • STATIC_ROOT, TETHYS_WORKSPACES_ROOT

    • EMAIL_HOST, EMAIL_PORT, EMAIL_HOST_USER, EMAIL_HOST_PASSWORD, EMAIL_USE_TLS, DEFAULT_FROM_EMAIL

    • SOCIAL_OAUTH_XXXX_KEY, SOCIAL_OAUTH_XXXX_SECRET

    • BYPASS_TETHYS_HOME_PAGE

    Refer to Tethys Portal Configuration for more details on specifying settings in the portal_config.yml file.

  6. Migrate the database:

    If you have a locally installed database then you will need to add a DIR setting in the DATABASES setting of the portal_config.yml file:
    DATABASES:
      default:
        NAME: tethys_platform
        USER: tethys_default
        PASSWORD: pass
        HOST: localhost
        PORT: 5436
        DIR: psql
    

    Note

    The DIR setting is relative to TETHYS_HOME. By default the locally installed database would have been at ~/tethys/psql/, but now that TETHYS_HOME has moved the default location is ~/.tethys/psql/.

    Tip

    If you have a locally installed database server then you need to downgrade postgresql to the version that the database was created with.

    t
    conda install -c conda-forge postgresql=9.5
    
    Once you have the database settings and dependencies configured properly then you can migrate the database by running:
    tethys db migrate
    

    Tip

    Refer to the db command docs for more information on how to use the new tethys db command.