Configuration Files

There are several configuration files available so you may adjust many parameters related to your website.

site/etc/system.js

This configuration file contains main options related to your web server (IP, ports, logging etc.).

id

Unique website ID. This ID is used for cookies, websockets etc.

Example:

id: "heretic"

secret

Secret key used for internal security purposes, e.g. to encrypt session keys or to salt database records.

Normally it's being imported from a js file called secure.js, but you can put any value here.

Example:

secret: secure.secret

hashMethod

Define the way you database passwords will be stored. Currently there are to options available: argon2 or crypto (crypto.scrypt):

hashMethod: "argon2"

server

Define the options to run the build-in Web server based on Fastify:

Option	Description
ip	IP address your server should listen to (use 0.0.0.0 to listen to all interfaces)
port	Port on which Fastify is listening to
static	Serve static content using internal server (disable for production)

Example:

server: {    ip: "0.0.0.0",    port: 3001,    static: true,}

auth

Set different options related to the authentication process:

Option	Description
admin	Should the admin panel be enabled (works only if MongoDb is enabled)
signIn	Is sign in allowed (the existing users are allowed to authenticate)
signUp	Is sign up allowed (new users are allowed to register)

Example:

auth: {    admin: true,    signIn: true,    signUp: true}

mongo

Heretic has an option to use MongoDB as a database backend. The options are as following:

Option	Description
enabled	Should the MongoDB feature be enabled?
url	Define MongoDB connection URL
dbName	Define database name
options	Define MongoDB connection options

Example:

mongoption: {    enabled: true,    url: "mongodb://127.0.0.1:27017",    dbName: "heretic",    options: {        connectTimeoutMS: 5000,    },}

redis

Heretic has an option to use Redis for internal purposes. The options are as following:

Option	Description
enabled	Should the Redis feature be enabled?
host	Define Redis Server host
port	Define Redis Server port
connectTimeout	Connection time-out
maxRetriesPerRequest	Number of maximum retries per request

Example:

redis: {    enabled: false,    host: "127.0.0.1",    port: 6379}

email

Set your e-mail configuration here. Heretic uses Nodemailer under the hood to send mails.

Configuration options:

Option	Description
enabled	Is mail sending allowed?
from	Which from address should be used to send mails
config	Nodemailer transporter configuration object

Example:

email: {    enabled: false,    from: "noreply@hereticjs.org",    config: {        host: "smtp.example.com",          port: 587,          secure: false,          auth: {            user: "username",            pass: "password",          }    }}

webSockets

Configuration for internal web sockets transport.

Option	Description
enabled	Are websockets supported?
url	Web socket URL for frontend connections
options	Web socket options

Example:

webSockets: {    enabled: true,    url: "ws://127.0.0.1:3001/ws",    options: {        maxPayload: 1048576,    }}

token

Configuration of JWT (tokens):

Option	Description
expiresIn	Token time-to-live (in seconds)
ip	Bind token to client IP address

Example:

const {    parse,} = require("@lukeed/ms");token: {    expiresIn: parseInt(parse("7 days") / 1000, 10),    ip: false}

passwordPolicy

Define password policy for users (takes effect on sign up and other password-related procedures).

Options:

Option	Description
minLength	Minimum password length (set null to disable)
maxLength	Maximum password length (set null to disable)
uppercase	Should contain uppercase characters
lowercase	Should contain lowercase characters
numbers	Should contain numbers
special	Should contain special characters
minGroups	A number of groups required (e.g. 2 means that a password should contain either numbers and uppercase characters, or lowercase and uppercase characters etc.)

Example:

passwordPolicy: {    minLength: 8,    maxLength: null,    minGroups: 2,    uppercase: true,    lowercase: true,    numbers: true,    special: true,}

oauth2

A list of available OAuth2 providers for the current site. Heretic is using @fastify/oauth2 under the hood.

The following providers are supported for Heretic now:

Google

Configuration data:

Option	Description
enabled	Is this authentication method enabled?
name	Method name (should start with oa2)
scope	A list of requested scopes (should contain email as this is required for the workflow)
credentials.client	Define ID and secret of oauth provider
credentials.auth	Redirect path to start the authentication workflow
callbackUri	Callback URL
callbackPath	Callback path
icon	SVG path for the icon displayed on the sign in / sign up pages

Example:

oauth2: [{    enabled: false,    name: "oa2google",    scope: ["profile", "email"],    credentials: {        client: {            id: "",            secret: "",        },        auth: process.browser ? null : require("@fastify/oauth2").GOOGLE_CONFIGURATION,    },    startRedirectPath: "/oauth2/google",    callbackUri: "https://demo.hereticjs.org/oauth2/google/callback",    callbackPath: "/oauth2/google/callback",    icon: "M488 261.8C488 403.3 391.1 ...",}]

cookieOptions

Define options for cookies.

Option	Description
expires	Cookie expiration time (seconds)
path	Cookie path
domain	Cookie domain
secure	Secure cookie flag
sameSite	Cookie "same site" property
callbackUri	Callback URL
callbackPath	Callback path
icon	SVG path for the icon displayed on the sign in / sign up pages

Example:

{    expires: 604800,    path: "/",    domain: ".demo.hereticjs.org",    secure: true,    sameSite: "strict"}

log

Define logging settings.

Options:

Option	Description
level	Define log level ("trace", "debug", "info", "warn", "error", or "fatal")

Example:

log: {  level: "info"}

rateLimit

Rate limiting protects your website from various denial-of-service attacks and helps you to limit access for specified IPs.

Options:

Option	Description
timeWindow	Time period (in milliseconds); in case a client reaches the maximum number of allowed requests in this time period, a 429 error is generated
max	Request limit until client gets temporary restricted
ban	Request limit until client gets banned
whiteList	A whitelist of IP addresses or networks
blackList	A whitelist of IP addresses or networks
addHeaders	Headers to add

Example:

rateLimit: {    enabled: false,    ban: false,    global: {        max: 100,        ban: 1000,        timeWindow: 10000    },    whiteList: [],    blackList: [],    addHeaders: {        "x-ratelimit-limit": true,        "x-ratelimit-remaining": true,        "x-ratelimit-reset": true,        "retry-after": true,    }}

See rate limiting for further information.

directories

Define system-wide directories used to store local files.

Options:

Option	Description
tmp	A directory to store temporary files (null means to use the system directory, e.g. /tmp)
files	A directory to store file uploads

Example:

directories: {    tmp: null,    files: "files"}

collections

A list of MongoDB collection names for different system modules.

Example:

collections: {    users: "users",    files: "files",    counters: "counters",    history: "history",    groups: "groups",    events: "events",    geoNetworks: "geoNetworks",    geoCountries: "geoCountries",    geoCities: "geoCities",    version: "version",    sessions: "sessions",    activation: "activation",    captcha: "captcha"}

routes

A list routes for different system modules.

Example:

routes: {    admin: "/admin",    signInAdmin: "/admin/signIn",    signIn: "/signIn",    signOutAdmin: "/admin/signOut",    signOut: "/signOut",    account: "/account",    signUp: "/signUp",    restorePassword: "/restorePassword"}

buildOptions

Options on how to build Heretic from source:

Option	Description
productionCompress	Compress compiled website files using gzip compression

Example:

buildOptions: {    productionCompress: false}

test

Options for test framework:

Option	Description
headless	Run GUI tests in headless mode
executablePath	Chromium executable path (set "auto" to search for a pre-installed Chrome or Chromium)
args	Arguments to start Chromium with
defaultViewport	Default view port
devtools	Start Chromium with open DevTools

Example:

test: {    headless: true,    executablePath: "auto",    args: ["--window-size=1920,1080", "--no-sandbox"],    defaultViewport: null,    devtools: true}

heretic

Specify some framework internal settings.

Option	Description
zipball	An URL to get the zipball from (used for system updates)
darkModeEnabled	Enable switch to dark mode

Example:

heretic: {    zipball: "http://github.com/hereticjsorg/heretic/zipball/master/",    darkModeEnabled: true}

site/etc/website.js

This configuration file describes the meta data of your website which is used system-wide.

Option	Description
url	Site URL starting with http or https

Returns the object which should include data from meta.js (see below).

site/etc/meta.src.js

This configuration file describes the meta data of your website which is used system-wide.

Option	Description
title	Site title (specified for each site language individually)
shortTitle	A shorter version of site title (specified for each site language individually)
description	Site description (specified for each site language individually)

site/etc/languages.js

This configuration file contains a list of languages in the following format:

{    "en-us": "English",    "ru-ru": "Русский"}

site/etc/navigation.js

This file is being used as a source to display the top navigation menu on your website (in the default template). Additionally, you've to set the default route ID.

For each area, "userspace" and "admin", you may define a separate list of routes.

Userspace:

Option	Description
home	Home route ID
routes	Array which contains all routes to display in the navbar

Admin:

Option	Description
routes

Normally, routes options contains an array of strings (each strings indicates a corresponding route ID). If you want to use dropdown menus for routes, you can use the following syntax:

{    "home": "sample_home",    "routes": [        "sample_home",        "sample_license",        {            "id": "parentRouteName_page",            "routes": ["childRouteId1_page", "childRouteId2_page", "childRouteId3_page"]        }    ]}

You will need to add a translation for parentRouteName to your user translation dictionaries. Add your route IDs to routes array.

Auto-Generated Files

Some files are auto-generated during the build process. Most of them are located in the .build directory. There is no need to edit anything there because each file gets overwritten on every build.