Installation guide (for pre packaged releases)

Introduction

What is Hajk?

It is important that those who setup a Hajk-based solution have a clear understanding of the following.

Hajk consists of three technically separate applications that work together to provide a full-fledged experience to both users and administrators:

• Client (the web map app that users usually think of when they think of Hajk)
• Admin (a frontend for Client's configuration files)
• Backend (a REST API)

System requirements

Hajk can run on any operating system and architecture where NodeJS is available.

In addition, Hajk is also provided as a Docker container. For more information, see below.

Finally, there is a Simple edition of Hajk, where Admin and Backend are not used and the only active component is the Client app. In this configuration, Hajk is just a directory of static HTML, JS and CSS and can be delivered to the user's browser using any HTTP server.

Regular vs Simple edition

As mention in the previous paragraph, there's a distinction between the Regular vs Simple editions:

1. Regular edition (previously known as "NodeJS edition"). This is the recommended way for installing Hajk in new environments. It includes an Admin application that allows administrators to control all the aspects of the Hajk installation. The Admin app writes the configuration files using the Backend server application. The Backend is a NodeJS application. It can be deployed on any platform supported by NodeJS.
2. Simple edition. A way to install Hajk without actually installing anything. Just put the static files on a web server, do necessary adjustments in some JSON files and you're good to go. This edition does not contain Admin and Backend application and is therefore recommended for basic installations only.

Installation

Step 1: Decide which version to use

Ensure that you've decided which Hajk edition suits your needs. For details, please refer to the previous section.

Step 2: Download

Go to the Hajk releases page and download the appropriate edition for the latest release.

Step 3: Install the chosen edition

Depending on your choice in step 1, refer to the relevant section below.

Regular edition (with the NodeJS backend)

Pre-requirements: Any OS with Node 20.9 or greater.

Please note: the instructions below assume Hajk release 4.0. Make sure to replace the version with the one you've downloaded wherever applicable.

1. Unpack the zip file
2. cd hajk-v.4.0.0-nodejs
3. npm install
4. node index.js
5. Go to localhost:3002 for the client app
6. Administration: use the full-fledged admin UI located on localhost:3002/admin. (There's even an API explorer, check out localhost:3002/api-explorer for the OpenAPI Specification of backend.)
7. For information on fine-tuning the setup, please refer to the following section.

Simple edition (no Backend nor Admin)

Pre-requirements: Any OS, any web server

1. Unpack the zip file
2. Copy the contents of hajk-v.4.0.0-simple directory to your web server of choice
3. Hajk is now available on the specified path/port of your web server (refer to your web server's setup)
4. Administration: edit simpleMapAndLayersConfig.json to configure your map

Fine-tuning your installation

Regular edition

The Backend of the NodeJS edition is controlled by the settings in the .env file. The file is well-commented and it is highly recommended that you take some time to review the options. If unsure, it's fine to leave the defaults.

If you've followed the instructions so far, you can verify that the Backend is up and running by navigating to http://localhost:3002. (If you wish to change the port, see .env.)

One particularly nice feature of the Backend is the API explorer. It is available on http://localhost:3002/api-explorer/. For production servers, it is recommended that you disable this functionality (see .env).

Simple edition

The Simple edition does not contain the Admin and Backend applications, hence the post-install fine-tuning is limited to configuring the Client application and its layers. That can be done in the simpleMapAndLayersConfig.json file.

Docker deployment

A simple way to get Hajk up and running is to use the official Docker image. The images can be fetched from Docker Hub.

Fetch either the latest image, or a specific release and follow the instructions on Docker Hub to get everything up and running.

The Docker image contains Hajk Regular edition.

Additional info: how Client and Admin communicate with the Backend

As mentioned in the previous sections, Hajk consists of three separate applications: Client, Admin and Backend.

Client and Admin communicate with the Backend using an API. In order for the communication between the applications to work, the two front-end applications must know where to find the Backend, i.e. which machine is hosting the backend and on which port. That setting is controlled in the appConfig.json for the Client and in config.json in for the Admin.

Troubleshooting

The most frequent problems when setting up Hajk are related to the different parts of Hajk not being able to communicate with each other. To debug, launch Developer tools in your browser and go to the Network tab. Reload the website. When the Client app load it'll attempt to fetch appConfig.json from your server. Once it has that file, it'll read the contents, look for the value of mapServiceBase parameter and use that to load the actual map configuration from your Backend.