Configuration¶
SLM is built on Django which means all of the configuration directives available on Django and on the application stack that comprise SLM are available. SLM provides additional directives referenced here to customize its behavior and operational configuration.
Django configuration directives are defined in a settings file which is just a normal python file.
You should first familiarize yourself with how
Django configuration works. The configuration directives in a
settings file are python variables of any type named in all caps. The python import path to this
configuration file must appear in the DJANGO_SETTINGS_MODULE environment variable.
After Django is bootstrapped you can access a configuration directive like so:
from django.conf import settings
settings.DIRECTIVE_NAME
One of the most important things to understand about configuring the SLM is that there are two main semantic flavors of configuration directive:
- Directives that configure the operational environment. For example:
where to find the database
debugging toggles
security toggles
- Directives that customize functionality. For example:
password requirements
sitelog field validation routines
station naming conventions
installed Django applications
The amount of customization you need to do to the SLM will inform how you configure and deploy your instance. For simple installations that make no behavioral customizations and that do not install any additional packages you most likely will not have to write any settings files and configuring the SLM via environment variables will be sufficient. Otherwise you will need to familiarize yourself with how the SLM builds its settings file.
Simple Environment Settings¶
By default the SLM will load environment variables from a file if it can find one. It will look, in order, for a file at:
The file path in the
SLM_ENVenvironment variable (or settings variable) if it exists.The file located at
django.conf.settings.BASE_DIR/ “.env” if it exists.
Environment variables in the process environment have higher precedence than those defined in files.
For example a minimal set of settings to instantiate a functional SLM might look like:
DJANGO_SETTINGS_MODULE="slm.settings.root"
Tip
DJANGO_SETTINGS_MODULE will always need to be defined in the process environment because
it is required before the environment file load is attempted.
# this could be defined in your process env or in BASE_DIR / .env
BASE_DIR="/var/www/sites/slm/production"
ADMINS="You <you@yourcompany.com>"
SLM_SITE_NAME="slm.yourcompany.com"
SLM_ORG_NAME="Your Company"
Building Settings Files¶
Django does not enforce any particular configuration design pattern, but the SLM does. We use two third party extensions:
django-split-settings to compose settings from multiple files. There are a lot of settings directives and this allows us to namespace like with like directives.
django-environ to allow environment variables to override select operational directives.
If you need to customize SLM behavior and build more complex settings directives, we highly recommend using slm-startproject to scaffold out your project and its settings files. Even if you do not ultimately use our recommended configuration, seeing how we lay out an SLM project may be of some help.
We use split_settings.tools.include() instead of
the import system to combine settings files. There are additional
tools that make splitting settings files up more easy in slm.settings. Once you’ve defined
your base settings file, that is the file that will be set in DJANGO_SETTINGS_MODULE, you
will need to import the SLM’s root settings file. A notional settings file might look like this:
from pathlib import Path
from split_settings.tools import include
from slm.settings import resource
# A few settings must be defined before including root
# These may be defined here or in the environment or environment files
BASE_DIR = Path("/var/www/path/to/your/site/directory")
SLM_SITE_NAME = "slm.yourdomain.org"
SLM_ORG_NAME = "Your Organization"
# Settings defined above (before inclusion of root) may be overridden
# by environment variables if they support being read from the environment
# include SLM default settings. Any setting defined before this
# will take precedence over the defaults defined by the SLM
include(resource("slm.settings", "root.py"))
# Settings defined here or later have the highest precedence
# After root is included you may read or override defaults, or
# make adjustments, like adding to or removing parts of complex settings
# For example, to add another app to the stack:
INSTALLED_APPS = [
"your_app",
*get_setting("INSTALLED_APPS"),
]
# or add another database:
DATABASES = {
**get_setting("DATABASES"),
"my_db": ...
}
Override Precedence¶
Setting definitions will have the following override precedence:
Defined in settings files after inclusion of
slm.settings.root.Defined in the process environment (for Environment Settings ⚙️).
Defined in environment files (for Environment Settings ⚙️).
Defined in settings files before inclusion of
slm.settings.root.Default settings defined in
slm.settings.root.
Environment Settings ⚙️¶
The following settings may be overridden by environment variables:
Setting |
Type |
Example |
|---|---|---|
|
|
|
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
250 |
||
|
||
256 |
Types¶
Path¶
We do not use django-environ’s environ.Path class. Instead we use the
Path from the stdlib. If a setting is a path setting from Django core we
convert it to a str.
All relative paths will be resolved relative to BASE_DIR
bool()¶
Environment booleans will resolve to true if they make a case insensitive match to any of the following strings:
('true', 'on', 'ok', 'y', 'yes', '1')
list()¶
Lists should be comma delineated. E.g.: "item1,item2,item3"
Environment Only Settings¶
These settings will not appear in django.conf.settings and are used to bootstrap parts
of the SLM before settings have finished resolving.
This must be the import path to your entry settings files which will usually be the file that
imports slm.settings.root or, if the defaults with environment overrides are enough you may
set this directly to slm.settings.root. Python must be able to import this file. If you are
getting import errors check your PYTHONPATH.
- SLM_MANAGEMENT_FLAG¶
The SLM by default may behave slightly differently depending on if it is running in an http
web serving context or if it has been invoked on the command line. For example, by default we
change the log file names based on this so it is easier to see what work was being done in
process as opposed to during administrative tasks. When the SLM_MANAGEMENT_FLAG is set in the
process environment (not in an environment file), the SLM will set the
SLM_MANAGEMENT_MODE setting to True.
Settings¶
We list settings that are unique to the SLM, or settings from Django or our dependencies where we have redefined the defaults.
BASE_DIR ⚙️ 🚨¶
Default: Not Defined
This setting is required and must be an absolute path. It is not an official Django setting,
but appears in the docs examples and is very common by convention. Think of it as the working
directory of your running SLM. Directories such as SLM_LOG_DIR will default to sub paths
of this directory.
SLM_ENV ⚙️¶
Default: Not Defined
The path to an optional environment file that will be loaded by the root settings. You
may specify this setting as an environment variable or as a file setting before you include
slm.settings.root.
SLM_DATABASE ⚙️¶
Default: postgis:///slm
Warning
The SLM requires that the default database be PostgreSQL with the PostGIS extension enabled.
This should be a database url string.
Use this setting to tell the SLM how to find it’s default database. This is the database where all the tables defined in igs-slm will be stored, as well as any other tables that are not routed to other databases.
This setting is optional, by default, the SLM will look for a database called slm, and it
will use the username of the running process to connect to that database without a password over a
socket. This will work if postgres is configured for peer authentication and the running user has the correct
privileges.
SLM_CACHE ⚙️¶
Default: locmemcache://
The default cache configuration to use specified as a cache url.
When slm.settings.root is included configuration directives derived from this setting will
be added to any part of the default cache already specified.
SLM_SITE_NAME ⚙️¶
Default: ALLOWED_HOSTS[0] or "" (Empty String)
The domain name of your site without the scheme. e.g. “slm.igs.org”. If undefined, and
ALLOWED_HOSTS is not empty, the first entry in ALLOWED_HOSTS will be used.
When routine deploy or set_site is run this setting will be set
into the default Site
domain attribute.
SLM_ORG_NAME ⚙️¶
Default: "SLM"
The name of your organization. This will appear in some of the HTML templates and email
communications. When routine deploy or set_site is run
this setting will be set into the default Site
name attribute.
SLM_DEBUG_TOOLBAR ⚙️¶
Default: DEBUG
Never enable this in production.
Enable or disable the django-debug-toolbar. By default it will be enabled if
the django-debug-toolbar is installed and DEBUG is true.
SLM_IGS_VALIDATION ⚙️¶
Default: True
Use the default IGS log validation rules. If False no validation
will be performed on site log values other than basic database column type checks.
SLM_COORDINATE_MODE ⚙️¶
Default: INDEPENDENT
Site logs contain position fields in both lat/lon/height and xyz (ECEF). By default the SLM will allow users to specify these values indepenendently. Optionally it can be configured to compute one from the other using the ITRF2020 ellipsoid parameters:
Behavior |
|
|---|---|
User specifies station coordinates in ECEF and LLH seperately. |
|
User specifies station coordinates in ECEF, LLH coordinates are calculated by the system. |
|
User specifies station coordinates in LLH, ECEF coordinates are calculated by the system. |
from slm.defines import CoordinateMode
SLM_COORDINATE_MODE = CoordinateMode.ECEF
If using IGS validation rules there is also a validator that will throw warnings if these coordinates differ by more than 1 meter in three dimensions.
SLM_SECURITY_DEFAULTS ⚙️¶
Default: not DEBUG
Use the default production security settings form the SLM. This sets the following:
SECURE_SSL_REDIRECT= TrueCSRF_COOKIE_SECURE= TrueSESSION_COOKIE_SECURE= TrueSECURE_REFERRER_POLICY= “origin”X_FRAME_OPTIONS= “DENY”
SLM_ADMIN_MAP ⚙️¶
Default: True
Enable or disable the MapBox admin map in the SLM. Must be set in the environment
or prior to the inclusion of slm.settings.root. You may also enable or disable
the admin map by adding or removing slm.map from INSTALLED_APPS.
SLM_IGS_STATION_NAMING ⚙️¶
Default: False
Enable or disable the use of IGS naming rules for station names. If enabled, the defaults for
SLM_STATION_NAME_REGEX and SLM_STATION_NAME_HELP will be set to:
SLM_STATION_NAME_REGEX = r"[\w]{4}[\d]{2}[\w]{3}"
SLM_STATION_NAME_HELP = _(
"This is the 9 Character station name (XXXXMRCCC) used in RINEX 3 "
"filenames Format: (XXXX - existing four character IGS station "
"name, M - Monument or marker number (0-9), R - Receiver number "
"(0-9), CCC - Three digit ISO 3166-1 country code)"
)
SLM_STATION_NAME_REGEX¶
Default: None
Provide a regular expression to validate new station names against. By default no validation occurs and station names may be any string up to 50 characters in length.
For example the IGS station name standard uses this regular expression:
SLM_STATION_NAME_REGEX = r"[\w]{4}[\d]{2}[\w]{3}"
SLM_STATION_NAME_HELP¶
Default: "The name of the station."
Override the help text used for station name field. Useful if you have a custom naming convention that requires explanation.
SLM_MANAGEMENT_MODE¶
Default: True if SLM_MANAGEMENT_FLAG is set, False otherwise.
This setting will be True when the SLM is running in the context of a management command
and False when running in the context of web serving. It is mostly used to make log file
changes.
SLM_EMAIL_SERVER ⚙️¶
Default: smtp://localhost:25
An email server url that will handle outgoing email traffic. This setting will be used to set the following Django settings:
SERVER_EMAIL ⚙️¶
Default: noreply@domain where domain is SLM_SITE_NAME or localhost
We provide a more reasonable default than Django’s SERVER_EMAIL.
DEFAULT_FROM_EMAIL ⚙️¶
Default: SERVER_EMAIL
We provide a more reasonable default than Django’s DEFAULT_FROM_EMAIL.
WSGI_APPLICATION ⚙️¶
Default: slm.wsgi.application
We set a default for WSGI_APPLICATION that works if either:
The
DJANGO_SETTINGS_MODULEisslm.settings.rootThe
DJANGO_SETTINGS_MODULEis set in the environment of the process that loads Django for web serving.You are not using WSGI - e.g. in a local development or debug context using
runserver.
This should work for most installations, only override it if it does not.
ALLOWED_HOSTS ⚙️¶
- Default:
DEBUG=False:[SLM_SITE_NAME]DEBUG=True:["localhost", "127.0.0.1", "[::1]"]
We override the empty default of ALLOWED_HOSTS with reasonable options.
Tip
In production you will likely have to add the IP address of your production machine to the list.
ROOT_URLCONF¶
Default: slm.settings.urls
We override the Django default setting ROOT_URLCONF of not defined.
With the basic SLM urls. If you need to add any urls you should override this and provide your
own urls python file.
STATIC_ROOT ⚙️¶
Default: BASE_DIR /static
This is where all statically served file asserts will live. These files are normally served by the webserver above Django on the stack.
We override the Django default setting STATIC_ROOT of None. If the directory
does not exist and it is a sub directory of BASE_DIR the SLM will create it.
MEDIA_ROOT ⚙️¶
Default: BASE_DIR /media
This is where all uploaded and dynamically generated file artifacts will be stored.
We override the Django default setting django: MEDIA_ROOT of None. If the directory
does not exist and it is a sub directory of BASE_DIR the SLM will create it.
SLM_SECRETS_DIR ⚙️¶
Default: BASE_DIR /secrets
The directory where secrets are kept. If there is a file named secret_key in this directory it
will be read into SECRET_KEY if that setting is unset. If that file does not exist
the SLM will generate a random key on startup.
SLM_LOG_LEVEL ⚙️¶
- Default:
DEBUG=True:
DEBUGDEBUG=False:
INFO
Set the default log level for loggers. This may be any of the
standard library logging levels and also TRACE.
SLM_LOG_DIR ⚙️¶
The directory where file logs will be stored. If this directory does not exist but is a sub path
of BASE_DIR it will be created.
LOGGING¶
We use the python stdlib logging module for logging. The Django
documentation also covers logging. See also Django’s
LOGGING and LOGGING_CONFIG.
Our default configuration has the following qualities:
Most loggers will be set to the
SLM_LOG_LEVELlevel. Some particularly noisy or unnecessary loggers will be set to higher levels.A
TimedRotatingFileHandlerfile handler will be created that rotates files every night at midnight and keeps 14 days worth of logs. The logs will be stored atSLM_LOG_DIR/SLM_SITE_NAME.logAn
AdminEmailHandlerwill be created that emailsADMINSwith an error report anytime a log statement atERRORor higher is issued.If
SLM_MANAGEMENT_MODEis on, log files will have_manageappended to their names.
MESSAGE_LEVEL¶
Default:
DEBUG=True:
DEBUGDEBUG=False:
INFO
We override the base Django default setting MESSAGE_LEVEL of INFO.
SLM_ALERT_COLORS¶
Default:
Color |
|
|---|---|
|
|
|
|
|
from slm.defines import AlertLevel
SLM_ALERT_COLORS = {
AlertLevel.NOTICE: "#12CAF0",
AlertLevel.WARNING: "#E3AA00",
AlertLevel.ERROR: "#DD3444",
}
Customize the color used in the web interface to represent alerts at different levels.
SLM_STATUS_COLORS¶
Default:
from slm.defines import SiteLogStatus
SLM_STATUS_COLORS = {
SiteLogStatus.FORMER: "#3D4543",
SiteLogStatus.SUSPENDED: "#E0041A",
SiteLogStatus.PROPOSED: "#913D88",
SiteLogStatus.UPDATED: "#0079AD",
SiteLogStatus.PUBLISHED: "#0D820D",
SiteLogStatus.EMPTY: "#D3D3D3"
}
Customize the color used in the web interface to represent site log status states.
SLM_FILE_COLORS¶
Default:
Color |
|
|---|---|
|
|
|
|
|
|
|
|
|
from slm.defines import SiteFileUploadStatus
SLM_FILE_COLORS = {
SiteFileUploadStatus.UNPUBLISHED: "#0079AD",
SiteFileUploadStatus.PUBLISHED: "#0D820D",
SiteFileUploadStatus.INVALID: "#8b0000",
SiteFileUploadStatus.WARNINGS: "#E3AA00",
SiteFileUploadStatus.VALID: "#0D820D"
}
Customize the color used in the web interface to represent file upload status states.
SLM_FILE_ICONS¶
Default:
Mime type |
Icon |
|---|---|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
SLM_FILE_ICONS = {
"zip": "bi bi-file-zip",
"x-tar": "bi bi-file-zip",
"plain": "bi bi-filetype-txt",
"jpeg": "bi bi-filetype-jpg",
"svg+xml": "bi bi-filetype-svg",
"xml": "bi bi-filetype-xml",
"json": "bi bi-filetype-json",
"png": "bi bi-filetype-png",
"tiff": "bi bi-filetype-tiff",
"pdf": "bi bi-filetype-pdf",
"gif": "bi bi-filetype-gif",
"csv": "bi bi-filetype-csv",
"bmp": "bi bi-filetype-bmp",
"vnd.openxmlformats-officedocument.wordprocessingml.document": "bi bi-filetype-doc",
"msword": "bi bi-filetype-doc",
}
Customize the icons used in the web interface to represent specific file mimetypes. These icons will render as:
<i class="{icon}"></i>
SLM_THUMBNAIL_SIZE ⚙️¶
Default: 250
The width in pixels of thumbnail previews of images generated by the SLM.
SLM_LEGACY_PLACEHOLDERS ⚙️¶
Default: True
If true, include a final placeholder section in renderings of the ASCII legacy formats of the site logs.
SLM_MAX_UPLOAD_SIZE_MB ⚙️¶
Default: 100
The maximum allowed upload file size. Arbitrary files may be attached to stations.
SLM_HTTP_PROTOCOL¶
Default:
DEBUG=True:
httpDEBUG=False:
https
In the event the SLM needs to build a link without a request object to determine which http scheme it should use, use this scheme.
SLM_PERMISSIONS¶
Default: slm.authentication.default_permissions
This setting tells the SLM which permissions are pertinent to its functionality.
We use Django’s permission framework
to control user access to certain functionality. If you wish to add your own permissions you may
set this directive to the import path of a function that returns a
Permission QuerySet. The SLM
will use this in the admin as the set of user permissions that should be offered on the user change
forms. Superfluous permissions will be hidden.
SLM_DEFAULT_PERMISSION_GROUPS¶
Default: {"Agency Manager": ["propose_sites", "moderate_sites"]}
We use the Django permission framework to open up certain functionality to users.
This setting creates named groups of permissions that are shown on the user admin forms.
Permissions groups can be thought of as user roles. We create an Agency Manager role by default
that allows its members to propose new sites for their agency and publish (moderate) site logs for
sites belonging to their agency.
This setting must be a dictionary where the group name is the key and the values are lists of
permission code names.
SLM_PRELOAD_SCHEMAS¶
Default:
DEBUGorSLM_MANAGEMENT_MODE:[](Empty List)not
DEBUG:list(GeodesyMLVersion)
The xsd schemas that should be preloaded on start - if a schema is used that is not preloaded it will be lazily loaded which can take some time and will prolong the request. It can be useful to disable this during testing to reduce load times. It is recommended to leave this set to the default setting in production.
When set to a list these should be instances of GeodesyMLVersion.
This setting may also be a falsey value, in which case no preloads will be attempted.
SLM_EMAILS_REQUIRE_LOGIN¶
Default: True
By default the SLM will not send moderation related emails to user accounts who have never logged in, set this to False to disable this behavior. This does not apply to account related emails like password reset requests. Moderation emails include notices like site log review requests and publish events.
SLM_FILE_DOMAIN¶
Default: None
Sets the domain used to generate links to the SLM station attachments including images and files. Any standalone artifacts produced by the slm that include links to files served by the SLM will use this domain as the stem. If empty the default site domain will be used. You probably do not need to set this field unless you are serving files off a different instance than the instance that generates serialized artifacts.
SLM_AUTOMATED_ALERTS¶
Use this setting to control when automated email alert system.
Todo
Describe this setting.
SLM_VALIDATION_BYPASS_BLOCK¶
Default: False
Toggling this off will prevent any validation configured to block edit saves from doing so - instead flags will be issued.
SLM_REQUIRED_SECTIONS_TO_PUBLISH¶
Default:
SLM_REQUIRED_SECTIONS_TO_PUBLISH = [
"siteform",
"siteidentification",
"sitelocation",
"sitereceiver",
"siteantenna",
"siteoperationalcontact"
]
The minimum set of completed site log sections required to publish a log for the first time. Must be a list of site log section model names.
SLM_DATA_VALIDATORS¶
Use this setting to control how site log sections are validated. Also see
SLM_IGS_VALIDATION.
Todo
Describe this setting.