ColdFront Plugin Demo

A simple demo plugin for ColdFront that will show compute usage from an external source. The demo is set up to read a Pandas dataframe containing usage for testing. In a production environment it may be more desirable to pull metrics from an external source of truth, such as XDMoD or a Prometheus server.

Installation

Clone the GitHub repository, e.g.

git clone git@github.com:SouthernMethodistUniversity/cf_plugin_demo.git

From your ColdFront repository,

uv add <path to>/cf_plugin_demo

Modify settings

Whenever possible, the recommended method of adding or changing settings in ColdFront is to utilize local settings. Local settings can be made using:

• local_settings.py relative to coldfront.config package
• /etc/coldfront/local_settings.py
• local_settings.py in the ColdFront project root

You can also specify the path to local_settings.py using the COLDFRONT_CONFIG environment variable. For example:

COLDFRONT_CONFIG=/opt/coldfront/mysettings.py

For more details, refer to the ColdFront configuration documentation.

Add plugin to ColdFront and add plugin settings

In the ColdFront project root directory, add the following to local_settings.py. You may need to make this file if it does not exist.

The following imports are needed:

from coldfront.config.base import SETTINGS_EXPORT, INSTALLED_APPS

Add an environment variable that enables the plugin to be turned on or off and add the plugin to the list of installed apps in ColdFront.

# -----------------------------------------------------------------------------
# Demo Plugin Functionality
# -----------------------------------------------------------------------------
CF_PLUGIN_DEMO_ENABLED = ENV.bool("CF_PLUGIN_DEMO_ENABLED", default=True)
SETTINGS_EXPORT += ["CF_PLUGIN_DEMO_ENABLED"]

# Add CF Plugin Demo to installed apps
if CF_PLUGIN_DEMO_ENABLED:
    INSTALLED_APPS += [
        "cf_plugin_demo"
    ]

Add plugin URLs to ColdFront

Additional URLs can be added to ColdFront using local URL settings that can be made at:

• local_urls.py relative to coldfront.config package
• /etc/coldfront/local_urls.py
• local_urls.py in the ColdFront project root

You can also specify the path to local_urls.py using the COLDFRONT_URLS environment variable. For example:

COLDFRONT_URLS=/opt/coldfront/myurls.py

In the ColdFront project root directory, add the following to local_urls.py. You may need to make this file if it does not exist.

The following imports are needed:

from django.conf import settings
from django.urls import path, include
from coldfront.config.urls import urlpatterns

The following will allow to the plugin urls to be visible at the prefix CENTER_BASE_URL/reports. You can name the link something other than "reports" if you wanted to.

# Enable plugin to be visible at CENTER_BASE_URL/reports
if "cf_plugin_demo" in settings.INSTALLED_APPS:
    urlpatterns.append(path("reports/", include("cf_plugin_demo.urls")))

Add links in the ColdFront Navigation

Finally, add links to the navigation bar (at this point the page is available at CENTER_BASE_URL/reports/stat-cards but is not linked.) In coldfront/templates/common/authorized_navbar.html add

        {% if settings.CF_PLUGIN_DEMO_ENABLED %}
          {% include 'cf_plugin_demo/navbar.html' %}
        {% endif %}

You can choose exactly where on the navigation bar you would like it to be based on the placement. One choice would be after the optional invoice menu:

        {% if settings.INVOICE_ENABLED %}
          {% if request.user.is_superuser or perms.allocation.can_manage_invoice %}
            {% include 'common/navbar_invoice.html' %}
          {% endif %}
        {% endif %}
        {% if settings.CF_PLUGIN_DEMO_ENABLED %}
          {% include 'cf_plugin_demo/navbar.html' %}
        {% endif %}
        {% if settings.CENTER_HELP_URL %}
          {% include 'common/navbar_help.html' %}
        {% endif %}

Running

In order to actually use the plugin, you will need data. In a real world example, this should probably come from an external source like XDMoD or a Prometheus server. For testing purposes, there is a sample data set available in src/cf_plugin_demo/data/cf_demo_data.feather.

For the plugin to see the data, you can set the environment variable:

CF_PLUGIN_DEMO_AGGREGATE_ACCOUNT_DF_PATH="<path to this repository>/src/cf_plugin_demo/data/cf_demo_data.feather"

Instead of an environment variable this path can also be set in local settings.

Available Settings

Setting	Description
CF_PLUGIN_DEMO_AGGREGATE_ACCOUNT_DF_PATH	Path to a Pandas dataframe containing usage information
CF_PLUGIN_DEMO_COMPUTE_ACCOUNT_ATTRIBUTE_NAME	Attribute name to associate to the "Account" in the usage information