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.

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.

Build a basemap in MOBAC

  1. Select the area of operations and use MBTiles as the atlas output format.
  2. 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.
  3. Export raster tiles as PNG, JPEG, or WebP. Vector MBTiles cannot be displayed by this map.
  4. Upload the package under Map Tile Sets and activate it.
  5. 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 Leaflet grid layer 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.

Tile bytes and missing-tile results are cached on the server for a day. 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.

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.