Getting Started

In order to run Heretic, you will need a web server which can run Node.js scripts. There are no special requirements, so if you can install and use Node, you can host a Heretic website.

In case your site needs additional features, such as database access, control panel, etc., you will also need to install additional packages.

Heretic can be run on the server as a standalone application or in a Docker container (or in Docker Compose). Running Heretic in a container is preferable because it allows Heretic's operation to be separated from the main host and is more secure.

Running with Docker Compose

The easiest way to run a fully functional and maintainable version of Heretic is to use Docker Compose. You can choose one of the options (Heretic only, Heretic + MongoDB, Heretic + Redis, or all at once). Each application runs in a separate container, and the containers are connected by a common network.

This option requires downloading the interactive script using the following command:

curl -sS -o docker-compose.sh https://hereticjs.org/compose

Next, run the script by executing the command:

bash docker-compose.sh

Finally, start docker compose containers by running:

docker compose up -d

Running a Docker Container

In its base configuration, Heretic requires nothing more than the standard features provided by Node.js. If you do not require advanced features such as user management, database, etc., you can run Heretic in a container using the following commands.

docker run -d --name heretic     -v /var/www/heretic/dist:/heretic/dist     -v /var/www/heretic/site:/heretic/site     -v /var/www/heretic/logs:/heretic/logs     -v /var/www/heretic/backup:/heretic/backup     -p 3001:3001     hereticjsorg/heretic:latest

You may wish to replace /var/www/heretic with any directory which shall be used to keep Heretic data on your host machine. You may also wish to replace the default port mapping (for example, to make container listen on the port 80, use the -p 80:3001 parameter).

Standalone

If you want to run Heretic without containers (in standalone mode), you must make sure that all necessary dependencies (such as Node.js, MongoDB and Redis if needed) are available on your server. For automated setup, you can download an interactive script that will download the latest version of Heretic from Github and execute the necessary commands for the first start:

curl -sS -o heretic.sh https://hereticjs.org/install

Next, run the script by executing the command:

bash heretic.sh

You can also perform all the necessary actions yourself, taking into account the specifics of your operating system version. First, you need to clone Heretic from Github repository:

git clone --depth 1 --branch master https://github.com/hereticjsorg/heretic.git

Then, you will need to go to heretic directory, install the required NPM modules and start the build process:

npm run install-modules

When successful, the required modules will be downloaded to ./node_modules directory.

In order to create templates of configuration files, directories, etc., you need to run the following command:

npm run configure

Finally, you may wish to run the build process:

npm run build -- --dev

This command will generate your site in development mode (faster, less optimizations). In order to generate a website in production mode, run the following command:

npm run build

Finally, start your web server using the following command:

npm run server

When successfully, your website will be accessible at http://127.0.0.1:3001.

Tests

In order to run built-in tests, please run the following command:

npm test

Jest, a delightful JavaScript Testing Framework with a focus on simplicity is used here.

Build Process

Heretic uses Webpack, a static module bundler for modern JavaScript applications. There are two build modes in Heretic: build-dev and build-production.

build-dev

During build process, Heretic creates a ./dist directory which contains everything you need to run your website (static bundles, server script etc.). There are following stages of website build:

  • generate internationalization loader to fetch translation files dynamically (./site/.build/i18n-loader.js) in SPA mode
  • generate pages and modules loader used by SPA mode used to load data without page reload (./site/.build/modules-loader.js)
  • generate configuration files used by build script (saved to ./site/.build directory)
  • generate site.webmanifest (saved to ./src/static/site.webmanifest directory)
  • generate <lang-switch/> components for each page where langSwitchComponent parameter is set to true
  • generate bundles and static assets (saved to ./dist/public)
  • generate script to run as a web server (saved to ./dist/server.js)

The following directories are deleted and re-created every time you start the build process: ./dist, ./site/.build.

In build-dev mode:

  • inline-source-map is used as devtool
  • style-loader is used as loader for CSS, SCSS or SASS files
  • no code is minimized for build performance reasons
  • no compression plugin is used (static assets and bundles are not compressed)

build-production

This mode is intended to prepare your website to run in production mode. It has some extra optimizations so it's slower as build-dev mode and must be used when you're ready to publish your website.

In build-production mode:

  • not using devtool
  • MiniCssExtractPlugin is used as loader for CSS, SCSS or SASS files
  • TerserPlugin and CssMinimizerPlugin plugins are used to minimize JS code and CSS styles
  • CompressionPlugin is used to generate GZ files to load website faster

Misc Static Assets

Several static assets are automatically generated during the build process:

  • Sitemap file is generated automatically based on pages settings
  • Site manifest is generated (based on website settings)
  • Everything from ./site/static is copied to ./dist/public automatically (this includes favicons, sitemap, site manifest etc.) - you may wish to copy your statics assets to include into ./dist directory here
  • Everything from ./src/defaults/static/data is copied to ./dist automatically (this includes for example captcha font and other data which will be used by server but should not be exposed to public).