Skip to main content

Installation Overview

Choose the installation path that fits your platform. All options require Java 21.

What you'll need​

  • JDK 21 on PATH (java -version → 21.x)
  • Outbound HTTPS to fetch packages/binaries
  • Open ports for your use case (e.g., 8080 for REST API; MQTT/AMQP/etc. per config)
  • Admin/root privileges for package installs and service setup

Version token: the docs use {MAPS_VERSION} where a version appears. Example: 4.0.1.

Pick an installation method​

MethodBest forPackageNotes
Debian/Ubuntu (APT)Debian/Ubuntu serversmaps, maps-mlRelease & Snapshot channels, systemd service
RPM/YUM (RHEL/Fedora)RHEL/CentOS/Alma/Rocky/Fedoramaps, maps-mlRelease & Snapshot repos, systemd service
Windows (MSI)Windows 10/11 & ServerMSIGUI or silent install; optional Windows Service
Archive (zip/tar.gz)Any OS with JDK 21zip / tar.gzUnpack & run scripts (bin/start.*)

Looking for orchestration? See Container Deployment and Kubernetes.

Quick start (after install)​

  1. Start the service or script

    • Linux (systemd): sudo systemctl enable --now maps (or maps-ml)
    • Windows Service (if installed): start from Services or PowerShell
    • Archive: ./bin/start.sh (Linux/macOS) or bin\start.bat (Windows)

  2. Verify

    # REST ping
    curl -s http://localhost:8080/api/v1/ping
    # -> {"status":"Success"}

    # Health
    curl -s http://localhost:8080/health
    # -> OK | Warning | Error

Upgrades & rollback (high level)​

  • APT / YUM: use your platform’s standard upgrade flow. You can keep Release default and selectively pull from Snapshot.
  • Windows MSI: re-run a newer MSI (GUI or /qn); most installs upgrade in place.
  • Archive: extract a new version to a new folder, copy your conf/ (and data if needed), and start the new version. Roll back by switching folders.

Troubleshooting​

  • java not found: install JDK 21 or set JAVA_HOME and update PATH.
  • Repo/key errors: re-import the GPG key and refresh metadata (see the per-OS guides).
  • Firewall/ports: ensure the chosen ports are reachable locally and from clients.
  • Logs: use journalctl -u maps on Linux; Event Viewer or console output on Windows; archive installs log to the console by default.