Server: Publish Web Maps

Manifold Server, called Server for short, is a read-only, parallel, spatial database server that also includes a TCP data sharing server, an HTTP map server and WMS server.  This topic discusses use of Manifold Server as an HTTP server to serve maps to the web.

 

Server can run in three modes:

 

 

 

 

See the Manifold Server, topic for basic instructions on installing, activating, and running Manifold server in either TCP or HTTP mode, including a complete list of command line options.

 

To use the Manage Services dialog,  a Server license must be installed for all users.   If the license is not installed for all users, it will not be possible to run new services from the dialog.  Check that setting in the Help - About dialog to verify that the license has been installed for all users.

HTTP Server

When run as an HTTP server, a Server service or Server instance run from a command prompt creates a web page that can be viewed by Internet browsers at the URL for the IP address specified.   

 

This allows Manifold users to create a GIS-enabled web page without any need to install and configure a web server (such as Internet Information Server or Apache): Server includes an HTTP server to provide web server functionality.  No map server, like MapServer or Manifold Release 8 Internet Map Server, is required either.   All you need to serve Manifold GIS-enabled web pages is Manifold Universal edition or Manifold Server edition installed on the computer that will be serving web pages.   If you have a static IP address reachable from Internet, you can create GIS-enabled web pages browsable worldwide through Internet.  No programming is required.

 

When the HTTP server creates a web page, it automatically also creates an OGC WMS 1.3.0 compliant WMS data source that any client capable of using WMS can use.

Overview

 

 

 

 

 

 

 

 

 

 

 

Example

In this topic we serve a map to the web that is created using the meteorites.map example project from the Release 9 Downloads page.   

 

We begin by launching Manifold in the usual way on the server machine, and we open the meteorites.map project that contains the map to be served.

 

 

We open the Map component, and using the Layers pane we configure it with a scale bar and legend as seen above.   We configure the Map component with layers as desired.  Note that one of the layers is a Bing street map layer.   When publishing maps to the web we should be careful using Bing or Google layers, since many visitors to our web site could use up our free use of Bing or Google very quickly.  For large volume uses we should have a paid API key that allows larger use of Bing or Google layers.

 

Server publishes the map as we configure it in a totally WYSIWYG (What You See Is What You Get) way, so we arrange all the layers and any minimum or maximum scales to turn layers on and off as desired.  The map served to the web will behave the same way as the map in the desktop Manifold session.

 

When we are happy with how we have arranged the map, we Save the project and then we Close the project.

 

To serve a map top the web, we can use Manifold Server as an HTTP server, launching multiple instances either as services or launching a single service from a command prompt window.  In this topic we first describe how to launch an HTTP server as a service, and then in later sections we describe how to launch an HTTP server from a command prompt window.

Launching an HTTP Server as a Service

When using a Manifold 9 Server license, Manifold Server instances can  be launched as Windows services using the new Tools - Manage Services dialog within Manifold.  That is a lot easier than launching Server from a Command Prompt window as illustrated below, although a Manifold 9 Server license also allows launching Server from a Command Prompt window.   

 

Begin by launching Manifold as regular interactive session, but using Run as Administrator (or using a login with Administrator privileges) to launch Manifold with Administrator privileges.

 

Choose Tools - Manage Services to launch the Manage Services dialog.

 

 

 Press the Add button to add a new service.

 

 

In this example we use the example project introduced at the beginning of this topic.

 

In the Service dialog, enter the path to the executable file and to the .map file.  Enter the IP address and the port to use.

 

For Options, enter

 

-type:http -component:"Map"

 

...to specify an HTTP server and the component name to use in the .map project.  In real life, we would probably add a -connections:0 option for unlimited connections.  Options are listed in the Options section of the Manifold Server topic.

 

Press OK.

 

 

That adds a new service, which has not yet been started.  Ctrl-click the service to select it.

 

 

 Press the Start button.  That will start all selected services.

 

 

The service is now running.  The web site is live, with the map page being served to that IP address and the port specified.

 

 If this is the first time we are launching manifoldsrv.exe in HTTP mode, we should make sure to add it as an exception to Windows Defender Firewall, so people on other computers can browse the web page it is serving.

 

We can now launch a browser on the machine or on any other machine on our network and visit the URL

 

http://192.168.2.12:8080

 

That will launch the web page served by Server in HTTP server mode.  

Stopping a Service

We can stop a Server service at any time by launching Manifold with Administrator privileges and choosing Tools - Manage Services to launch the Manage Services dialog.

 

 

 Ctrl-click the service to be stopped to select it, and then press the Stop button.

 

Adding Another Web Page

We can add another HTTP server service that serves a different map from a different project.

 

Launch Manifold with Administrator privileges and choose Tools - Manage Services.   In the Manage Services dialog press the Add button to add another service.

 

 

Configure the Service dialog with the path to the .map project to use.  Choose a different port, in this case using the default port 80 for HTTP sites.

 

The Options string chooses a server type of HTTP and gives the name of the component to serve as a map:

 

-type:http -component:"Cities and Provinces of Mexico"

 

In real life, we would probably add a -connections:0 option for unlimited connections.

 

Press OK.

 

 

That adds another service to the Manage Services dialog.  

 

 We can ctrl-click that service to select it, and press the Start button to start it running.

 

We now have two different web map pages being served by Server as an HTTP server on the same machine.  Both use the same IP address, but one uses port 8080 and the other port 80.

Changing a Services Project

Changing a component used by a service is easy.  

 

Changing the content of a map served as a service:

 

  1. In the Manage Services dialog, ctrl-click the service to be changed and stop it.  Close the dialog

  2. Open the project in a regular Manifold session.   

  3. Change the component as desired.

  4. Save the project, and then close the project.

  5. In the Manage Services dialog, ctrl-click the service to be changed and start it.

 

The usual situation is that we want to tinker with the component that is being published as a web map, for example, changing style in layers or adding or deleting layers.  The above makes that very, very easy.  Just stop the service, launch the project and change the map, and save it and close it.  Start the service again and the changes are live on the web site.  Any refresh of the web page shows the new content.

 

If we want to make other changes, like changing the component served, after stopping the service we can double-click it to launch the Service dialog.  That allows us to change ports, the component that is served or the project used or other parameters.

Launch an HTTP Server from a Command Prompt

Server can be launched from a Command Prompt window when using a Manifold 9 Universal or a Manifold 9 Server license.   In this example a portable Manifold installation is being used for both server and client.


In this example we use the example project introduced at the beginning of this topic.

 

Launch a command prompt window as Administrator (in the Windows Start menu, right click the Command Prompt app and choose Run as Administrator).

 

 

Navigate into the Manifold installation folder containing the manifoldsrv.exe file.  

 

 

Launch the manifoldsrv.exe file (enter manifoldsrv and press Enter) without any arguments to see syntax and options.  Note that some options, such as -user, -password, and -workers, are not used with the HTTP server.

 

 

Use the -type:http  option to launch Server as an HTTP server.   We want Server to listen to the IP address used by the machine on the local area network, using port 8080 so the default port used for HTTP web service remains free to use for regular web servers if we want.

 

For this example we launch Server using the meteorites.map project we have configured.   We want Server to display the Map component in that project.

 

The command line used is:

 

manifoldsrv -type:http -addr:192.168.2.12 -port:8080 -component:"Map" "C:\mfd\projects\meteorites.map"

 

We only need quotes around the name of the component or the path to the file name if any part has a space character in it.   There are no spaces in the component name or path to the project file in the example above, but we use quotes anyway.  It is good to get in the habit of using quotes for when we will use a component name or path with a space character in it.

 

This is a typical example for local, casual use of the HTTP server.  In real life, serving a map to the great big Internet, we would probably add a -connections:0 option as well, to use an unlimited number of connections (requires a Manifold Server edition license).

 

 

Server starts up and announces the options it is using.   The web page is now live.  Easy!

 

Leave the Command Prompt window open and do not log out from the account being used.  Server will continue to run so long as the Command Prompt window is open, we do not press Ctrl-C or Ctrl-Break, and we do not log out of the account being used.   If we do not want other people using a computer that has an opened Command Prompt window, lock the screen by simultaneously pressing the Windows logo key and L.

 

 If this is the first time we are launching manifoldsrv.exe in HTTP mode, we should make sure to add it as an exception to Windows Defender Firewall, so people on other computers can browse the web page it is serving.

 

We can now launch a browser on the machine or on any other machine on our network and visit the URL

 

http://192.168.2.12:8080

 

That will launch the web page served by Server in HTTP server mode.  

Stopping a Command Prompt HTTP Server

When an HTTP server is launched from a Command Prompt window, stop Server by closing the Command Prompt window in which the Server session is running, or, with the focus on the Command Prompt window, pressing Ctrl-C or Ctrl-Break.   Logging out from the user account used for the Command Prompt session will also shut down Server.

Changing a Command Prompt HTTP Server Project

Server publishes a web map using whatever .map project was specified in the command line to launch Server.   While Server is using that project, Manifold desktop sessions cannot open that same project for editing.

 

Changing the content of a project used by Server:

 

  1. Shut down Server.

  2. Open the project in a regular Manifold session.   

  3. Change the project as desired.

  4. Save the project, and then close the project.

  5. In a Command Prompt window, launch Server again with that project.

 

To change the .map project that is used by Server, shut down Server and then launch it again using the edited or different .map project.  Use keyboard shortcuts in the Command Prompt window to avoid lots of unnecessary keyboarding.  

 

For example, suppose we have an HTTP server running in a Command Prompt window.   We want to edit the file it is using, perhaps to change the layers in the map or the Style of some of the layers.   The fast way to do that is to press Ctrl-C in the Command Prompt window to stop Server.   Next, without closing or doing anything in the Command Prompt window, in a regular Manifold session open the .map project that was being used by Server.  Change the project as desired, save it, and then close the project in the Manifold session.

 

Back in the Command Prompt window, press the up arrow key on the keyboard.  That will reload the last-used command line, which was used to launch Server with that .map project file and other options, such as the component used for the web map.  Press Enter and Server is now running just as before as an HTTP server with the updated .map project file.

Default Web Page User Interface

The web page served by the HTTP server shows the name of the served component (usually a map) in the page title, and in larger text above the map window.  In the project being served, specify a name for the component to be served that makes sense for the web page.  For example, choose a name like Cities and States of Mexico and not just Map.

 

The example below uses Microsoft's Bing browser:

 

 

The web page is exactly a WYSIWYG version of the Map component we configured in the project.  The web page shows the name of the served component in the page title above the map, in this case Map.  A better choice for a name for the map would have been Lunar and Martian Meteorites.  If the served component has a description entered in the Info pane, that description will be displayed in a second line below the name of the served component.  Using a description is a handy way to add quick instructions, such as Mobile users: Click / tap to center on that spot.

 

Important: When providing a description for a map in the Info pane, make sure to edit the description of the map component instead of the description of the active layer.  When the focus is on an open map window, the Info pane shows the descriptions both for the map and also for the active layer.  Click the upper [...] "more" button to enter a description for the map.

 

The page also includes a manifold.net watermark in the middle of the bottom margin of the display.

 

The default web page generated by the HTTP server includes buttons in a toolbar in the upper center of the map for common commands such as  zoom in, zoom out, and zoom to fit. The extent used by zoom to fit ignores layers for web images such as Google or Bing unless all other layers in the map are empty.   If there are locations in the project being served, a Locations button will appear in the toolbar.  The toolbar is positioned adjacent to the top edge of the web image to save space.  Hovering the mouse over a toolbar button shows a tooltip.

 

Controls

Collapse / Expand - Reduce the toolbar to a single button, or expand it to show all buttons.

Zoom In - Zoom the view further in.

Zoom Out - Zoom the view further out.

Zoom In - Zoom the view to show the contents of all layers, ignoring layers for web images such as Google or Bing unless all other layers in the map are empty.

Info - Shows object fields (attributes) in the layers which are visible and which have a Layers pane pick status other than "no pick."   Press the button and the cursor switches to a cross.  Click on the desired object and a display reporting field values pops open.
 
The field values display remains open (allowing users to highlight a field's contents and copy with a Ctrl-C or a right-click and Copy) until another location is clicked or Info mode is exited. Press the Info button again to exit Info mode.
 
The Info button appears in the toolbar only if the component being served has layers that can be visible and which have a Layers pane pick status other than "no pick."
 
If the map being served has more than one visible layer with a pick status other than "no pick", the Info pane display will included a dropdown list box that allows choosing the layer for which a click will display field values.   The default choice is auto, which shows field values for clicked objects that are in the uppermost layer which is visible and which has a pick status other than "no pick."

Locations - Provides a drop down menu of Locations.   Choose a Location to pan and zoom to that location.  The Locations button appears in the toolbar only if the project being served has some Locations in it.

Layers - Provides a drop down menu of layers in the map that can be turned on and off.  Layer folders within the map are treated as top level layers to be shown in the Layers button menu.  When a component has only one layer, that single layer cannot be turned off.  The Layers button appears in the toolbar only if the component being served has layers in it that can appear in the Layers button.

 

Pan the map using the mouse cursor with a click and drag motion. Pressing Escape while panning cancels the operation.

 

Zoom the map using the zoom buttons in the upper left corner, or by using the mouse wheel.  Zooming using the mouse wheel zooms in and out on the location under the mouse cursor.  Multiple rapid zooms, that is, multiple clicks, using the mouse wheel are combined together with the map being updated after the wheel has not been scrolled for 1 second.

Descriptions

When a layer in a map or a location in a project has text in the descriptions property, the descriptions text will appear in lighter text below the name of the layer or description in the drop down list provided by the Layers button or Locations button in the web user interface.

 

 

Add a description to a location by opening the location (double-click it in the Project pane) and then in the Info pane clicking the [...] button for the  Description.  In the Description dialog enter the description and then press OK.

 

To remove a description, open the description as above and delete all text in the Description pane and then press OK.

 

 

If either a location or a layer in a map has no description, none will appear in the drop down list.

Info Button

The Info tool reports attribute fields for objects in the topmost visible layer that has a Layers pane pick mode other than "no pick" and which is currently visible.  If multiple objects in the  topmost layer overlap at the clicked location, the Info tool will pick one of them to display attributes.  It shows all fields in the order specified by the schema except binary fields, which are not reported.   The Info tool retrieves and displays field values from the server asynchronously without reloading the page.

 

Field values are displayed using the styles set in the table window for the layer's table.  Text fields in the table that have been styled as email or URLs will be displayed as hyperlinks: a click on the displayed hyperlink will launch it as an email link or as a URL in a new browser tab.

 

The Info tool excludes layers that are currently hidden, for example, because they are dynamically hidden at the current zoom level by min / max scale settings as set up in the Layers pane for the component being served, because they are explicitly hidden because the layers button in the web UI toolbar has the layer turned off, or because the layer has been implicitly hidden in the original component being served and does not appear at all in the layers button list in the web UI.

 

The Info tool also works on touch screens.

Mobile / Touchscreen User Interface

The HTTP server Javascript control detects when the page is being viewed on a device that has a touchscreen interface, for example a mobile device such as a telephone, and adjusts the user interface to make it easier to use the site by tapping with fingers on the touchscreen:

 

 

 

 

At present, the HTTP server Javascript control does not automatically resize the image based on the display device or browser window size.   That capability is expected to be added in the future.  Until then, if the web display is intended for mobile devices like telephones, specify an image size using the cx and cy options that is a reasonable match to the display size and aspect ratio users are expected to have. See the Options section in the Manifold Server topic.

For Web Developers

It is easy to put the map served by the HTTP server into an existing web site.  The HTML code to do so looks like this:

 

<script src="webscript.js"></script>

<script>

 

  window.onload = function () {

    let config = {

      bounds: { xmin: xxx, ymin: xxx, xmax: xxx, ymax: xxx, },

      cx: 800,

      cy: 800,

      urlbase: "/",

    };

    manifold.createMap(document.querySelector("#map"), config);

  };

 

</script>

 

...

 

<div id="map"></div>

 

The above can be put into an existing web site served by some other web server, like Microsoft Internet Information Server (IIS) or Apache. The URL for the script and the urlbase config parameter will have to be adjusted to point to an appropriate instance of the Manifold HTTP server.

 

When the web page loads, the script defines the manifold object and the call to manifold.createMap will create all necessary HTML elements for the map UI in the specified div, style them and wire them to events. The content of the div will then display the map served by the Manifold HTTP server and allow operating it.   Future extensions to the map UI will only affect the config section in the inserted code.

 

REST Endpoints

 

 

 

 

 

Example

Entering a URL that has the IP address of a running Server instance such as http://192.168.2.36/config will report the running configuration of that Server instance in plain text:

 

{

bounds: { xmin: -20037508.342789233, ymin: -23250277.329460155, xmax: 20037508.342789244, ymax: 18428920.012950014, },

layers: [

{ name: "Countries Labels", id: 3, visible: true, },

{ name: "Countries", id: 9, visible: true, },

{ name: "Bing Maps Street Map Image", id: 10, visible: false, },

],

locations: [

{ name: "Cape Town", centerX: 2051107.386994766, centerY: -4018653.0920721362, scale: 15.448851675508728, },

{ name: "New York", centerX: -8236647.6722477125, centerY: 4972723.067661641, scale: 43.054810323796346, },

{ name: "Paris", centerX: 261016.2998893885, centerY: 6251395.90149811, scale: 60.65963437999172, },

{ name: "Sydney", centerX: 16832676.800296493, centerY: -4012598.5723743583, scale: 38.286399302586474, },

],

cx: 1200,

cy: 600,

}

 

We can then use the layer IDs reported to turn layers off and on.  For example, a URL for the above Server instance such as http://192.168.2.36/map?size=400,600&layermod=h9s3s10 will create an image that is 400 pixels wide and 600 pixels high that hides the Countries layer while showing the Countries Labels and Bing layers.

 

Note that the coordinates reported by /config are in the coordinate system of the component being served.  The map uses Pseudo Mercator in this example so the coordinates are in that system using meters, not in Latitude / Longitude using degrees.

Add Server as an Exception to Windows Defender Firewall

When running Server as an HTTP Server, to see the map web page it generates from Internet (or from different computers in our local network),  we must add the manifoldsrv.exe executable file we are using as an exception to Windows Defender Firewall.  That will allow Server to serve maps to the web on private and public networks, so users from Internet or from other computers on our private network can connect to the web page Server is operating and see the map being served.  The following example shows Windows Defender Firewall in Windows 11.   Other Windows versions are similar.   

 

From the Windows Start button, use the search box to search for Windows Firewall and to launch the app.

 

 

Click on the Allow an app or feature... choice.

 

 

Click oin the Allow another app... button.

 

 

Click the Browse... button.

 

 

In the Browse dialog, navigate to the installation folder for Manifold.  Click on the manifoldsrv.exe file and press  Open.

 

Note that in the above dialog we are using a portable installation.  Many users who work with portable installations copy the files for the portable installation into some standard folder, like C:/mfd/portable/ so the executable files are always in the same folder and path.   If we keep our portable installation files in different folders, using a different manifoldsrv.exe  file to launch server, then each such different manifoldsrv.exe file will have to be added as an exception to Windows Defender Firewall.

 

 

That adds the manifoldsrv.exe file to the Add an app dialog.   Press Network types... to choose the network types for which it will be allowed by Windows Defender Firewall.

 

 

Check both boxes to allow access through both private and public networks and press OK.  

 

 

Press Add.  That adds manifoldsrv.exe as an exception to the Windows Defender Firewall list.   Press the OK buttons up through the Windows Defender Firewall dialogs to finish configuring Windows Defender Firewall.

 

Notes

Console title - When launched in a Command Prompt window, Server sets the console title to Server - addr:port - filename. This hides sensitive information like user logins and passwords and it also shows connection information even if that was not spelled out in the command line.   The console window will show the server type (HTTP or TCP) in the window caption when Server is run in a console window.

 

Specifying Ports - We can use whatever port we like for the HTTP server's port so long as it does not conflict with a port used by other programs.   Port 80 is the default port assigned by IANA for HTTP servers so that is the default used by Manifold Server for HTTP.   IANA lists ports 591, 8008, and 8080 as alternate ports for use by HTTP servers.   This documentation uses 8080 as an alternate port since that is easy to remember.   If we are using Server on a machine that also hosts a web server like IIS or Apache, it might be a good idea to use a high port number that is highly unlikely to be used by some other software on the machine.  For example, IANA lists ports 44300 to 44399 as unused.  We could use ports like 44380, 44381, 44382, and so on for different Manifold HTTP server pages.

 

One instance per web page - When using the HTTP server javascript control in a web page there currently can be only one instance of the Manifold Javascript control per web page.  Attempting to create a second instance or to reinitialize an existing instance of the Javascript control provided by the HTTP server does nothing.  This limitation will be removed in the future.

 

Safety first - The HTTP server provides safeties if the image size is specified to be very small: If the size of the Javascript control (the web UI) provided by the HTTP server is less than 200 x 200 pixels, the control reduces to a static image and the toolbar will be turned off for lack of space. Panning and zooming using the cursor also will be turned off for lack of a way to get back to the original extent (also, because the image might be too small to do panning and zooming in general).

 

Server-side Cache priorities - The HTTP server caches images that have been generated to serve browser requests.  It uses the following priorities for the image cache: full view is prioritized over any other view, and views showing default layers are prioritized over views with some layers turned on or off.  A related topic is persistent cache of external data sources used in the map being served.  See the Cache in Server Projects topic.

 

Non-routable IP addresses - The examples in this documentation use non-routable IP addresses beginning with 192....  Such IP addresses may be visible on your local network, but they cannot be visited across Internet.  When connecting to Server through the Internet, either for sharing data using the TCP server or for publishing maps using the HTTP server, the computer should have a static IP address that is routable (visible over Internet), like 20.81.111.85, and the Server instances that are launched should use that IP address.

See Also

Manifold Server

 

Server: Share Data

 

Server: WMS Server

 

Cache in Server Projects

 

Favorite Data Sources

 

File - Create - New Data Source

 

Tools - Manage Services

 

Command Window

 

Query Builder