Skip to main content

Operate

Scope​

This page is intended for administrators who are authorized to install and configure the MapCore™ Map Layer Server. The information provided in this page includes:

  • Minimum System Requirements

  • Overview of System Folders and Configuration Files

  • Note for Linux Users

  • Changing the Location of the Data Repository Folder

  • Server Start

  • Server Update

  • Server Shut Down

  • Server Uninstall

The server execution parameters are described in Command line, and the installation in Install on Windows, Install on Linux and Run in Docker.

The following diagram illustrates steps to be taken in server operations per system and server configuration.

Figure 2-1

Figure 2-1 Server operations process flow

Minimum System Requirements​

The computer on which the MapCore™ Map Layer Server is installed must meet or exceed the following specifications:

  • Processor (CPU): Intel I3 or higher

  • Memory (RAM): 8 GB

  • Storage (HDD): 500 GB

  • Operating system:

    • Windows 7, 8, 10, 11 (x64)

    • Linux, rpm-based distributions such as RHEL, AlmaLinux and Rocky Linux (reference platform: AlmaLinux 8.10), x86_64 or aarch64

    • Linux, Debian and Ubuntu (20.04, 22.04, 24.04), amd64 or arm64

  • Browser, current versions:

    • Chrome

    • Edge

    • Firefox

System Folders and Configuration Files​

Figure 2-2

Figure 2-2 Configuration files and user-specific data in MapCore™ Map Layer Server directory

While the name of the default installation folder varies according to the operating system of the machine on which MapCore™ Map Layer Server is installed, the structure within that folder is always identical, regardless of operating system. For the purpose of running and managing the MapCore™ Map Layer Server, knowledge of only the information detailed herein is relevant.

The default installation folder contains both system data and user-specific data such as layers and configuration choices. By default, server data resides in both folders while user-specific data resides in the default server data repository folder. Configurable server data is found in the server configuration file (see Server Configuration File below). All user-specific data regarding layers is stored in the configurable layer configuration file (see Layer Configuration File below).

warning

User-specific data should be moved to a customized location to prevent data loss in the event of a server update.

It is strongly advisable to change the location of all user-specific data folder and files to prevent data loss when updating the server. Note, however, that the default server data repository folder also holds all server GUI files, which must not be moved. Refer to Changing the Location of the Data Repository Folder for detailed instructions.

The names of both the default installation folder and the default data repository folder vary according to the operating system of the machine on which MapCore™ Map Layer Server is installed as detailed in the following table.

Table 2-1 Default serverinstallation and server data repository folders per operating system

Operating systemDefault server installation folderDefault server data repository folder
Linux (rpm and deb packages)/usr/bin/maplayerserver/usr/bin/maplayerserver/WWWRoot (server GUI). The start-up script uses /mnt/ServerData as the data repository folder by default.
Docker/usr/bin/maplayerserver (inside the container)/mnt/ServerData (container volume, mapped to a host folder)
WindowsC:\Program Files\MapLayerServer\<version>C:\ProgramData\Elbit\MapLayerServer\<version>\WWWRoot (server GUI). The data repository folder is the one chosen in Setup, C:\ServerData by default.

Server Configuration File​

The server configuration file McMapLayersServerConfig.xml resides by default in the server executable folder (see Figure 2-2 Configuration files and user-specific data in MapCore™ Map Layer Server directory for layer configuration file location) and holds server-specific information that controls how the server is run, such as default tiling scheme. These parameters may be set via the Server GUI. Refer to Server Parameters for details on the structure and content of this file. While it is inadvisable to change the location of this file, it is possible to do so.

Refer to Figure 2-2 Configuration files and user-specific data in MapCore™ Map Layer Server directory for configuration file name and location.

Refer to Server Execution Parameters for details on running the server when the server configuration file is in a location other than the default location.

Refer to Change Server Configuration for details on accessing and changing configuration parameters via the GUI.

Refer to Configure the server for a detailed explanation of each configurable parameter.

On Linux installations from the rpm/deb packages and in the Docker image, the server configuration file resides in /var/lib/maplayerserver (passed to the server as the server configuration file folder by the start-maplayerserver script), so that the installation folder remains read-only.

On Windows, the server configuration file resides in C:\ProgramData\Elbit\MapLayerServer\<version> (passed to the server as the server configuration file folder by the installed shortcuts and by MCLAYERSERVER_ACTIVATION_STRING), so that the installation folder remains read-only and a standard user can change the configuration. The MapCore log MapCore.log is written to the same folder. See What the Installer Sets Up.

Layer Configuration File​

The layer configuration file McLayersDataConfig.xml resides by default in the data repository folder (see Figure 2-2 Configuration files and user-specific data in MapCore™ Map Layer Server directory for layer configuration file location) and contains information about all layers that have been defined in the server. Refer to User-specific Layer Parameters for details on the structure and content of this file. Information stored in the layer configuration file is accessed by the server each time it is run in order to open all layers.

In case layers are referenced in the layer configuration file but actual data of layers is missing (e.g., accidently removed from the server computer, renamed, or moved to another location), a backup file is created of the original layer configuration file including the information of the missing layers, after which those layers are deleted from the layer configuration file. When the backup file is created, a warning message is issued in the terminal console while the server continues to load. The backup file is named McLayersDataConfig_backup_<timestamp>.xml where <timestamp> has the following structure: YYYY_MM_DD_HH_MM_SS, for example: McLayersDataConfig_backup_2023_05_28_14_16_20.xml.

In addition, each time the server saves its configuration, it also saves a backup copy of each configuration file next to the original: McMapLayersServerConfigBackup.xml and McLayersDataConfigBackup.xml. If a configuration file cannot be read when the server starts (for example, because it is corrupted), the server loads the corresponding backup file instead.

The contents of the layer configuration file may be retrieved via the GET GetCapabilities Restful API request. Refer to GET GetCapabilities Request (WMTS Compatible)for detailed information.

Server Log File​

The MapCore™ Map Layer Server log file is called McMapLayerServer_<timestamp>.log where <timestamp> is presented in this format: YYYY_MM_DD_HH_MM_SS (such as: McMapLayerServer_2023_11_21_09_34_28.log).

The location of server log file depends on the operating system:

  • In Windows, it is located by default in the folder c:\programdata\Elbit. Note that you may type %programdata% in the file explorer address bar to quickly locate the programdata folder.

  • In Linux, it is located in the same folder as McMapLayersServerConfig.xml. Refer to Server Configuration File for name and location of the default server executable folder. For installations from the rpm/deb packages and in the Docker image, this is /var/lib/maplayerserver.

Up to 10 instances of the McMapLayerServer_<timestamp>.log may be created. The eleventh instance of this file will cause the oldest log file to be deleted.

A second log file is created on demand through the MapCore™ Map Layer Server GUI. Refer to Log Display for detailed information about this log file and its location.

Note for Linux Users​

note

Pay particular attention to code and command case, as the Linux operating system is case sensitive.

Changing the Location of the Data Repository Folder​

Two steps are required for changing the location of the data repository folder:

Create a New Data Repository Folder​

This process differs depending on whether you are creating a new data repository folder for a new installation or a server update, as detailed below.

For a New Installation​

  1. Create a new folder in a desired location as your new customized data repository folder.

  2. Use server execution parameters to direct MapCore™ Map Layer Server to the customized data repository folder. Refer to Server Start for detailed instructions.

For a Server Update​

If customized client software data has already been stored in the default data repository folder (see System Folders and Configuration Files for detailed information), it is inadvisable to change the location of your customized client software data. Refer to Server Update for detailed instructions on how to handle such data.

Save Server Execution Parameters for Automatic Deployment​

This process differs per operating system as detailed below.

Save Execution Parameters on Linux​

Installations from the rpm/deb packages and the Docker image include the start-up script start-maplayerserver. It runs the server from its installation folder and accepts named options in place of the positional server execution parameters (see Server Execution Parameters):

start-maplayerserver [--host <local address>] [--port <port>] [--threads <number of threads>] [--www-root <server GUI folder>] [--conf-dir <server configuration file folder>] [--data-dir <data repository folder>]

The defaults are: --host 0.0.0.0, --port 6767, --threads 0, --www-root /usr/bin/maplayerserver/WWWRoot/, --conf-dir /var/lib/maplayerserver, and --data-dir /mnt/ServerData. To save customized execution parameters, create a script file that calls start-maplayerserver with the desired options, for example:

sudo start-maplayerserver --port 8080 --data-dir /srv/mapdata

If you run the McMapLayerServer executable directly instead, run it from its installation folder (/usr/bin/maplayerserver), since it locates ServerConfig.xsd, resources.cfg and plugins.cfg relative to the current folder.

Server Execution Parameters on Windows When Running the Server as a Service​

The service takes its server execution parameters from the system variable MCLAYERSERVER_ACTIVATION_STRING. Setup creates it with the port and the folders chosen at install (see What the Installer Sets Up). The server splits the value on spaces and tabs, so the folders it names cannot contain a space or a tab.

To customize the server execution parameters, change the variable as follows:

  1. Open the System Properties window. To do so, either:

    • On the keyboard press Windows + S to open Window’s search box, enter the term environment variable, and click on the search result that looks something like this:

Figure 2-13

Figure 2-13 Windows search result for the term environment variable

  • Click on the Windows icon, and then click on the Settings option. In the Setting window, enter the term environment variable, and click on the search result that looks something like this:

Figure 2-14

Figure 2-14 Windows system search result for the term environment variable

  1. On the Advanced tab of the System Property window, click the Environment Variables button.

Figure 2-15

Figure 2-15 System Property window

  1. Under System variables on the Environment Variables window, select MCLAYERSERVER_ACTIVATION_STRING and click the Edit… button. If the variable is not listed, click the New… button.

Figure 2-16

Figure 2-16 Environment Variables window

  1. In the System Variable window, enter the following, and then click the OK button:

    • In the field Variable name: MCLAYERSERVER_ACTIVATION_STRING

    • In the field Variable value: <server execution parameters> as detailed in Server Execution Parameters, with full folder paths.

Figure 2-17

Figure 2-17 Customizing server execution paramaters via MCLAYERSERVER_ACTIVATION_STRING environment variable

  1. Click the OK button to exit the Edit System Variable window.

  2. Click the OK button to exit the Environment Variables window.

  3. On the System Properties window, click the Apply button and then click the OK button.

  4. Reboot the system for your changes to take effect.

Server Execution Parameters on Windows When Running the Server from the Desktop Shortcut Icon​

The following instructions are relevant for running the MapCore™ Map Layer Server from the desktop shortcut icon (see Start Server on Windows for more details).

  1. Locate and right-click the McMapLayerServer <version> shortcut, and from the pop-up menu click the Properties option.

  2. In the Target field, enter following value:

"<default server executable folder>\McMapLayerServer.exe" <server execution parameters>

Where <default server executable folder> is as detailed in System Folders and Configuration Files and <server execution parameters> are as detailed in Server Execution Parameters.

Figure 2-18

Figure 2-18 Windows shortcut properties (Target field)

  1. The shortcuts created by the installer already contain the default server execution parameters (see Install Server on Windows); modify them as needed.

  2. Click the Apply button and then click the OK button.

Server Start​

This process differs based on operating system as detailed below.

Start Server on Linux​

  1. Run sudo start-maplayerserver, or run the script file which you created in Save Execution Parameters on Linux above.

  2. To operate the MapCore™ Map Layer Server, follow instructions detailed in Configure the server and The web GUI.

Start Server via Docker​

  1. Open the command line, and issue the following command:
docker run -d --name mcmaplayerserver -p 6767:6767 -v <host data folder>:/mnt/ServerData mapcore.jfrog.io/c4i-mapcore-docker-release-local/mcmaplayerserver:<version>

Where <host data folder> is the folder created in Install Server via Docker and <version> is the version of the installed image. The container runs the server through start-maplayerserver with its default options (see Save Execution Parameters on Linux), as an unprivileged user, and exposes port 6767. Alternatively, use the compose.yml file supplied with the image and issue the command docker compose up -d.

  1. Once the message Server is up and ready to receive requests is displayed, you may operate the MapCore™ Map Layer Server. To display the server messages of a container started with -d, issue the command docker logs -f mcmaplayerserver.

  2. To operate the MapCore™ Map Layer Server, follow instructions detailed in Configure the server and The web GUI.

Start Server on Windows​

note

Installing, uninstalling, registering the service and changing MCLAYERSERVER_ACTIVATION_STRING require administrator permissions; running the server from a shortcut or a command prompt does not. Should you encounter an error message along the following lines, click the Continue button to complete the operation:

Figure 2-19

Figure 2-19 Running commands as administrator in Windows

You may run the MapCore™ Map Layer Server on Windows in either of the following ways, which are further detailed below:

  • Set up the server to automatically start during operating system startup (running the server as a service) in which case, it is recommended to save server parameters within a designated environment variable. This is the recommended option.

  • Use the desktop shortcut icon to manually start the server, in which case, it is recommended to save server parameters within the shortcut properties to be employed each time you start the server.

  • Use the command prompt to manually start the server while overriding any saved server execution parameters. It is not recommended to use this option.

Start the Server Automatically on Computer Startup (Running the Server as a Service)​

The simplest way is to select the service task in Setup, which registers the service McMapLayersService, sets it to start automatically at boot and starts it. Refer to Run the Server as a Service. To register the service by hand instead:

  1. If not already done, save server startup parameters. Refer to Server Execution Parameters on Windows When Running the Server as a Service for detailed instructions.

  2. Open the command prompt as an administrator (see Start the Command Prompt as an Administrator).

  3. Issue the following commands:

cd <Default server executable folder>
McMapLayerServer /register
sc config McMapLayersService binPath= "\"<Default server executable folder>\McMapLayerServer.exe\""

Where <Default server executable folder> is detailed in System Folders and Configuration Files. The sc config command puts quotes around the registered path, which contains a space.

  1. Close the command prompt window (see Close the Command Prompt for detailed instructions).

  2. On the keyboard press Windows + S to open Window’s search box, enter the term services

  3. Right-click on the search result that looks something like this and from the context menu select Run as administrator. If prompted, click the Yes button to confirm your choice.

Figure 2-20

Figure 2-20 Windows search result for the term services

  1. On the Extended tab of the Services window, locate the service McMapLayersService by scrolling to it in the list of displayed services (it will only be displayed on the list if it has been successfully registered first).

Figure 2-21

Figure 2-21 Successfully registered McMapLayersService listed in Services window

  1. Right-click on the McMapLayersService service, and then click the Properties option.

  2. On the General tab of the service Properties window, Click the dropdown arrow of the field Startup type, and click the option Automatic.

Figure 2-22

Figure 2-22 Services window

  1. Click the Apply button, click the Start button, and then click the OK button to close the Properties window. The status of the service in the Services window is changed to Running.

  2. Close the Services window by clicking on the X control at the top right corner of the window.

Figure 2-23

Figure 2-23 Closing the Services window

Start Server via Desktop Shortcut Icon​

  1. If not already done, save server startup parameters. Refer to Save Server Execution Parameters for Automatic Deployment.

  2. Double-click the McMapLayerServer <version> shortcut on your desktop or in the MapLayerServer Start Menu folder. This will open the command line window.

note

Keep the command prompt window open for as long as you are working with the MapCore™ Map Layer Server. Closing the command prompt window will shut down the server.

  1. Once the message Server is up and ready to receive requests is displayed, you may operate the MapCore™ Map Layer Server. Keep the command prompt window open for as long as you are working with the server.

  2. To operate the MapCore™ Map Layer Server, follow instructions detailed in Configure the server and The web GUI.

Start Server via Windows Command Prompt​

  1. Open the command prompt (see Open the Command Prompt in Windows Operating System for detailed instructions).

  2. Issue the following commands:

cd <server executable folder>
McMapLayerServer <server execution parameters>

Run the server from the server executable folder, since it locates ServerConfig.xsd, resources.cfg and plugins.cfg relative to the current folder. Pass the server configuration file folder (C:\ProgramData\Elbit\MapLayerServer\<version> for an installed server); without it the server looks for McMapLayersServerConfig.xml in the current folder, where Setup does not place it.

Where <server executable folder> is as detailed in System Folders and Configuration Files and <server execution parameters> are as detailed in Server Execution Parameters.

Once the message Server is up and ready to receive requests is displayed, you may operate the MapCore™ Map Layer Server. Keep the command prompt window open for as long as you are working with the server.

  1. To operate the MapCore™ Map Layer Server, follow instructions detailed in Configure the server and The web GUI.

Server Update​

On Linux, stop the server and upgrade the installed packages in place by issuing sudo apt-get update followed by sudo apt-get install --only-upgrade maplayerserver (Debian, Ubuntu), or sudo dnf upgrade maplayerserver (rpm-based distributions). The mapcore7 package is upgraded in the same transaction. The server configuration file in /var/lib/maplayerserver is preserved, while any change made inside /usr/bin/maplayerserver is overwritten.

On Windows, each version is installed into its own folders (C:\Program Files\MapLayerServer\<version> and C:\ProgramData\Elbit\MapLayerServer\<version>). If you customized the server configuration file McMapLayersServerConfig.xml, copy it from C:\ProgramData\Elbit\MapLayerServer\<previous version> into the new version's folder before you uninstall the previous version, which removes it, and check that DiskCacheFolder and IntermediateFilesFolder in it point at the new version's Cache folder. The data repository folder chosen in Setup is shared by every version and is not affected by installing or uninstalling a version; choose the same one when installing the new version. If the previous version holds the service, uninstall it before installing the new version with the service task (see Run the Server as a Service).

For Docker, pull the image of the new version and recreate the container with the same data volume.

The following procedure applies to installations of earlier versions whose data repository folder is located inside the installation folder:

  1. If the server is used as a service on Windows, stop and unregister the MapCore™ Map Layer Server. Refer to Stop and Unregister the MapCore™ Map Layer Server When Used as a Service (Windows only) for detailed instructions.

  2. Based on your data configuration, do the following:

    • If your server data repository folder is in its default location (see System Folders and Configuration Files), copy the following server folders to a temporary location that is unrelated to any of the MapCore™ Map Layer Server folders:

      • /WWWRoot/Data

      • /WWWRoot/ExternalLayers

      • /WWWRoot/McLayersDataConfig.xml (if exists)

      • /MapLayerServer/McMapLayersServerConfig.xml

    • If your server data repository folder has been moved to a customized location, continue to Step #3.

  3. According to your operating system, do one of the following:

    • For Linux, continue to step #4 below.

    • For Windows, uninstall current version of the MapCore™ Map Layer Server as described in Server Uninstall.

  4. Install the new version of the MapCore™ Map Layer Server. Refer to Server Install for detailed instructions.

  5. Based on your data configuration, do the following:

    • If you copied data to a temporary location in Step 2 above, copy that data back to the default data repository folder.

    • If you server data repository folder has been moved to a customized location, you are not required to do anything else.

Server Shut Down​

This process differs based on operating system as detailed below.

note

This step is relevant only if the MapCore™ Map Layer Server is running.

Shut Down Server in Linux​

If the server runs in the foreground (for example, started by start-maplayerserver), press Ctrl+C in its console window. If it runs in a Docker container, issue the command docker stop mcmaplayerserver. Otherwise:

  1. If not already active, go to the Map Layers Server console window and issue the following command:
ps -all | grep McMapLayerServer

The result should look something like this:

4 S 0 21241 18946 0 80 0 - 172784 futex_ pts/4 00:04:44 McMapLayerServer

Where the fourth group of numbers (i.e., 21241 in the above example) is the process ID.

  1. Issue the following command:
kill -9 <ProcessID>

Where <ProcessID> is the process ID returned in the previous Step.

Shut Down Server in Windows​

If the MapCore™ Map Layer Server is running as a service (see Start the Server Automatically on Computer Startup (Running the Server as a Service)), go to Shut Down Server as Service in Windows. Otherwise:

Close the command prompt (see Close the Command Prompt).

Shut Down Server as Service in Windows​

Use either of the following alternatives:

  • Use the command prompt:

a) Go to the open the command prompt and issue the following commands:

cd <default server executable folder>
McMapLayerServer /stop

Where <default server executable folder> is as defined in System Folders and Configuration Files

b) Close the command prompt window (see Close the Command Prompt).

  • Use the Services window:

a) On the keyboard press Windows + S to open Window’s search box, enter the term services, and right-click on the relevant search result (see Figure 2-22 Services window).

b) On the Extended tab of the Services window, locate the service McMapLayersService by scrolling to it in the list of displayed services.

c) Right-click on the desired service, and then click the Stop option.

d) Close the Services window.

Server Uninstall​

To uninstall you must follow these two steps, which are further detailed below:

  1. If the MapCore™ Map Layer Server runs as a service on Windows (see Start the Server Automatically on Computer Startup (Running the Server as a Service)), the uninstaller of the version that holds the service stops and unregisters it. To remove the service without uninstalling that version, stop and unregister it as described below.

  2. Uninstall server.

Stop and Unregister the MapCore™ Map Layer Server When Used as a Service (Windows only)​

  1. Open the command prompt as an administrator (see Start the Command Prompt as an Administrator).

  2. Issue the following commands:

cd <server executable folder>
McMapLayerServer /stop
McMapLayerServer /unregister

Where <server executable folder> is the folder to which the MapCore™ Map Layer Server was installed. Use Table 2-1 Default server installation and server data repository folders per operating system for reference.

  1. Close the command prompt window (see Close the Command Prompt).

Uninstall the MapCore™ Map Layer Server​

Linux and Docker​

In the command prompt, according to your Linux setup, issue the following command:

  • For rpm-based distributions (RHEL, AlmaLinux, Rocky):
sudo dnf remove maplayerserver
  • For Debian and Ubuntu:
sudo apt-get remove maplayerserver
  • For Docker:
docker rm -f mcmaplayerserver
docker rmi mapcore.jfrog.io/c4i-mapcore-docker-release-local/mcmaplayerserver:<version>

Windows​

note

Server uninstall may only be executed by a system administrator.

  1. Locate the Apps Settings. The Settings window is typically accessibly via the Start menu or the Windows search box, and then locate the Apps option.

Figure 2-25

Figure 2-25 Windows settings

  1. Locate the MapLayerServer app and click it to select it. Locating the app may typically be achieved by scrolling through the list of apps or using the search box.

  2. Click the Uninstall button.

Figure 2-26

Figure 2-26 Windows uninstall app

  1. If prompted, confirm uninstallation.

  2. When asked whether to completely remove MapLayerServer and all of its components, click the Yes button. Alternatively, start the uninstall from the Uninstall MapLayerServer shortcut in the MapLayerServer Start Menu folder.

Figure 2-27

Figure 2-27 MapLayerServer Uninstall

  1. Upon successful completion, click the OK button.

Uninstalling removes the version's installation folder and its folder under C:\ProgramData\Elbit\MapLayerServer, including its server configuration file. The data repository folder chosen in Setup is kept.

Figure 2-28

Figure 2-28 MapLayerServer successful completion of uninstall process

Verified against MapCore 12.5.0