Technical Configuration

This section will discuss the technical configuration of Janeway focusing on the Django settings file.

Note

This section is currently a work in progress.

Django Settings

Unlike traditional Django applications Janeway has two settings files, they are generally located in src/core/.

  • janeway_global_settings.py
  • settings.py (created during the installation process)

Global Settings

The global settings file is created by the Janeway team and is managed through version control. Generally speak you should not need to change anything in this file as you can use your local settings.py file to override variables.

Local Settings

This file is usually created during the setup process and can be based on the provided example_settings.py file.

  • DEBUG - Should be set to False in any environment where an external user can access the install.

  • URL_CONFIG - Set to either ‘domain’ or ‘path’ dependind on whether the primary way to access sites is via individual domains for each or path based urls eg. journal.press.com or press.com/journal/.

  • DATABASES - You can set the database connection details for the install.

  • CAPTCHA_TYPE - Can be one of three different variables: ‘simple_math’, ‘recaptcha’ or ‘hcaptcha’.

    • simple_math - A very simple captcha using a basic mathematical question.
    • recaptcha - Uses Google’s reCaptcha2. Has been shown to be less effective recently but v3 is not GDPR compliant. You should complete ‘RECAPTCHA_PRIVATE_KEY’ and ‘RECAPTCHA_PUBLIC_KEY’ otherwise you will get an error.
    • hcaptcha - Uses hcaptcha, a new addition to Janeway. You should complete ‘HCAPTCHA_SITEKEY’ and ‘HCAPTCHA_SECRET’ otherwise you will get an error.
  • LOGGING
    • Provides the configuration for Python’s logger. We recommend following the steps described in the Django documentation for configuration.
    • By default, Janeway will log both to the console as well as to the file located at logs/janeway.log and rotates the file every 50MB. For production systems, you may want to change the location and/or rotation strategy as per the Django documentation

Error Logging with Sentry

As of version 1.5 we have removed core the Raven core requirement, this is because Sentry no longer uses Raven. We have made the decision not to include the Sentry SDK as a core requirement so the process for adding Sentry logging back is detailed below.

First you will need to install the Sentry SDK:

pip install sentry-sdk

Next you will need to configure the SDK by adding the following to you settings.py file:

import sentry_sdk
from sentry_sdk.integrations.django import DjangoIntegration

sentry_sdk.init(
    dsn="https://examplePublicKey@o0.ingest.sentry.io/0",
    integrations=[DjangoIntegration()],

    # Set traces_sample_rate to 1.0 to capture 100%
    # of transactions for performance monitoring.
    # We recommend adjusting this value in production,
    traces_sample_rate=0.0,
)

Add your own dsn in place of the example. You should now start receiving sentry error reports. Information, including which version of the SDK to install, on Sentry’s Django integration can be found over on their docs site: https://docs.sentry.io/platforms/python/guides/django/.

Theming

Janeway includes three core themes by default:

  • OLH (Foudation)
  • material (Materialize)
  • clean (Bootstrap)

A list of core themes is held in janeway_global_settings.py.

Theme Structure

Generally themes follow this structure:

  • /path/to/janeway/src/themes/themename/
    • assets/
      • Contains CSS/JS/Images
    • templates/
      • Contains Django templates
    • __init__.py
    • build_assets.py
      • Should contain at least one method called build that takes no arguments, it should know how to process any SCSS and copy the resulting files into the main static folder or just pass if not required. See path/to/janeway/src/themes/OLH/build_assets.py as an example.
    • README.MD

Creating a New Theme

You are welcome to develop your own themes and can use one of the existing themes as a template of what is required. You should follow the structure above and have full template coverage.

Creating a Sub Theme

Creating a sub theme is much easier than creating one from scratch. A sub theme is essentially a copy of one of the existing themes but with the templates that aren’t required stripped out. This is useful if say, for example, you only want to customise one or two templates as you will only need to track core changes to those files.

Once you have created your sub theme you can then set for the whole install with the INSTALLATION_BASE_THEME setting or the Journal Base Theme setting for journals that are using the sub theme (located on the Manager > Journal Settings page, this setting will appear once you set the Journal Theme to your non-core theme).

An example structure for a sub theme where we want to customise only the login page:

  • /path/to/janeway/src/themes/speciallogintheme/
    • assets/
    • templates/
      • core/login.html
      • press/core/login.html
    • __init__.py
    • build_assets.py
    • README.MD