Skip to main content

Install on Linux

Map Layer Server ships as a native package, maplayerserver, from the same repositories as MapCore itself. A debug build is published in parallel as maplayerserver-debug.

Prerequisites​

The package depends on mapcore7 at exactly the same version — not "at least", exactly. The two are built and released together, so your package manager will install or upgrade mapcore7 alongside the server, and it will refuse a combination that would pair the server with a different MapCore. That is deliberate: there is no supported mix-and-match.

You therefore do not need to install mapcore7 first. If you already have it, expect the server's install to upgrade or downgrade it to match.

The graphics libraries mapcore7 needs are listed under Install on Linux. They apply here too: the server renders map tiles, so it needs them even though it has no window of its own.

Install from the MapCore repository​

Configure the repository exactly as for MapCore — the credentials, the codename table and the unsigned-repository warning are all in Install on Linux. With that in place:

sudo apt-get install maplayerserver # Debian, Ubuntu
sudo dnf install maplayerserver # RHEL, AlmaLinux, Rocky

To pin a version, remember that package versions use a tilde where release names use a hyphen — 12.5.0-alpha9 is 12.5.0~alpha9:

sudo apt-get install maplayerserver=12.5.0~alpha9
sudo dnf install maplayerserver-12.5.0~alpha9

Install from a downloaded package​

sudo dnf install ./maplayerserver-<version>.x86_64.rpm
sudo apt install ./maplayerserver_<version>_amd64.deb

Both resolve the mapcore7 dependency from the repository if it is configured. If it is not, put the matching mapcore7 package in the same directory and install both in one command, or the exact-version dependency will fail with nothing available to satisfy it.

What you get​

/usr/bin/maplayerserver/ install tree, read-only
/usr/bin/maplayerserver/McMapLayerServer the server binary
/usr/bin/maplayerserver/WWWRoot/ web GUI and the served assets
/usr/bin/maplayerserver/WWWRoot/Export/Packages/ export output, writable
/usr/bin/start-maplayerserver the wrapper you run
/var/lib/maplayerserver/McMapLayersServerConfig.xml the configuration, writable

The split is a security boundary, not tidiness. The server rewrites its configuration on every layer change and writes export packages while running, so both locations must be writable — and both are kept outside the install tree, so that a writable path can never be used to replace the server binary or the libraries and configuration it loads.

note

McMapLayersServerConfig.xml is packaged as a no-replace configuration file, so an upgrade keeps the copy you have been editing and leaves the new default beside it. Your layer definitions survive upgrades; a new configuration option does not appear in your file automatically.

Start the server​

sudo start-maplayerserver

It prints the configuration it is using and runs in the foreground. The defaults:

OptionDefault
--host0.0.0.0All interfaces
--port6767
--threads00 or 1 means "choose": CPU cores × 2, plus one for the main thread
--www-root/usr/bin/maplayerserver/WWWRoot/
--conf-dir/var/lib/maplayerserverWhere McMapLayersServerConfig.xml lives
--data-dir/mnt/ServerDataImport and temporary data
sudo start-maplayerserver --host 127.0.0.1 --port 8080 --data-dir /srv/mapdata

Two things about that wrapper are worth knowing before you replace it with something of your own:

  • It changes into /usr/bin/maplayerserver before starting the server, because the server resolves ServerConfig.xsd, resources.cfg, plugins.cfg and graphics.cfg relative to the working directory. Launch McMapLayerServer directly from elsewhere and it will not find them.
  • The binary takes those six settings positionally, in the order above, with no flags and no defaults. The wrapper exists to turn them into named options.
warning

/mnt/ServerData is a default, not a directory the package creates. Create it before the first start, or pass --data-dir somewhere that exists.

Verify​

curl -s -o /dev/null -w '%{http_code}\n' http://localhost:6767/

200 means the server is up and serving its web root. Open the same URL in a browser for the web GUI, which is the quickest way to confirm it can also read your layers.

Upgrading​

sudo apt-get update && sudo apt-get install --only-upgrade maplayerserver
sudo dnf upgrade maplayerserver

Because the dependency is pinned to an exact version, this upgrades mapcore7 in the same transaction. Stop the server first. A running process keeps the files it already has open, so it will not crash — but it is then a mix: the old binary against a new install tree, loading any plugin or asset it opens next from the new version. Restart it and the ambiguity goes away.

Your configuration is preserved. What is not preserved is anything you edited inside /usr/bin/maplayerserver — that tree belongs to the package and an upgrade overwrites it. If you have customised the served web assets, keep them somewhere else and point --www-root at them.

Verified against MapCore 12.5.0

Written from packaging/nfpm/maplayerserver.yaml, packaging/nfpm/scripts/maplayerserver-postinstall.sh, packaging/nfpm/nfpmbuild.sh, MapCore/Tools/MapLayerServer/start-maplayerserver