Skip to content

Installation guide (for pre packaged releases)

Jump to bottom
Jacob Wodzyński edited this page Jun 9, 2021 · 7 revisions

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 front end)
  • Admin (a frontend for Client's configuration files)
  • Backend (historically called Mapservice, which is the backend server application which has a REST API)

System requirements

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

Furthermore, there is a Windows-specific IIS-only backend.

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

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.

The Three Editions of Hajk

The following options are available when installing Hajk:

  1. The NodeJS edition. This is the recommended way edition for installing Hajk in new environments. The Backend has been rewritten from scratch in JS. It can be deployed on any platform supported by NodeJS and supports additional features that are not available in the other editions.
  2. The .NET edition. The original edition. Requires Windows and IIS.
  3. The 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.

Node JS edition

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

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

  1. Unpack the zip file
  2. cd hajk-v.3.5.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 or admin)

Pre-requirements: Any OS, any web server

  1. Unpack the zip file
  2. Copy the contents of hajk-v.3.5.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 the simpleMapConfig.json and simpleLayersConfig.json to configure your map

.NET edition

Pre-requirements: Windows with IIS

  1. Download the latest release of .NET edition from here.
  2. Unpack the zip-file to a folder, e.g. D:\hajk
  3. Go to IIS
  4. Create a new website, point it to D:\hajk as root
  5. Convert admin and mapservice to IIS applications (by right-clicking and selecting "Convert to application")
  6. Launch your server and navigate to localhost (or whatever your binding for the website is, in IIS). You should see the client application spinning up. (If not, see Troubleshooting below.)
  7. The other applications are located in their respective directories, so if client is on localhost, you can reach admin on localhost/admin and map service on localhost/mapservice.
  8. Fine-tune the admin application. The mapservice application must have sufficient permissions to change files in the /mapservice/App_Data directory. This is done by giving the user that runs the IIS Application Pool (by default IIS_IUSRS) modify permission on the directory.
  9. It's recommended to restrict access to the admin application. One way to achieve it is to use IIS's built in Authentication module. Disable Anonymous Authentication and enable your authentication method of choice, such as Windows Authentication. Now users who try to reach the localhost/admin endpoint will be prompted to login in with a valid Windows username and password.
  10. For information on fine-tuning the setup, please refer to the following section.

Fine-tuning your installation

NodeJS edition

The Backend of the NodeJS edition is controlled by the settings in the .env file. The file is well-commented and it's recommended that you take some time to review the options available. 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 that only exists in the NodeJS edition is the API explorer. It is available on http://localhost:3002/api-explorer/. For production servers, it is recommended that you disable this functionality (again, see .env).

.NET edition

The .NET edition's Backend is an IIS application and can be controlled via the IIS Control Panel and the Web.config file.

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 layers.json and map_1.json files.

Running the entire solution as a Docker image

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

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

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. Client will request two files from mapservice on load: layers and map_1. By default mapservice is located directly under web root, but if your setup varies, make sure to point to the proper mapservice application by editing client\appConfig.json. The same should be done for admin in admin\config.json.

Clone this wiki locally