Configuration

ColdFront can be configured via environment variables, an environment file, or a python file which can be used for more advanced configuration settings. This document covers the configuration settings available in ColdFront and the core plugins. For information on installing ColdFront see here.

Configuration files

You can set environment variables via a file and ColdFront by default will look for the following files:

• .env in the ColdFront project root
• /etc/coldfront/coldfront.env

Note: You can check your project root with the following command:

coldfront diffsettings | grep PROJECT_ROOT

You can also specify the path to an environment file using the COLDFRONT_ENV environment variable. For example

COLDFRONT_ENV=/opt/coldfront/coldfront.env

For more advanced configurations, you can create a python file to override ColdFront settings:

• 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 URL configurations, you can create a python file to override ColdFront URLs:

• 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

Simple Example

Here's a very simple example demonstrating how to configure ColdFront using environment variables:

$ tee coldfront.env <<EOF
DEBUG=True
CENTER_NAME='University HPC'
PROJECT_ENABLE_PROJECT_REVIEW=False
DB_URL='mysql://user:password@127.0.0.1:3306/database'
EOF

$ COLDFRONT_ENV=coldfront.env coldfront runserver

Configuration Variables

Base settings

The following settings allow overriding basic ColdFront Django settings. For more advanced configuration use local_settings.py.

Template settings

ColdFront core settings

The following settings are ColdFront specific settings related to the core application.

Database settings

The following settings configure the database server to use, if not set will default to using SQLite:

Examples:

DB_URL=mysql://user:password@127.0.0.1:3306/database
DB_URL=psql://user:password@127.0.0.1:5432/database
DB_URL=sqlite:////usr/share/coldfront/coldfront.db

Email settings

The following settings configure emails in ColdFront. By default email is disabled:

Plugin settings

For more info on ColdFront plugins (Django apps)

LDAP Auth

$ pip install ldap3 django_auth_ldap

OpenID Connect Auth

$ pip install mozilla_django_oidc

Mokey

Slurm

XDMoD

FreeIPA

iquota

LDAP User Search

This plugin allows searching for users via LDAP. This has nothing to do with authentication. This allows users who haven't yet logged into ColdFront but exist in your backend LDAP to show up in the ColdFront user search.

$ pip install ldap3

Project OpenLDAP

This plugin allows for projects and project membership to be synced to an OpenLDAP server. See coldfront/coldfront/plugins/project_openldap/README.md in the source code for more detailed information.

Auto Compute Allocation

Advanced Configuration

ColdFront uses the Django settings. In most cases, you can set custom configurations via environment variables above. If you need more control over the configuration you can create /etc/coldfront/local_settings.py or create a local_settings.py file in the coldfront project root to override any Django settings. Some examples:

Instead of setting the DB_URL environment variable, we can add a custom database configuration:

DATABASES = {
    'default': {
        'ENGINE': 'django.db.backends.mysql',
        'NAME': 'coldfront',
        'USER': '',
        'PASSWORD': '',
        'HOST': 'localhost',
        'PORT': '',
    },
}

To authenticate against Active Directory, it's not uncommon to need the OPT_REFERRALS set to 0. Likewise, we should look for users based on their sAMAccountName attribute, rather than uid.

AUTH_LDAP_CONNECTION_OPTIONS={ldap.OPT_REFERRALS: 0}
AUTH_LDAP_BASE_DN = 'dc=example,dc=org' # same value as AUTH_LDAP_USER_SEARCH
AUTH_LDAP_USER_SEARCH = LDAPSearch(
    AUTH_LDAP_BASE_DN, ldap.SCOPE_SUBTREE, '(sAMAccountName=%(user)s)')

Additional debug logging can be configured for troubleshooting. This example attaches the django_auth_ldap logs to the primary Django logger so you can see debug those logs in your main log output.

LOGGING = {
    "version": 1,
    "disable_existing_loggers": False,
    "handlers": {"console": {"class": "logging.StreamHandler"}},
    "loggers": {"django_auth_ldap": {"level": "DEBUG", "handlers": ["console"]}
},

Custom Branding

The default HTML templates and css can be easily customized to add your own site specific branding or even modify the functionality of ColdFront. To override the stock templates in ColdFront, create a directory and add your custom templates. By default, ColdFront will look in /usr/share/coldfront/site/templates and /usr/share/coldfront/site/static. If you'd like to use a different directory then be sure to set the following environment variable:

SITE_TEMPLATES=/path/to/your/templates

You can also override any static files such as CSS or images by creating a directory and adding your custom static assets. Then set the following environment variable:

SITE_STATIC=/path/to/static/files

To apply changes in a production environment (where the static files are served through an nginx or apache server), rerun collectstatic. Be sure to activate your virtual environment first if you're using one.

source /srv/coldfront/venv/bin/activate
coldfront collectstatic

As a simple example, to change the default background color from blue to black, create a common.css file with the following styles and set the SITE_STATIC environment variable when starting ColdFront:

$ mkdir -p site/static/common/css
$ tee site/static/common/css/common.css <<EOF
.bg-primary {
  background-color: #000 !important;
}
EOF

$ DEBUG=True SITE_STATIC=site/static coldfront runserver