explore optional dependency implementations

make all possible dependencies optional

tests passing

add min env file

add additional_url_patterns

add oauth2_provider

remove warning about user keys

Fix pygments lexer warnings in docs build

Add install dependency tip box to plot gizmos.

black formatting

fix lint

Removed lingering references to the old developer tools page

Add "Starting with Tethys 5.0..."

Update tutorial to require installing plotly

optional dep notes for Tethys Portal configuration
Fixes typo in GRAVATAR_DEFAULT_SECURE setting

Replace deprecated Axes setting in docs.
Note: settings.py is updated in master

docs for social_auth, mf2, and simple_captcha

Reviewed manual production configuration docs for optional args

REST API  and Terms and conditions optional deps

JSON Custom setting optional dependency docs

MapLayout and pyshp optional dependency.

document template tags

most optional dependencies documented

docs/installation.rst

@@ -23,7 +23,7 @@ a. To install the ``tethys-platform`` into a new conda environment then run the
 
 .. code-block:: bash
 
-    conda create -n tethys -c tethysplatform -c conda-forge tethys-platform
+    conda create -n tethys -c conda-forge tethys-platform
 
 .. tip::
 
@@ -33,9 +33,11 @@ a. To install the ``tethys-platform`` into a new conda environment then run the
 
     **Install Development Build**
 
-    To install the latest development build of ``tethys-platform`` add the ``tethysplatform/label/dev`` channel to the list of conda channels::
+    To install the latest development build of ``tethys-platform`` add the ``tethysplatform/label/dev`` channel to the list of conda channels:
 
-        conda create -n tethys -c tethysplatform/label/dev -c tethysplatform -c conda-forge tethys-platform
+        .. code-block:: bash
+
+            conda create -n tethys -c tethysplatform/label/dev -c conda-forge tethys-platform
 
     Alternatively, to install from source refer to the :ref:`developer_installation` docs.
 
@@ -51,7 +53,9 @@ Anytime you want to work with Tethys Platform, you'll need to activate the ``tet
 3. Create a :file:`portal_config.yml` File
 ------------------------------------------
 
-To add custom configurations such as the database and other local settings you will need to generate a :file:`portal_config.yml` file. To generate a new template :file:`portal_config.yml` run::
+To add custom configurations such as the database and other local settings you will need to generate a :file:`portal_config.yml` file. To generate a new template :file:`portal_config.yml` run:
+
+.. code-block:: bash
 
     tethys gen portal_config
 
@@ -61,20 +65,24 @@ You can customize your settings in the :file:`portal_config.yml` file after you
 4. Configure the Tethys Database
 --------------------------------
 
-Tethys Platform requires a PostgreSQL database server. There are several options for setting up a DB server: local, docker, or dedicated. For development environments you can use Tethys to create a local server::
+There are several options for setting up a DB server: local, docker, or remote. Tethys Platform uses a local SQLite database by default. For development environments you can use Tethys to create a local server:
+
+.. code-block:: bash
 
     tethys db configure
 
 .. note::
 
-    The tethys db command (:ref:`tethys_db_cmd`) will create a local database server in the directory specified by the ``DIR`` setting in the ``DATABASES`` section of the :file:`portal_config.yml` file. If the value of ``DIR`` is a relative path then the database server will be created relative to directory specified by the ``TETHYS_HOME`` environment variable. By default ``TETHYS_HOME`` is at `~/.tethys`.
+    The tethys db command (:ref:`tethys_db_cmd`) will create a local database file in the location specified by the ``NAME`` setting in the ``DATABASES`` section of the :file:`portal_config.yml` file (by default ``tethys_platform.sqlite``). If the value of ``NAME`` is a relative path then the database file will be created relative to directory specified by the ``TETHYS_HOME`` environment variable. By default ``TETHYS_HOME`` is at `~/.tethys`.
 
-    As an alternative to creating a local database server you can also configure a Docker DB server (see :ref:`using_docker`). A local database server is only recommended for development environments. For production environments please refer to :ref:`production_installation`.
+For additional options for configuring a database see :ref:`database_configuration`
 
 5. Start the Development Server
 -------------------------------
 
-Once you have a database successfully configured you can run the Tethys development server::
+Once you have a database successfully configured you can run the Tethys development server:
+
+.. code-block:: bash
 
     tethys manage start
 
@@ -84,7 +92,7 @@ This will start up a locally running web server. You can access the Tethys Porta
 
     You can customize the port that the server is running on by adding the ``-p`` option.
 
-    ::
+    .. code-block:: bash
 
         tethys manage start -p 8001
 
@@ -110,6 +118,7 @@ Related Docs
 
     installation/system_requirements
     tethys_portal/configuration
+    installation/database_configuration
     installation/conda
     installation/application
     installation/showcase_apps

docs/installation/application.rst

@@ -72,6 +72,18 @@ 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 `microtethys`, you will need to install these libraries using conda or pip as follows:
+
+    .. code-block:: bash
+
+        # conda: conda-forge channel strongly recommended
+        conda install -c conda-forge conda conda-libmamba-solver
+
+        # pip
+        pip install conda
+
 .. literalinclude:: resources/example-install.yml
    :language: yaml
 

docs/installation/production/docker/docker_compose.rst

@@ -305,7 +305,7 @@ c. Add the following contents to each ``.env`` file:
 
     **db.env**
 
-    .. code-block:: env
+    .. code-block:: docker
 
         # Password of the db admin account
         POSTGRES_PASSWORD=please_dont_use_default_passwords
@@ -323,7 +323,7 @@ c. Add the following contents to each ``.env`` file:
 
     **thredds.env**
 
-    .. code-block:: env
+    .. code-block:: docker
 
         # Password of the TDM admin user
         TDM_PW=please_dont_use_default_passwords
@@ -355,7 +355,7 @@ c. Add the following contents to each ``.env`` file:
 
     **web.env**
 
-    .. code-block:: env
+    .. code-block:: docker
 
         # Domain name of server should be first in the list if multiple entries added
         ALLOWED_HOSTS="\"[localhost]\""
@@ -471,7 +471,7 @@ a. Create a :file:`.gitignore` file:
 
 b. Add the following contents to the :file:`.gitignore` file to omit the contents of these directories from being tracked:
 
-    .. code-block:: gitignore
+    .. code-block:: text
 
         data/
         keys/

docs/installation/production/manual/configuration/advanced/lockout.rst

@@ -6,6 +6,18 @@ Lockout (Optional)
 
 **Last Updated:** May 2020
 
+.. important::
+
+    This feature requires the `django-axes` library to be installed. Starting with Tethys 5.0 or if you are using `microtethys`, you will need to install `django-axes` using conda or pip as follows:
+
+    .. code-block:: bash
+
+        # conda: conda-forge channel strongly recommended
+        conda install -c conda-forge django-axes
+
+        # pip
+        pip install django-axes
+
 Tethys Portal includes lockout capabilities to prevent brute-force login attempts. This capability is provided by the `Django Axes <https://django-axes.readthedocs.io/en/latest/>`_ add-on for Django. This document describes the different configuration options that are available for lockout capabilities in Tethys Portal.
 
 .. image:: ./images/locked_out.png

docs/installation/production/manual/configuration/advanced/multi_factor_auth.rst

@@ -6,6 +6,19 @@ Multi Factor Authentication (Optional)
 
 **Last Updated:** September 2020
 
+.. important::
+
+    These settings require the `django-mfa2`, `arrow`, and `isodate` libraries to be installed. Starting with Tethys 5.0 or if you are using `microtethys`, you will need to install these libraries using conda or pip as follows:
+
+    .. code-block:: bash
+
+        # conda: conda-forge channel strongly recommended
+        conda install -c conda-forge django-mfa2 arrow isodate
+
+        # pip
+        pip install django-mfa2 arrow isodate
+
+
 Tethys allows you to enable/enforce the use of multi factor authentication through apps such as LastPass Authenticator or Google Authenticator. This capability is provided by `Django MFA2 <https://github.com/mkalioby/django-mfa2/>`_. This tutorial will show you how to enable that functionality.
 
 

docs/installation/production/manual/configuration/advanced/social_auth.rst

@@ -6,6 +6,18 @@ Single Sign On (Optional)
 
 **Last Updated:** December 2020
 
+.. important::
+
+   This feature requires the `social-auth-app-django` library to be installed. Starting with Tethys 5.0 or if you are using `microtethys`, you will need to install `social-auth-app-django` using conda or pip as follows:
+
+   .. code-block:: bash
+
+      # conda: conda-forge channel strongly recommended
+      conda install -c conda-forge social-auth-app-django
+
+      # pip
+      pip install social-auth-app-django
+
 Tethys Portal supports authenticating users with several social authentication and single sign on providers such as Google, Facebook, and LinkedIn via the OAuth 2.0 method. The social authentication and authorization features have been implemented using the `Python Social Auth <http://psa.matiasaguirre.net/>`_ module. Social login is disabled by default, because enabling it requires registering your tethys portal instance with each provider.
 
 
@@ -187,7 +199,7 @@ Facebook
     b. Press the ``Setup`` button on the tile (or ``Settings`` if setup previously).
     c. Specify the following for the Valid OAuth Redirect URIs field:
 
-      ::
+      .. code-block::
 
           https://<SERVER_DOMAIN_NAME>/oauth2/complete/facebook/
 
@@ -245,7 +257,7 @@ Google
 
       As a security precaution, Google will only accept authentication requests from the hosts listed in the ``Authorized JavaScript Origins`` box. Add the domain of your Tethys Portal to the list. Optionally, you may add a localhost domain to the list to be used during testing:
 
-      ::
+      .. code-block::
 
           https://<SERVER_DOMAIN_NAME>
           http://localhost:8000
@@ -258,7 +270,7 @@ Google
 
       You also need to provide the callback URI for Google to call once it has authenticated the user. This follows the pattern ``http://<host>/oauth2/complete/google-oauth2/``:
 
-      ::
+      .. code-block::
 
           https://<SERVER_DOMAIN_NAME>/oauth2/complete/google-oauth2/
           https://localhost:8000/oauth2/complete/google-oauth2/
@@ -299,6 +311,18 @@ For more detailed information about using Google social authentication see the f
 HydroShare
 ----------
 
+.. important::
+
+    This feature requires the `hs_restclient` library to be installed. Starting with Tethys 5.0 or if you are using `microtethys`, you will need to install `hs_restclient` using conda or pip as follows:
+
+    .. code-block:: bash
+
+        # conda: conda-forge channel strongly recommended
+        conda install -c conda-forge hs_restclient
+
+        # pip
+        pip install hs_restclient
+
 1. Create a HydroShare Account
 
     You will need a HydroShare account to register your Tethys Portal with HydroShare. To create an account, visit `https://www.hydroshare.org <https://www.hydroshare.org>`_.
@@ -319,7 +343,7 @@ HydroShare
 
     g. Redirect uris: Add the call back URLs. The protocol (http or https) that matches your Tethys Portal settings should be included in this url. For example:
 
-    ::
+    .. code-block::
 
         if your Tethys Portal was located at the domain ``https://www.my-tethys-portal.com``:
             https://www.my-tethys-portal.com/oauth2/complete/hydroshare/
@@ -509,7 +533,7 @@ LinkedIn
 
     a. Add the call back URLs under the **OAuth 2.0 settings** section:
 
-        ::
+        .. code-block::
 
             https://<SERVER_DOMAIN_NAME>/oauth2/complete/linkedin-oauth2/
             http://localhost:8000/oauth2/complete/linkedin-oauth2/

docs/installation/production/manual/configuration/advanced/webanalytics.rst

@@ -4,9 +4,17 @@ Web Analytics (Optional)
 
 **Last Updated:** May 2020
 
-.. image:: ./images/webanalytics.png
-   :width: 300px
-   :align: right
+.. important::
+
+    This feature requires the `django-analytical` library to be installed. Starting with Tethys 5.0 or if you are using `microtethys`, you will need to install `django-analytical` using conda or pip as follows:
+
+    .. code-block:: bash
+
+        # conda: conda-forge channel strongly recommended
+        conda install -c conda-forge django-analytical
+
+        # pip
+        pip install django-analytical
 
 Tethys portals are configured to allow portal administrators to track how users interact with their portal and applications using web based analytical services. 24 services, including common services like Google Analytical and Optimizely, can be configured using the `Django-Analytical <https://github.com/jazzband/django-analytical>`_ package.
 

docs/installation/production/manual/configuration/basic/database.rst

@@ -4,11 +4,22 @@
 Production Database
 *******************
 
-**Last Updated:** September 2022
+**Last Updated:** September 2023
 
 In this part of the production deployment guide, you will learn how to initialize and configure the Tethys Portal database for production.
 
-1. Set Database Settings
+1. Install Python dependencies
+==============================
+
+Using a PostgreSQL database for production requires the ``psycopg2`` Python package. Also,  While we do not recommend having your database on the same server as Tethys Portal, the commands to automate setting up and configuring the database require that the PostgreSQL database and the `psycopg2` library be installed on the web server. Starting with Tethys 5.0 or if you are using `microtethys`, you will need to install `postgresql` and `psycopg2` using conda as follows:
+
+
+    .. code-block:: bash
+
+        # conda: conda-forge channel strongly recommended
+        conda install -c conda-forge postgresql psycopg2
+
+2. Set Database Settings
 ========================
 
 Set the database settings in the :file:`portal_config.yml` using the ``tethys settings`` command:
@@ -25,7 +36,7 @@ Set the database settings in the :file:`portal_config.yml` using the ``tethys se
 
         **DO NOT USE DEFAULT USERNAMES OR PASSWORDS FOR PRODUCTION DATABASE ACCOUNTS**
 
-2. Create Tethys Database and Database Users
+3. Create Tethys Database and Database Users
 ============================================
 
 Use the ``tethys db create`` command to create the database users and tables required by Tethys Portal:
@@ -42,7 +53,7 @@ Use the ``tethys db create`` command to create the database users and tables req
 
         **DO NOT USE DEFAULT USERNAMES OR PASSWORDS FOR PRODUCTION DATABASE ACCOUNTS**
 
-3. Create Tethys Database Tables
+4. Create Tethys Database Tables
 ================================
 
 Run the following command to create the Tethys database tables:
@@ -51,7 +62,7 @@ Run the following command to create the Tethys database tables:
 
       tethys db migrate
 
-4. Create Portal Admin User
+5. Create Portal Admin User
 ===========================
 
 You will need to create at least one Portal Admin account to allow you to login to your Tethys Portal. Create the account as follows:

docs/tethys_cli/db.rst

@@ -5,6 +5,23 @@ db command
 
 Setup and manage a Tethys database.
 
+.. important::
+
+    The default database configuration uses SQLite. Many of these commands are not applicable to SQLite databases are only support PostgreSQL databases. To use a PostgreSQL database be sure to set your settings accordingly. At the very least:
+
+    .. code-block:: bash
+
+        tethys settings --set DATABASES.default.ENGINE django.db.backends.postgresql
+
+    For more details see :ref:`database_configuration`
+
+    Additionally, the PostgreSQL database and the `psycopg2` library be installed. Starting with Tethys 5.0 or if you are using `microtethys`, you will need to install `postgresql` and `psycopg2` using conda as follows:
+
+    .. code-block:: bash
+
+        # conda: conda-forge channel strongly recommended
+        conda install -c conda-forge postgresql psycopg2
+
 .. argparse::
    :module: tethys_cli
    :func: tethys_command_parser

docs/tethys_cli/docker.rst

@@ -9,6 +9,14 @@ Manage Tethys-sponsored Docker containers. To learn more about Docker, see `What
 
     You must have Docker installed and add your user to the ``docker`` group to use the Tethys ``docker`` command (see: `Install Docker <https://docs.docker.com/install/>`_ and `Post-installation steps for Linux <https://docs.docker.com/install/linux/linux-postinstall/>`_).
 
+    Additionally, this feature requires the `docker-py` library to be installed. Starting with Tethys 5.0 or if you are using `microtethys`, you will need to install `docker-py` using conda as follows:
+
+    .. code-block:: bash
+
+        # conda: conda-forge channel strongly recommended
+        conda install -c conda-forge docker-py
+
+
 .. argparse::
    :module: tethys_cli
    :func: tethys_command_parser

docs/tethys_portal.rst

@@ -2,7 +2,7 @@
 Tethys Portal
 *************
 
-**Last Updated:** April 29, 2019
+**Last Updated:** August 2023
 
 Tethys Portal is the Django web site provided by Tethys Platform that acts as the runtime environment for apps. It leverages the capabilities of Django to provide the core website functionality that is often taken for granted in modern web applications. A description of the primary capabilities of Tethys Portal is provided in this section.
 
@@ -12,7 +12,6 @@ Tethys Portal is the Django web site provided by Tethys Platform that acts as th
    tethys_portal/configuration
    tethys_portal/admin_pages
    tethys_portal/tethys_users
-   tethys_portal/developer_tools
    tethys_portal/feedback