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
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
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
.
Name | Description |
---|---|
ALLOWED_HOSTS | A list of strings representing the host/domain names that ColdFront can serve. See here |
DEBUG | Turn on/off debug mode. Never deploy a site into production with DEBUG turned on. See here |
SECRET_KEY | This is used to provide cryptographic signing, and should be set to a unique, unpredictable value. See here. If you don't provide this one will be generated each time ColdFront starts. |
LANGUAGE_CODE | A string representing the language code. See here |
TIME_ZONE | A string representing the time zone for this installation. See here |
Q_CLUSTER_RETRY | The number of seconds Django Q broker will wait for a cluster to finish a task. See here |
Q_CLUSTER_TIMEOUT | The number of seconds a Django Q worker is allowed to spend on a task before it’s terminated. IMPORTANT NOTE: Q_CLUSTER_TIMEOUT must be less than Q_CLUSTER_RETRY. See here |
SESSION_INACTIVITY_TIMEOUT | Seconds of inactivity after which sessions will expire (default 1hr). This value sets the SESSION_COOKIE_AGE and the session is saved on every request. See here |
Template settings
Name | Description |
---|---|
STATIC_ROOT | Path to the directory where collectstatic will collect static files for deployment. See here |
SITE_TEMPLATES | Path to a directory of custom templates. Add custom templates here. This path will be added to TEMPLATES DIRS. See here |
SITE_STATIC | Path to a directory of custom static files. Add custom css here. This path will be added to STATICFILES_DIRS See here |
ColdFront core settings
The following settings are ColdFront specific settings related to the core application.
Name | Description |
---|---|
CENTER_NAME | The display name of your center |
CENTER_HELP_URL | The URL of your help ticketing system |
CENTER_PROJECT_RENEWAL_HELP_URL | The URL of the article describing project renewals |
CENTER_BASE_URL | The base URL of your center. |
PROJECT_ENABLE_PROJECT_REVIEW | Enable or disable project reviews. Default True |
ALLOCATION_ENABLE_ALLOCATION_RENEWAL | Enable or disable allocation renewals. Default True |
ALLOCATION_DEFAULT_ALLOCATION_LENGTH | Default number of days an allocation is active for. Default 365 |
ALLOCATION_ENABLE_CHANGE_REQUESTS_BY_DEFAULT | Enable or disable allocation change requests. Default True |
ALLOCATION_CHANGE_REQUEST_EXTENSION_DAYS | List of days users can request extensions in an allocation change request. Default 30,60,90 |
ALLOCATION_ACCOUNT_ENABLED | Allow user to select account name for allocation. Default False |
ALLOCATION_RESOURCE_ORDERING | Controls the ordering of parent resources for an allocation (if allocation has multiple resources). Should be a list of field names suitable for Django QuerySet order_by method. Default is ['-is_allocatable', 'name']; i.e. prefer Resources with is_allocatable field set, ordered by name of the Resource. |
INVOICE_ENABLED | Enable or disable invoices. Default True |
ONDEMAND_URL | The URL to your Open OnDemand installation |
LOGIN_FAIL_MESSAGE | Custom message when user fails to login. Here you can paint a custom link to your user account portal |
ENABLE_SU | Enable administrators to login as other users. Default True |
Database settings
The following settings configure the database server to use, if not set will default to using SQLite:
Name | Description |
---|---|
DB_URL | The database connection url string |
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:
Name | Description |
---|---|
EMAIL_ENABLED | Enable/disable email. Default False |
EMAIL_HOST | Hostname of smtp server |
EMAIL_PORT | smtp port |
EMAIL_HOST_USER | Username for smtp |
EMAIL_HOST_PASSWORD | password for smtp |
EMAIL_USE_TLS | Enable/disable tls. Default False |
EMAIL_SENDER | Default sender email address |
EMAIL_SUBJECT_PREFIX | Prefix to add to subject line |
EMAIL_ADMIN_LIST | List of admin email addresses. |
EMAIL_TICKET_SYSTEM_ADDRESS | Email address of ticketing system |
EMAIL_DIRECTOR_EMAIL_ADDRESS | Email address for director |
EMAIL_PROJECT_REVIEW_CONTACT | Email address of review contact |
EMAIL_DEVELOPMENT_EMAIL_LIST | List of emails to send when in debug mode |
EMAIL_OPT_OUT_INSTRUCTION_URL | URL of article regarding opt out |
EMAIL_SIGNATURE | Email signature to add to outgoing emails |
EMAIL_ALLOCATION_EXPIRING_NOTIFICATION_DAYS | List of days to send email notifications for expiring allocations. Default 7,14,30 |
EMAIL_ADMINS_ON_ALLOCATION_EXPIRE | Setting this to True will send a daily email notification to administrators with a list of allocations that have expired that day. |
Plugin settings
For more info on ColdFront plugins (Django apps)
LDAP Auth
Required
LDAP authentication backend requires ldap3
and django_auth_ldap
.
$ pip install ldap3 django_auth_ldap
Name | Description |
---|---|
PLUGIN_AUTH_LDAP | Enable LDAP Authentication Backend. Default False |
AUTH_LDAP_SERVER_URI | URI of LDAP server |
AUTH_LDAP_START_TLS | Enable/disable start tls. Default True |
AUTH_LDAP_BIND_DN | The distinguished name to use when binding to the LDAP server |
AUTH_LDAP_BIND_PASSWORD | The password to use AUTH_LDAP_BIND_DN |
AUTH_LDAP_USER_SEARCH_BASE | User search base dn |
AUTH_LDAP_GROUP_SEARCH_BASE | Group search base dn |
AUTH_LDAP_MIRROR_GROUPS | Enable/disable mirroring of groups. Default True |
AUTH_LDAP_BIND_AS_AUTHENTICATING_USER | Authentication will leave the LDAP connection bound as the authenticating user, rather than forcing it to re-bind. Default False |
OpenID Connect Auth
Required
OpenID Connect authentication backend requires mozilla_django_oidc
.
$ pip install mozilla_django_oidc
Name | Description |
---|---|
PLUGIN_AUTH_OIDC | Enable OpenID Connect Authentication Backend. Default False |
OIDC_OP_JWKS_ENDPOINT | URL of JWKS endpoint |
OIDC_RP_SIGN_ALGO | Signature algorithm |
OIDC_RP_CLIENT_ID | Client ID |
OIDC_RP_CLIENT_SECRET | Client secret |
OIDC_OP_AUTHORIZATION_ENDPOINT | OAuth2 authorization endpoint |
OIDC_OP_TOKEN_ENDPOINT | OAuth2 token endpoint |
OIDC_OP_USER_ENDPOINT | OAuth2 userinfo endpoint |
OIDC_VERIFY_SSL | Verify ssl Default True |
OIDC_RENEW_ID_TOKEN_EXPIRY_SECONDS | Token lifetime in seconds. Default 3600 |
Mokey
Required
Mokey depends on the OpenID Connect plugin above. You must also enable the
OpenID Connect plugin via PLUGIN_AUTH_OIDC=True
.
Name | Description |
---|---|
PLUGIN_MOKEY | Enable Mokey/Hydra OpenID Connect Authentication Backend. Default False |
Slurm
Name | Description |
---|---|
PLUGIN_SLURM | Enable Slurm integration. Default False |
SLURM_SACCTMGR_PATH | Path to sacctmgr command. Default /usr/bin/sacctmgr |
SLURM_NOOP | Enable/disable noop. Default False |
SLURM_IGNORE_USERS | List of user accounts to ignore when generating Slurm associations |
SLURM_IGNORE_ACCOUNTS | List of Slurm accounts to ignore when generating Slurm associations |
XDMoD
Name | Description |
---|---|
PLUGIN_XDMOD | Enable XDMoD integration. Default False |
XDMOD_API_URL | URL to XDMoD API |
FreeIPA
Name | Description |
---|---|
PLUGIN_FREEIPA | Enable FreeIPA integration. Default False |
FREEIPA_KTNAME | Path to keytab file |
FREEIPA_SERVER | Hostname of FreeIPA server |
FREEIPA_USER_SEARCH_BASE | User search base dn |
FREEIPA_ENABLE_SIGNALS | Enable/Disable signals. Default False |
iquota
Name | Description |
---|---|
PLUGIN_IQUOTA | Enable iquota integration. Default False |
IQUOTA_KEYTAB | Path to keytab file |
IQUOTA_CA_CERT | Path to ca cert |
IQUOTA_API_HOST | Hostname of iquota server |
IQUOTA_API_PORT | Port of iquota server |
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.
Required
LDAP User Search requires ldap3
.
$ pip install ldap3
Name | Description |
---|---|
PLUGIN_LDAP_USER_SEARCH | Enable LDAP User Search. Default False |
LDAP_USER_SEARCH_SERVER_URI | URI of LDAP server |
LDAP_USER_SEARCH_BIND_DN | The distinguished name to use when binding to the LDAP server |
LDAP_USER_SEARCH_BIND_PASSWORD | The password to use LDAP_USER_SEARCH_BIND_DN |
LDAP_USER_SEARCH_BASE | User search base dn |
LDAP_USER_SEARCH_CONNECT_TIMEOUT | Time in seconds to wait before timing out. Default 2.5 |
LDAP_USER_SEARCH_USE_SSL | Whether to use ssl when connecting to LDAP server. Default True |
LDAP_USER_SEARCH_USE_TLS | Whether to use tls when connecting to LDAP server. Default False |
LDAP_USER_SEARCH_PRIV_KEY_FILE | Path to the private key file. |
LDAP_USER_SEARCH_CERT_FILE | Path to the certificate file. |
LDAP_USER_SEARCH_CACERT_FILE | Path to the CA cert file. |
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