Application Installation

Last Updated: July 2022

Once you have the portal configured and setup with all the required services, the next step is to install Tethys applications on to your portal.

2. Install the App

Using the install cli command, you can install the application in one quick step. The install command will install all the dependencies, link any services that you might need for your application and can also rely on the portal configuration to link default services to your application (as configured by the portal administrator).

python
# Normal installation
tethys install

# Development installation
tethys install -d

# Tethys install with custom options
tethys install -f ../install.yml -p $TETHYS_HOME/src/configs/portal_config.yml

3. Restart Tethys Server

Restart tethys portal to effect the changes:

python
tethys manage start

4. Configure Additional App Settings

If any required settings were not configured through the installation process go to the application settings page in the Tethys Portal admin pages and configure them there (see Administrator Pages).

5. Initialize Persistent Stores (Optional)

The install command will automatically run the syncstores command if it detects that the app has persistent stores. However, if you need to run syncstores manually, it can be done like so:

python
tethys syncstores {app_name}

Install Configuration Files

The install command uses three configuration files:

install.yml

This file is generated with your application scaffold. Dependencies that are listed in the install.yml will be installed with conda and will honor the specified channel priority. If there are any dependencies listed in the setup.py that are not specified in the install.yml then these packages will be installed with pip as part of the setup process. This file should be committed with your application code in order to aid installation on a Tethys Portal.

Important

The conda sections of the install.yml file require the conda library and optionally the conda-libmamba-solver library to be installed. Starting with Tethys 5.0 or if you are using micro-tethys-platform, you will need to install these libraries using conda or pip as follows:

bash
# conda: conda-forge channel strongly recommended
conda install -c conda-forge conda conda-libmamba-solver

# pip
pip install conda
yaml
# This file should be committed to your app code.
version: 1.1
# This should be greater or equal to your tethys-platform in your environment
tethys_version: ">=4.0.0"
# This should match the app - package name in your setup.py
name: my_first_app

requirements:
  # Putting in a skip true param will skip the entire section. Ignoring the option will assume it is set to False
  skip: false
  conda:
    channels:
      - conda-forge
    packages:
      - pyshp=2.0.0
      - geojson
      - shapely
      - nodejs

  pip:
    - see

  # Add JavaScript packages and versions under npm as a key value pair
  # If you include JavaScript packages it is recommended the you include "nodejs" as a conda package.
  npm:
    leaflet: 1.8.0

post:
  - test.sh

install.yml Options:

  • version: Indicates the version of the install.yml file. Current default : 1.1

  • tethys_version: Indicates the version of the tethys-platform library (Tethys Portal) required to install the app. Defaults to >=4.0.0. Assumes <4.0.0 if not specified.

  • name: This should match the app-package name in your setup.py

  • skip: If enabled, it will skip the installation of packages. This option is set to False by default.

  • conda/channels: List of conda channels that need to be searched for dependency installation. Only specify any conda channels that are apart from the default.

  • conda/packages: List of python dependencies that need to be installed by conda. These may be entered in the format pyshp=2.0.0 to download a specific version.

  • pip: A list of python dependencies that need to be installed by pip.

  • npm: A dictionary of JavaScript dependencies and versions that are installed by npm. They should be listed as a key-value pair (e.g. leaflet: 1.8.0).

  • post: A list of shell scripts that you would want to run after the installation is complete. This option can be used to initialize workspaces/databases etc. These shell scripts should be present in the same directory as setup.py

Tip

Run tethys gen install to create a blank template of this file. By default the file will be saved to the current working directory.

Note

If npm packages are listed in the install.yml file, then a package.json file will be created in the public directory of the app, and then npm will be run with that file. Alternatively, you can directly create a package.json file in the public directory and it will be used to install JavaScript packages. To ensure that npm is available in the environment, it is recommended that you list nodejs as a conda dependency in the install.yml file.

services.yml

The file is designed to be maintained by Tethys Portal administrators to automatically assign services defined in their Tethys Portal to apps they are installing. This file will only be run by default if there is no portal services config file present (see portal_config.yml). However you can force the use of this file over the portal config by specifying the --force-services tag on the install command.

yaml
# Do not commit this file with your app code. This file is portal specific.
version: 1.0

# Set service params in the following format :
# app_service_setting_name(from your app.py): <service_name or id from list of installed services>
persistent:
  catalog_db: hydroexplorer-persistent
  second_db: main-persistent
wps:
  wps_main: testWPS
dataset:
spatial:
custom_settings:
  max_dams: 5

services.yml Options:

  • version: Indicated the version of the services.yml file. Current default : 1.0

  • persistent : List of persistent store settings in the app and the service to link to each.

  • dataset : List of dataset settings in the app and the service to link to each.

  • spatial : List of spatial persistent store settings in the app and the service to link to each.

  • wps : List of web processing service settings in the app and the service to link to each.

  • custom_settings : List of custom settings in the app and value of each.

Settings in each of the service sections above will need to be listed in the following format:

python
<app_setting_name> : <service_name or id>

In the above example, catalog_db is the name of the setting in your app.py and hydroexplorer-persistent is the name of the service on the portal.

Tip

Run tethys gen services to create a blank template of this file. By default the file will be saved to the current working directory.

portal_config.yml

The file is designed to be maintained by Tethys Portal administrators to automatically assign services defined in their Tethys Portal to apps they are installing. For more information about the portal_config.yml see Tethys Portal Configuration.

yaml
# Portal Level Config File

# For more information about this file refer to the Tethys Docs (http://docs.tethysplatform.org/en/stable/tethys_portal/configuration.html)
version: 2.0
name: Tethys Main Portal

############################################################################
# APPS
# The "tethys install" command checks this section for app settings.
#############################################################################
apps:
  my_first_app:
    services:
      persistent:
        catalog_db: test
      spatial:
      dataset:
      wps:
      custom_settings:

############################################################################
# SETTINGS
# Settings from this section are read everytime the Portal starts up.
#############################################################################
settings:
  SECRET_KEY: 'gij28v16WhZ4v18WtlHqusP5VYnVUslxEvRQoXLj7hvJ2ZRN7f'
  DEBUG: True
  ALLOWED_HOSTS: []
  ADMINS: []
  TETHYS_PORTAL_CONFIG:
    BYPASS_TETHYS_HOME_PAGE: False
    ENABLE_OPEN_SIGNUP: False
    ENABLE_OPEN_PORTAL: False
    ENABLE_RESTRICTED_APP_ACCESS: False
    #  REGISTER_CONTROLLER: ''
    #  STATIC_ROOT: ''
    #  TETHYS_WORKSPACES_ROOT: ''
    #  STATICFILES_USE_NPM: True
    #  ADDITIONAL_TEMPLATE_DIRS:
    #  - tethysapp.myapp.templates
    #  ADDITIONAL_URLPATTERNS:
    #  - tethysext.myextension.urls

  SESSION_CONFIG:
    EXPIRE_AT_BROWSER_CLOSE: True
    SECURITY_WARN_AFTER: 840
    SECURITY_EXPIRE_AFTER: 900

  DATABASES:
    default:
      ENGINE: django.db.backends.sqlite3
      NAME: tethys_platform.sqlite

    postgresql_db_config:
      ENGINE: django.db.backends.postgresql
      NAME: tethys_platform
      USER: tethys_default
      PASSWORD: pass
      HOST: localhost
      PORT:  5436
      DIR: psql

  # LOGGING:
  #   formatters: {}
  #   handlers: {}
  #   loggers:
  #     django:
  #       handlers:
  #       - console_simple
  #       level: WARNING
  #     tethys:
  #       handlers:
  #       - console_verbose
  #       level: INFO
  #     tethysapp:
  #       handlers:
  #       - console_verbose
  #       level: INFO

  #  INSTALLED_APPS_OVERRIDE: []
  INSTALLED_APPS: []

  #  MIDDLEWARE_OVERRIDE: []
  MIDDLEWARE: []

  #  AUTHENTICATION_BACKENDS_OVERRIDE: []
  AUTHENTICATION_BACKENDS: []

  #  RESOURCE_QUOTA_HANDLERS_OVERRIDE: []
  RESOURCE_QUOTA_HANDLERS: []

  CAPTCHA_CONFIG:
    ENABLE_CAPTCHA: False
    RECAPTCHA_PRIVATE_KEY: ''
    RECAPTCHA_PUBLIC_KEY: ''
    #  RECAPTCHA_PROXY_HOST: https://recaptcha.net

  #  OAUTH_CONFIG:
  #    SOCIAL_AUTH_GOOGLE_OAUTH2_KEY: ''
  #    SOCIAL_AUTH_GOOGLE_OAUTH2_SECRET: ''
  #
  #    SOCIAL_AUTH_FACEBOOK_KEY: ''
  #    SOCIAL_AUTH_FACEBOOK_SECRET: ''
  #    SOCIAL_AUTH_FACEBOOK_SCOPE: ['email']
  #
  #    SOCIAL_AUTH_LINKEDIN_OAUTH2_KEY: ''
  #    SOCIAL_AUTH_LINKEDIN_OAUTH2_SECRET: ''
  #
  #    SOCIAL_AUTH_HYDROSHARE_KEY: ''
  #    SOCIAL_AUTH_HYDROSHARE_SECRET: ''
  #
  #    SOCIAL_AUTH_ARCGIS_KEY: ''
  #    SOCIAL_AUTH_ARCGIS_SECRET: ''
  #
  #    SOCIAL_AUTH_ARCGIS_PORTAL_KEY: ''
  #    SOCIAL_AUTH_ARCGIS_PORTAL_SECRET: ''
  #    SOCIAL_AUTH_ARCGIS_PORTAL_URL: ''

  #  ANALYTICS_CONFIG:
  #    CLICKMAP_TRACKER_ID: False
  #    CLICKY_SITE_ID: False
  #    CRAZY_EGG_ACCOUNT_NUMBER: False
  #    GAUGES_SITE_ID: False
  #    GOOGLE_ANALYTICS_JS_PROPERTY_ID: False
  #    GOSQUARED_SITE_TOKEN: False
  #    HOTJAR_SITE_ID: False
  #    HUBSPOT_PORTAL_ID: False
  #    INTERCOM_APP_ID: False
  #    KISSINSIGHTS_ACCOUNT_NUMBER: False
  #    KISSINSIGHTS_SITE_CODE: False
  #    KISS_METRICS_API_KEY: False
  #    MIXPANEL_API_TOKEN: False
  #    OLARK_SITE_ID: False
  #    OPTIMIZELY_ACCOUNT_NUMBER: False
  #    PERFORMABLE_API_KEY: False
  #    PIWIK_DOMAIN_PATH: False
  #    PIWIK_SITE_ID: False
  #    RATING_MAILRU_COUNTER_ID: False
  #    SNAPENGAGE_WIDGET_ID: False
  #    SPRING_METRICS_TRACKING_ID: False
  #    USERVOICE_WIDGET_KEY: False
  #    WOOPRA_DOMAIN: False
  #    YANDEX_METRICA_COUNTER_ID: False

  #  EMAIL_CONFIG:
  #    EMAIL_BACKEND: 'django.core.mail.backends.smtp.EmailBackend'
  #    EMAIL_HOST: 'localhost'
  #    EMAIL_PORT: 25
  #    EMAIL_HOST_USER: ''
  #    EMAIL_HOST_PASSWORD: ''
  #    EMAIL_USE_TLS: False
  #    DEFAULT_FROM_EMAIL: 'Example <noreply@exmaple.com>'

  #  CHANNEL_LAYERS:
  #    default:
  #      BACKEND: channels.layers.InMemoryChannelLayer

  # Password validation
  # https://docs.djangoproject.com/en/1.9/ref/settings/#auth-password-validators
  #  AUTH_PASSWORD_VALIDATORS:
  #    - NAME: django.contrib.auth.password_validation.UserAttributeSimilarityValidator
  #    - NAME: django.contrib.auth.password_validation.MinimumLengthValidator
  #    - NAME: django.contrib.auth.password_validation.CommonPasswordValidator
  #    - NAME: django.contrib.auth.password_validation.NumericPasswordValidator

  # Django Guardian Settings
  #   GUARDIAN_RAISE_403: False  # Mutually exclusive with GUARDIAN_RENDER_403
  #   GUARDIAN_RENDER_403: False  # Mutually exclusive with GUARDIAN_RAISE_403
  #   GUARDIAN_TEMPLATE_403: ''
  #   ANONYMOUS_DEFAULT_USERNAME_VALUE: 'anonymous'

############################################################################
# SITE SETTINGS
# This section is applied when running the "tethys site -f" command.
#############################################################################
site_settings:
  GENERAL_SETTINGS:
    SITE_TITLE:
    FAVICON:
    BRAND_TEXT:
    BRAND_IMAGE:
    BRAND_IMAGE_HEIGHT:
    BRAND_IMAGE_WIDTH:
    BRAND_IMAGE_PADDING:
    APPS_LIBRARY_TITLE:
    PRIMARY_COLOR:
    SECONDARY_COLOR:
    BACKGROUND_COLOR:
    PRIMARY_TEXT_COLOR:
    PRIMARY_TEXT_HOVER_COLOR:
    SECONDARY_TEXT_COLOR:
    SECONDARY_TEXT_HOVER_COLOR:
    COPYRIGHT:
  HOME_PAGE:
    HERO_TEXT:
    BLURB_TEXT:
    FEATURE_1_HEADING:
    FEATURE_1_BODY:
    FEATURE_1_IMAGE:
    FEATURE_2_HEADING:
    FEATURE_2_BODY:
    FEATURE_2_IMAGE:
    FEATURE_3_HEADING:
    FEATURE_3_BODY:
    FEATURE_3_IMAGE:
    CALL_TO_ACTION:
    CALL_TO_ACTION_BUTTON:
  CUSTOM_STYLES:
    PORTAL_BASE_CSS:
    HOME_PAGE_CSS:
    APPS_LIBRARY_CSS:
    ACCOUNTS_BASE_CSS:
    LOGIN_CSS:
    REGISTER_CSS:
    USER_BASE_CSS:
  CUSTOM_TEMPLATES:
    HOME_PAGE_TEMPLATE:
    APPS_LIBRARY_TEMPLATE:
    LOGIN_PAGE_TEMPLATE:
    REGISTER_PAGE_TEMPLATE:
    USER_PAGE_TEMPLATE:

portal_config.yml Options:

  • version: Indicated the version of the portal_config.yml file. Current default : 1.0

  • name: Name of the portal

  • apps/<app-name>/services/persistent : List of persistent store settings in the app and the service to link to each.

  • apps/<app-name>/services/dataset : List of dataset settings in the app and the service to link to each.

  • apps/<app-name>/services/spatial : List of spatial persistent store settings in the app and the service to link to each.

  • apps/<app-name>/services/wps : List of web processing service settings in the app and the service to link to each.

  • apps/<app-name>/services/custom_settings : List of custom settings in the app and the value of each.

Settings in each of the service sections above will need to be listed in the following format:

python
<app_service_setting_name> : <service_name or id>

In the above example, catalog_db is the name of the setting in your app.py and test is the name of the service on the portal.

Tip

Run tethys gen portal_config to create a blank template of this file. By default the file will be saved to the $TETHYS_HOME directory.