Skip to content

Operational Map

The Operational Map plots active and planned Mission Plans with deployment coordinates. Mission Plan validation normalizes MGRS and converts it to latitude/longitude before the map loads. Expired missions and missions without coordinates are omitted. Object permissions apply to both missions and basemaps.

Configure private atlas storage

The map requires Python 3.11 or later for SQLite resource limits. RAMP's Python 3.12 runtime meets this requirement. Archives are stored outside Nautobot's ordinary media/static directories and downloaded through a permission-checked route. New uploads must use the .mbtiles extension; the stored filename is generated by the server.

Add the following entry to your existing PLUGINS_CONFIG in nautobot_config.py:

PLUGINS_CONFIG["nautobot_trax"] = {
    "map_storage_root": "/opt/nautobot/trax-private-map-tiles",
    "enable_demo_user": False,
    "map_max_upload_bytes": 5 * 1024**3,
    "map_validation_timeout": 30,
    "map_tile_timeout": 2,
}

The storage root must be an absolute path outside MEDIA_ROOT and STATIC_ROOT. It must be writable by the Nautobot service account. With the standard media layout, the default is the trax-private-map-tiles directory beside media. Back it with persistent storage and include it in protected backups. A Docker container's writable layer alone is not persistent application storage.

Mount the same private volume in web, worker, and migration/init services. For example, add trax_map_tiles_private:/opt/nautobot/trax-private-map-tiles to their Compose volumes and declare trax_map_tiles_private in the top-level volumes. Prepare the directory with the Nautobot user's ownership and mode 0700 in the image or volume initialization. The supplied development setup includes this named volume and prepares the image directory. Do not expose it through a proxy, static-file service, or Docker build context.

Verify a deployment

After installation, upgrades, restores, or container recreation, run:

nautobot-server check_map_storage

This command checks that the configured private directory is writable and that every referenced archive is readable and has a SQLite header. It creates and immediately removes a temporary write probe; it never changes uploaded archives or database records. It exits nonzero on failure. Use --active-only to check only the basemaps offered on the Operational Map. This is an availability check, not a complete integrity scan of every tile in a large package.

Run it as the Nautobot service account in each web and worker instance. A VM needs a persistent private directory, Docker needs a persistent mount, and Kubernetes needs persistent storage accessible to the relevant pods. Multiple web instances must have access to the same archive versions. TRAX can check accessibility; it cannot determine whether a directory will survive replacement of a host, container, or pod. Back up archives together with the database.

Map Tile Sets display a live Archive Status of ready or unavailable in the list, detail view, and REST API (archive_status, read-only). Activation and availability are independent: an active record with missing storage is not ready. The map excludes unavailable basemaps and lists their names only for users who may view them. Restore the original archive or upload a replacement through TRAX. Availability is checked again on the next request, so restoration needs no status reset or cache purge. Do not use Redis or browser caches as archive backups.

Upgrade an existing atlas installation

  1. Back up the database and the current trax_map_tiles media directory.
  2. Stop web/worker processes while applying the upgrade. Keep the original media volume and the new private volume mounted in the migration process.
  3. Run nautobot-server migrate. Migration 0011_private_map_archives copies and verifies legacy archives, including orphaned files, before removing the public copies. It preserves storage names so an interrupted migration can be retried.
  4. If a referenced file is unavailable, restore its media mount or backup before continuing. A conflicting private copy stops migration and retains the source; investigate rather than deleting data to force the upgrade through.
  5. Start the services and verify an authorized atlas download. The old media URL should return 404 and a user without atlas permission must not download it.

The reverse migration does not put files back in public media storage. A code rollback needs a deliberate recovery plan with the protected backups.

Demo operator permissions

The operator/operator account is for a disposable demo. Normal migration does not create it. The supplied development configuration explicitly enables it with enable_demo_user: True; use that setting only in an isolated demo environment. The demo operator can view/filter the Operational Map and manage Map Tile Sets.

For an existing demo, refresh the operator's scoped permissions explicitly:

nautobot-server setup_operator_user

This includes the new atlas permissions. Without --reset, an existing account's password is preserved. Normal installations should provision their own users with the required Mission Plan, Operation, and Map Tile Set permissions. Turning enable_demo_user off does not remove a previously created account.

Track operations

Mission Plan names remain visible beside their markers. Click a marker to see its kit, status, MGRS, location, and a link to the Mission Plan.

Use Operations above the map to choose one or more operations, then select Apply. The map loads permitted missions belonging to any selected operation. A mission shared by several selected operations appears once. The shown mission count and initial viewport follow the filtered results. An operation with no mapped missions displays an empty-state message.

Leave the selector blank, or select Show all, to include all permitted mapped missions, including those not assigned to an operation. The filter is stored in the page URL, so a filtered view can be bookmarked. Operation and mission permissions are checked separately; selecting an operation never grants access to its restricted missions.

Associate basemaps with operations

On an Operation's create/edit form, select Map Tile Sets covering its AOR and, optionally, a Preferred Map Tile Set. These fields are also writable through the Operation API as map_tile_sets and preferred_map_tile_set. A preferred map is associated implicitly; it need not also appear in the multiple-selection field. The AOR text remains a description, not a geographic boundary.

After applying the Operations filter, available preferred maps appear first, followed by other associated maps and then other permitted, available basemaps. The first map is selected initially; the selector retains the alternatives. When multiple operations have preferred maps, name and UUID determine a stable order, independent of the order of the selected operations. Without an operation filter, maps retain their name order. Existing operations need no associations to work.

If none of the selected operations' associated maps is available to the user, TRAX uses other permitted, available maps and explains the fallback. An operation association never grants atlas access. Inactive maps are not offered, and invalid or inaccessible operation selections do not fall back to all maps or missions. Mission markers remain plotted outside a basemap's recorded bounds; a notice counts those outside its coverage. Bounds do not guarantee that every interior tile is present in a sparse archive.

Build a basemap in MOBAC

Mobile Atlas Creator (MOBAC) is a separate, GPL-licensed desktop application that downloads raster map tiles into a package TRAX can read. It is not bundled with TRAX and must be installed and run independently by whoever prepares basemaps.

Install and launch MOBAC

  1. Download the latest MOBAC release from the SourceForge files page and unzip it to any writable folder. On Windows, avoid installing under Program Files.
  2. Install a Java SE Runtime Environment 17 or later; MOBAC does not run on Java 8 or 11. On macOS, brew install openjdk installs a current JRE. On Linux, use the distribution's package manager. On Windows, install a Temurin or Oracle JRE.
  3. Launch MOBAC:
    • Windows: double-click Mobile Atlas Creator.exe.
    • Linux/macOS: run java -jar Mobile_Atlas_Creator.jar from the extracted folder. The bundled start.sh wraps the same command but needs its executable bit set first (chmod u+x start.sh), and macOS Gatekeeper may still block an unsigned script pulled from a downloaded archive. Running the java -jar command directly avoids both issues.
  4. On first launch MOBAC creates its settings, map source list, and tile cache next to the jar (or under ~/.mobac / %APPDATA%\Mobile Atlas Creator if that location isn't writable). No separate initialization step is required.

Create an atlas

  1. Open Atlas → New Atlas and give it a name. For desired format, select MBTiles SQLite.
  2. Pick a map source from the source tree (an OSM or satellite source already bundled with MOBAC, or a custom map source you've registered).
  3. Drag a selection rectangle over the area of operations. Only imagery inside this rectangle, at the zoom levels selected next, is included in the exported package.
  4. Select zoom levels for the selection. For tracking teams over large areas, start with zoom levels 0 through 8. Include levels 9–10 if nearby teams are difficult to distinguish. Street-level imagery is not required for team positions to be plotted at their stored coordinates.
  5. Click Add selection to add this area/zoom combination to the Atlas Content list. Repeat for additional areas or zoom ranges before creating the atlas.
  6. Click Create Atlas, choose MBTiles as the output format, and export raster tiles as PNG, JPEG, or WebP. Vector MBTiles cannot be displayed by this map.
  7. MOBAC writes the package to the atlases folder beside the jar, as <atlas name>/<atlas name>.mbtiles. Upload this file to TRAX.

Upload to TRAX

  1. Upload the package under Map Tile Sets and activate it.
  2. Open Operational Map. When several packages are active, use the basemap selector to switch.

Levels 0–3 provide world and continental context, 4–6 cover countries and large regions, and 7–8 provide a closer regional overview. The exact area visible depends on the viewport and latitude. See the zoom scale reference. The MOBAC area selection must cover the full operating area: selecting zooms 0–8 does not provide level-8 imagery outside the exported area.

TRAX detects each uploaded package's actual zoom levels and adapts when the package is replaced or another basemap is selected. It supports raster zooms 0–22, including zoom-0-only packages, other ranges such as 3–5 or 6–12, and nonconsecutive levels such as 0, 3, and 8. Continuous ranges give the clearest imagery at each scale. For a missing intermediate level, the map scales the closest available coarser tiles instead of showing gaps or loading large numbers of finer tiles. Two extra display zoom levels above the native maximum help separate markers; they stretch existing imagery without adding detail.

Include low zoom levels even when most operations use the detailed levels. A package containing only zoom 12 has no regional overview tiles. Drawing a zoom 8 overview from zoom 12 detail would require up to 256 detail tiles for each overview tile. The map therefore limits zooming out to the package's lowest available level. It permits two extra levels of zooming in by stretching existing tiles; this adds no detail.

For an existing detail-only archive, overview tiles can also be generated offline from its current imagery. Run this in a Python environment with Pillow installed (such as the Nautobot container):

python tools/build_mbtiles_overviews.py input.mbtiles output_overviews.mbtiles --min-zoom 6

The command creates a new file, preserves the native tiles, and adds lower zoom levels down to 6. Upload the resulting file to the existing Map Tile Set to refresh its metadata and enable zooming out. These overviews shrink the existing imagery; exporting native lower zoom levels in MOBAC gives labels and symbols designed for each scale.

See the OpenLayers XYZ source options for native zoom scaling behavior.

Loading behavior

The map initially centers on missions inside the selected basemap's coverage, limits requests to the package bounds, and waits for panning or zoom animations to finish before requesting new tiles. Mission markers use a shared canvas renderer. An atlas with no missions initially centers on its own bounds, as does an atlas with no missions inside its coverage. Switching basemaps also updates the viewport to the selected package's coverage. Missions outside that coverage remain plotted but do not shift the initial view away from available imagery.

Wheel and trackpad gestures zoom continuously around the pointer. Existing tiles scale during the gesture, and TRAX requests the next native tile grid after the gesture settles. Fractional display zoom does not create new zoom levels in the archive or fetch tiles for every animation frame. The +/− buttons and keyboard zoom controls retain their one-level steps. Dragging, another zoom control, or changing basemaps interrupts an active wheel gesture.

Tile bytes are cached on the server for a day; missing-tile results for ten minutes. Successful responses require private browser revalidation and support ETags. Permission is checked before a conditional response; a new request after permission revocation is denied. The atlas's last_updated value versions tile URLs and server cache keys. Replace a package through the Map Tile Set form or API so its version updates; replacing a file directly on disk bypasses that invalidation.

Archive availability is checked before using cached bytes or returning an ETag response, and a tile must exist before TRAX returns 304 Not Modified. Missing, unreadable, or invalid archives and tile-query failures return 503 Service Unavailable with Cache-Control: private, no-store and Retry-After: 30. An absent tile in an available archive, an unsupported zoom, or invalid tile coordinates still returns 404. The map reports imagery loading failures without automatically retrying every failed tile.

Debug Toolbar profiling is disabled for tile requests in the development configuration. Production should use the normal Nautobot production server with DEBUG=False.

Archive validation accepts MBTiles tables or views within configured SQLite query and resource limits, checks available zooms and raster format, and restores the upload's file position. PNG, JPEG, and WebP metadata names and MIME type aliases are accepted. When bounds are omitted or invalid, coverage is derived from the most detailed tiles; a regional package's low-zoom world tiles do not expand that coverage. These packages must use the standard MBTiles Web Mercator/TMS coordinate scheme. Vector PBF packages require a separate renderer and are rejected with an explanation.

Existing packages are not recopied for name or activation edits. Replacing a package refreshes its zoom levels, bounds, and cache version. Older imports retain their recorded zoom range until replaced. Tile serving currently requires local filesystem storage for the MBTiles file.

See the MBTiles specification for supported archive interfaces and coordinates.

Storage cleanup and limits

Successful replacement and deletion remove unreferenced archive files only after the database transaction commits. Shared files remain until the last reference is removed. Failed/rolled-back uploads or filesystem failures can leave private orphans; preview their cleanup with:

nautobot-server cleanup_map_archives

The preview changes nothing. After reviewing your storage/backup requirements, nautobot-server cleanup_map_archives --apply removes only unreferenced regular files at least 24 hours old. Recent, referenced, and symlink files are excluded. Keep this age guard long enough to avoid interfering with active uploads or recovery. Protect retained backups independently of live atlas retention.

The defaults allow 5 GiB per upload, 30 seconds of SQLite validation work, and 2 seconds per tile query. Query budgets must be positive and at most 300 seconds. Metadata is limited to 128 text entries, 16,384 characters per value, and 255 characters of attribution. Tile BLOBs are limited to 16 MiB. Missing/corrupt files or queries that exceed their limits produce controlled tile failures with server-side logging. These limits complement filesystem quotas and cache capacity planning.