Mercator: a Laravel application for mapping an information system

The problem is organisational, not technical

The README opens with a diagnosis rather than a feature list: as information systems grow in complexity, organisations struggle to maintain a clear, accurate picture of what they own, how it connects, and what depends on what. Without that visibility, managing risk, ensuring compliance and responding to incidents becomes guesswork.

That framing explains what kind of tool this is. It is not a monitoring agent and not a scanner. It is a place to model the estate, and the model is what the compliance and audit features then operate on. The dependency direction is the opposite of a CMDB that ingests automatically: here a person or a script records the relationships, and the application computes the consequences.

The audience is stated as security teams, architects and IT managers, and the tool is described as giving them a shared, living representation of their digital environment, from business processes down to physical infrastructure. The emphasis on shared is doing real work. A mapping that lives in one person's spreadsheet is not usable during an incident, and a mapping that lives in a database with a login is.

The standards alignment is the other differentiator, and it is specific: ANSSI's cartography guidelines, NIS2 and ISO 27001. Those are European public sector and regulated industry frameworks, and the topic list on the repository repeats the vocabulary, including anssi, cartographie, cmdb, cpe, cve, dora, gdpr, itil, oiv and urbanisation. The project is aimed squarely at organisations that answer to those frameworks, and a tool built around a compliance model rather than a data model is a different proposition from a generic asset register.

What the application actually lets you do

The feature list is long, but several items are more than labels.

The visualisation claim is specific about its scope: graphical representations of the ecosystem including logical, administrative and physical infrastructure views. Those three views are the standard cartography layering, and treating them as separate projections of one model is what makes the output useful to different audiences, since a network diagram and a physical site plan answer different questions about the same estate.

The rest of the list covers reporting and exchange. Architecture reports are generated automatically from the model, mapping diagrams can be drawn and exported to communicate the architecture to people outside the team, and compliance levels are computed across the systems so you can see where you stand against the framework. Data export goes to Excel, CSV and PDF, which is a practical detail that decides whether a report leaves the tool or stays trapped in it.

Then the integrations, and these are the two that make the data more than a description. Vulnerability search runs through CVE-Search integration, so a component recorded in the map can be checked against known vulnerabilities rather than left as a name. And CPE support, the Common Platform Enumeration naming standard, gives enhanced system identification, which is the join key between a name in your map and a record in a vulnerability database. Without a shared identifier, a CMDB entry and a CVE entry are two unrelated strings.

The remaining items are access and identity rather than analysis. There is a REST API with JSON support for integrating with other systems, role-based access control for collaborative environments, multiple languages, and LDAP or Active Directory integration so authentication comes from the directory the organisation already runs. That last one matters more than it sounds: a mapping tool whose logins are separate from the corporate identity system will have fewer users than it should.

Running it with Docker: demo data, seeding and a persistent volume

The Docker path is the documented quick start, and the README offers three variants of the same run command.

The first starts the application with a pre-populated demo database, which is the fastest way to see what the tool looks like with data in it:

docker run -it --rm -e USE_DEMO_DATA=1 -p 8080:8080 --name mercator ghcr.io/sourcentis/mercator:latest

If you do not want the demo database, the README says the first time you start Docker you have to seed the database to create the admin user, and the seed run differs only in the environment variable:

docker run -it --rm -e SEED_DATABASE=1 -p 8080:8080 --name mercator ghcr.io/sourcentis/mercator:latest

The third variant persists your data, and this one is worth reading closely because it shows where the application expects its state to live. The SQLite file, the docs directory and the app directory are created on the host first, given to uid 1000, and then mounted into the container at fixed paths:

touch ./db.sqlite
mkdir -p ./docs ./app
chmod go= ./db.sqlite ./docs ./app
sudo chown -R 1000:1000 ./docs ./app ./db.sqlite

The mount points tell you the layout inside the image, with the database at /var/www/mercator/sql/db.sqlite, the generated documents at /var/www/mercator/storage/docs and the uploaded application files at /var/www/mercator/storage/app. The uid 1000 matters because the image creates its own user with that id, so the host files have to be owned by the same number or the container cannot write them.

When the container is up, the README points at http://127.0.0.1:8080, and the credentials for the demo instance are listed as [email protected] and password. Those are demo credentials for the seeded database, and they are the reason the seeding step exists as a separate run from the demo data run. For a production-ready environment with HTTPS and automated setup, the README points at the docker-compose folder in the repository.

One image with nginx, PHP-FPM, supervisor and four database clients

The Dockerfile is where the deployment shape becomes clear, and it is a single image rather than a set of services.

It starts FROM php:8.4-fpm-alpine, so PHP 8.4 with the FPM process manager on Alpine, and the first layer installs the system dependencies in one pass: git, curl, bash, ssmtp, graphviz, fontconfig and ttf-freefont for the diagrams, the sqlite and postgresql and mariadb client libraries, openldap-dev for the directory integration, libzip, the PNG libraries, and then nginx, gettext, supervisor and su-exec.

The PHP extensions follow, and they map one to one onto the feature list: pdo, pdo_mysql, pdo_pgsql and pdo_sqlite cover the four supported databases, intl covers the translations, zip and ldap cover archiving and directory integration, and gd covers image handling. The build dependencies are installed as a virtual package and removed again in the same layer, so the image does not carry a compiler toolchain into production.

The process management is the other half. php-fpm runs under supervisor with nginx in front of it, and the entrypoint uses su-exec to drop from root to the application user. The image creates a group and a user, both with id 1000, and the ownership of the web, log and nginx directories is set to match, with group write permission. That is the same uid 1000 you saw in the persistence instructions, and the two are consistent: the container runs as a non-root user whose id you must match on the host.

One more detail is worth copying into your own images. A small ini file is written at build time to send PHP fatal errors to the Docker logs, by turning log_errors on, pointing error_log at /proc/self/fd/2, setting error_reporting to E_ALL and turning display_errors off. Without that, a fatal error in a container is invisible.

The version is injected rather than hard-coded, through a build argument VERSION that becomes the APP_VERSION environment variable, and the working directory is /var/www/mercator.

Configuration: the .env file, rate limiting and the app key

The .env.example in the repository is the configuration reference, and its comments are more informative than a separate document would be.

The application basics are at the top: APP_NAME is Mercator, APP_ENV defaults to local, APP_URL is http://localhost:8080, and APP_FORCE_HTTPS is false. APP_KEY is left empty, which is a line to notice, because an unset key in a Laravel application is a deployment error rather than a default.

The database block is where the choice of engine is made, and the example defaults to MySQL on 127.0.0.1 with a database called mercator. The README's technology list names MariaDB, MySQL, PostgreSQL and SQLite as supported, and the Dockerfile installs the client libraries and PDO drivers for all four, so the switch is a matter of changing the connection settings and the appropriate driver rather than rebuilding anything.

The rate limiting block is the part with the most explicit guidance. The settings are API_RATE_LIMIT and API_RATE_LIMIT_DECAY, and the comments give the format as requests per decay window in minutes, with four worked examples: 60,1 for normal usage, 120,1 for development and testing, 1000,60 for a public API, and 10000,1440 for third party integrations. The comment also states the behaviour, an HTTP 429 Too Many Requests when the limit is exceeded.

The mail block sets the sender identity for the password reset emails, with MAIL_FROM_ADDRESS and MAIL_FROM_NAME, and the ssmtp package in the image is what actually delivers them. Password reset by email is the reason that package is installed, and it is also the reason the SMTP configuration has to be correct in a real deployment, since a cartography tool whose password reset mail never arrives is a tool that gets shared passwords over chat instead.

The stack: Laravel 12, Vite, and Graphviz compiled to WebAssembly

The package.json shows the front end and the JavaScript dependencies, and a few of them explain how the drawing features work.

The base is Laravel 12 with Sanctum 3, which is the token layer behind the REST API, so a machine-to-machine integration authenticates with a Sanctum token rather than a session cookie. The front end is built with Vite, with a dev script, a build script and a watch script that runs node watch-and-sync.mjs, so the JavaScript is compiled as an asset bundle rather than served from a CDN.

The interesting dependency is @hpcc-js/wasm-graphviz. That is Graphviz compiled to WebAssembly, which means the diagram rendering happens in the browser. The alternative would be a Graphviz binary on the server, and the image installs the graphviz package, so both routes exist: a server side renderer for generated reports, and a WebAssembly one for interactive drawing in the browser. The fontconfig and ttf-freefont packages in the image are the server side counterpart, because Graphviz needs fonts to lay out text.

There is also chart.js for the compliance and reporting charts, @maxgraph/core for the diagram editing canvas, the CKEditor build for rich text in the description fields, bootstrap 5 and bootstrap-icons for the interface, and @sourcentis/bpmn-editor, which is the BPMN editor dependency. The BPMN part deserves a note, because business process modelling is the top layer of the cartography, and the scripts show how it is developed: bpmn:use-local symlinks a sibling checkout of the editor into node_modules and rebuilds, bpmn:use-npm does the same from the published package, and bpmn:build-local builds the sibling directly. So the editor is a separate repository that is consumed either as a published npm package or as a local working copy, which is a sensible arrangement for a component that is developed in step with the application.

The package.json also carries a mismatch worth flagging: the description, the license badge, the contributors badge and the repository field all still point at the dbarzin/mercator GitHub project, while the package version 2026.10.11 and the repository name are the current ones. The project has moved, and some of its metadata has not caught up.

Licence, releases and the OW2 footprint

Mercator is GPL-3.0, and the LICENSE file sits at the root of the repository. That is the licence to plan around rather than the permissive one, so if you intend to modify it and run a modified version as a service for others, the copyleft obligations are a conversation for your legal team. Nothing here is legal advice; the point is that this is not MIT, and a project that stores an inventory of your systems, its vulnerabilities and its compliance status is the kind of thing organisations want to modify.

The release cadence is fast and the versioning is calendar based. The recent tags are 2026.10.11 and mercator-2026.10.11, both on 2026-10-11, followed by 2026.10.10 on 2026-10-10, and the version string in package.json is 2026.10.11, with a version.txt file at the root. The last push to the repository was on 2026-10-19, three days before the newest release, so the tree is being worked on. Dated releases mean you can tell exactly which build you deployed, which is what you want for an audit trail.

The project also has an Artifact Hub badge and an OW2 Project badge, and the OW2 listing indicates the project is part of the OW2 open source landscape rather than being a private company tool with a public repository. The Docker image is published at ghcr.io/sourcentis/mercator, and there is a docker-compose folder in the repository for a production setup with HTTPS and automated setup, alongside a Dockerfile at the root and a build.sh.

The rest of the tree is a conventional Laravel application with a large surface. There are app, bootstrap, config, database, docs, guides, public, resources, routes, storage and tests directories, plus phpstan.neon for static analysis, phpunit.xml for tests, mkdocs.yml with a requirements-docs.txt for the documentation, an artifacthub-repo.yml for the Helm chart repository, an .env.ci and an .env.testing alongside the .env.example and .env.sqlite, and an anonymize.sh script. A SECURITY.md is present as well, which is worth reading before you load real inventory data into a deployment.

The README is also available in French, with the Roadmap document in French too, and the documentation site is published through the pages branch at sourcentis.github.io/mercator.

Editorial conclusion

Adopt Mercator if you are a security team, an architect or an IT manager who has to hold a shared, auditable picture of what the organisation owns and how the pieces depend on each other, and you want an open source tool that maps to ANSSI cartography, NIS2 and ISO 27001 rather than a vendor CMDB. Do not adopt it as a replacement for a live asset discovery agent, since the application records and models what you tell it rather than scanning your network, and do not adopt it if you need a bare metal install without a container runtime, because the documented paths are Docker and per distribution guides. Verify first that the database you pick is one of the four the project supports, MariaDB, MySQL, PostgreSQL or SQLite, that you set APP_KEY before exposing the instance, and that the API rate limit values in .env.example suit the number of machines that will call the REST API.

Frequently asked questions

Official sources

1. Issues
2. License: GPL-3.0
3. README
4. Releases
5. sourcentis/mercator on GitHub