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:

OptionDescription
ipIP address your server should listen to (use 0.0.0.0 to listen to all interfaces)
portPort on which Fastify is listening to
staticServe 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:

OptionDescription
adminShould the admin panel be enabled (works only if MongoDb is enabled)
signInIs sign in allowed (the existing users are allowed to authenticate)
signUpIs 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:

OptionDescription
enabledShould the MongoDB feature be enabled?
urlDefine MongoDB connection URL
dbNameDefine database name
optionsDefine 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:

OptionDescription
enabledShould the Redis feature be enabled?
hostDefine Redis Server host
portDefine Redis Server port
connectTimeoutConnection time-out
maxRetriesPerRequestNumber 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:

OptionDescription
enabledIs mail sending allowed?
fromWhich from address should be used to send mails
configNodemailer 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.

OptionDescription
enabledAre websockets supported?
urlWeb socket URL for frontend connections
optionsWeb socket options

Example:

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

token

Configuration of JWT (tokens):

OptionDescription
expiresInToken time-to-live (in seconds)
ipBind 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:

OptionDescription
minLengthMinimum password length (set null to disable)
maxLengthMaximum password length (set null to disable)
uppercaseShould contain uppercase characters
lowercaseShould contain lowercase characters
numbersShould contain numbers
specialShould contain special characters
minGroupsA 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:

OptionDescription
enabledIs this authentication method enabled?
nameMethod name (should start with oa2)
scopeA list of requested scopes (should contain email as this is required for the workflow)
credentials.clientDefine ID and secret of oauth provider
credentials.authRedirect path to start the authentication workflow
callbackUriCallback URL
callbackPathCallback path
iconSVG 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.

OptionDescription
expiresCookie expiration time (seconds)
pathCookie path
domainCookie domain
secureSecure cookie flag
sameSiteCookie "same site" property
callbackUriCallback URL
callbackPathCallback path
iconSVG 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:

OptionDescription
levelDefine 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:

OptionDescription
timeWindowTime period (in milliseconds); in case a client reaches the maximum number of allowed requests in this time period, a 429 error is generated
maxRequest limit until client gets temporary restricted
banRequest limit until client gets banned
whiteListA whitelist of IP addresses or networks
blackListA whitelist of IP addresses or networks
addHeadersHeaders 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:

OptionDescription
tmpA directory to store temporary files (null means to use the system directory, e.g. /tmp)
filesA 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:

OptionDescription
productionCompressCompress compiled website files using gzip compression

Example:

buildOptions: {    productionCompress: false}

test

Options for test framework:

OptionDescription
headlessRun GUI tests in headless mode
executablePathChromium executable path (set "auto" to search for a pre-installed Chrome or Chromium)
argsArguments to start Chromium with
defaultViewportDefault view port
devtoolsStart 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.

OptionDescription
zipballAn URL to get the zipball from (used for system updates)
darkModeEnabledEnable 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.

OptionDescription
urlSite 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.

OptionDescription
titleSite title (specified for each site language individually)
shortTitleA shorter version of site title (specified for each site language individually)
descriptionSite 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:

OptionDescription
homeHome route ID
routesArray which contains all routes to display in the navbar

Admin:

OptionDescription
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.