Upgrade from Older Versions
Last Updated: July 2022
This document provides instructions for upgrading from versions of Tethys Platform prior to 4.2.
Upgrading 3.X Versions
Use these instructions to update Tethys 3.X installations to other versions of Tethys 3 (3.1, 3.2, 3.3, and 3.4). Tethys Platform has become much more stable as of version 3.0 and you shouldn't expect many major breaking changes between different minor versions (e.g. 3.1, 3.2, 3.3). In other words, apps that work in 3.0 should work in 3.1 without any changes. The following steps can be used as a general guide, but additional steps may be required for your specific installation.
Upgrade Steps
Review the What's New documentation before attempting any upgrade, especially on production servers.
Activate the
tethys
conda environment:conda activate tethys
Update the Tethys Platform conda package and dependencies by installing the new version of Tethys Platform:
conda install -c tethysplatform -c conda-forge tethys-platform=3.*
Migrate the Tethys Platform database tables:
tethys db migrate
Make any changes to your apps if necessary. This should only be the case when upgrading between major versions (e.g. 3.0 to 4.0). See the What's New documentation for detailed notes on what changes occur in each release.
Note
In previous versions of Tethys Platform it was required to backup the settings.py
file before upgrading and then copy your custom settings from the backup to the new settings.py
file after upgrading. As of version 3.0, this should no longer be the case. All custom settings should be defined in the portal_config.yml
, which is preserved during upgrades. See: Tethys Portal Configuration for more details.
Additional Upgrade Steps for Production Installations
The following additional steps may be required for production server upgrades.
Collect static files:
tethys manage collectstatic
Restart Daphne and NGINX servers:
sudo supervisorctl restart all
Upgrading from 2.1 to 3.X
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/
. As of 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
Activate Tethys environment uninstall the previous version of
tethys-platform
:conda activate tethys pip uninstall tethys-platform
Install the new conda packaged version of
tethys-platform
:conda install -c tethysplatform -c conda-forge tethys-platform
Rename
~/tethys/
to~/.tethys/
:mv ~/tethys ~/.tethys
Generate a
portal_config.yml
file:tethys gen portal_config
Port any custom settings from your old
settings.py
to the newportal_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.Migrate the database:
- If you have a locally installed database then you will need to add a
DIR
setting in theDATABASES
setting of theportal_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 toTETHYS_HOME
. By default the locally installed database would have been at~/tethys/psql/
, but now thatTETHYS_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.- If you have a locally installed database then you will need to add a