Getting Started

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.

Using Docker

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/public:/heretic/dist/public \
    -v /var/www/heretic/etc:/heretic/etc \
    -v /var/www/heretic/site:/heretic/site \
    -v /var/www/heretic/files:/heretic/files \
    -v /var/www/heretic/logs:/heretic/logs \
    -v /var/www/heretic/backup:/heretic/backup \
    -p 3001:3001 \

You may wish to replace /var/www/heretic with any directory which shall ne 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).

To use the full configuration, you will either need to install additional services such as Mongo and Redis on the target machine, or use the Docker Compose mechanism to run multiple containers, including a Heretic container, in conjunction.

The helper script generates the Docker Compose configuration file, the curl and sed commands must be available on your machine. Run this script to generate *docker-compose.yml* in the current directory: bash ./ <siteid> <port> (replace <siteid> with an unique site ID (e.g. heretic), and <port> with a listening port (e.g. 3001):

bash ./ heretic 3001

When finished, you need to run docker compose command in order to start the containers:

docker compose

Installation on Server

Heretic can be installed on any server that can run Node.js. The database and caching server also require an architecture and configuration that must be supported by Mongo and Redis, but since these components are optional, the system can be run without them.

The Heretic build process was successfully tested on Debian Linux 11, macOS and Windows 11. The system can be run on a server or virtual machine with 512 MB RAM, but at least 2 GB of RAM may be required for a successful build.

Prerequisite steps to be taken before installing Heretic on the server:

  1. Install Node.js using these instructions
  2. Install the MongoDB database management system using these instructions — optional
  3. Install Redis using *apt* package manager by running apt install redis-server command — optional

Then, you need to clone Heretic from Github repository:

git clone --depth 1 --branch master

Install the required NPM modules and start the build process:

npm i    

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 command above without --dev key.

Finally, start your web server using the following command:

npm run server

When successfully, your website will be accessible at

Detailed documentation on installing, setting up, and configuring Heretic can be found in the project's repository on GitHub.