Welcome. This guide adds offline maps to your xTAK node. When you're done, your ATAK / WinTAK devices will have detailed street basemaps in the field — no cell service and no internet required. The maps live on the Pi and are served to every connected TAK device over your local network.
mbtileserver is one small, self-contained program: nothing to download at install time, no dependencies, works fully offline. You install it once, then drop in the map region(s) you want.
New to Linux / the Raspberry Pi? Follow the steps exactly in order. Every command is complete — copy and paste each line as-is. The only things you change are the values in
<angle brackets>(your Pi's address, your login, the map file names you downloaded).
scp and ssh).Download up front from the xTAK download page at activate.xtak.ai, onto your computer (files land in Downloads):
mbtileserver-*-linux-arm64.tar.gz — the map server (this install).west-colorful-z15.mbtiles. Download only
the region(s) you operate in. (Maps are distributed separately from the
software; see Add your maps below.)You only need internet to download these to your computer — everything you run on the Pi is fully offline.
Copy the file into the Pi's home folder.
SCP, Host name =
your Pi's IP, User name / Password = your Pi login → Login. Drag
mbtileserver-*-linux-arm64.tar.gz from Downloads (left) into the Pi's
home folder (right). scp ~/Downloads/mbtileserver-*-linux-arm64.tar.gz <user>@<pi-ip>:~/Open a command session on the Pi:
- Windows: open PuTTY and log in, or in PowerShell run
ssh <user>@<pi-ip>.
- macOS / Linux: ssh <user>@<pi-ip>.
Then unpack the bundle:
cd ~
tar xzf mbtileserver-*-linux-arm64.tar.gz
cd mbtileserver-*-linux-arm64
(Optional integrity check — compare against the SHA256 shown on the download
page: sha256sum mbtileserver-*-linux-arm64.tar.gz.)
On the Pi:
sudo ./install.sh
The installer — with no internet — copies the program to /opt/mbtileserver,
starts the mbtileserver service on port 8000, and (if you have adminTAK)
refreshes the panel so the map server appears there. It creates an empty
/opt/mbtileserver/tiles/ folder — that's where your maps go next.
systemctl is-active mbtileserver # should print: active
curl -s http://127.0.0.1:8000/services
The curl prints [] (an empty list) until you add a map — that's expected.
✅ The map server is live. Now give it maps.
Maps are single .mbtiles files, one per region. You just drop them in — the
server picks them up automatically, no restart needed.
west-colorful-z15.mbtiles into the Pi's home folder.scp ~/Downloads/west-colorful-z15.mbtiles <user>@<pi-ip>:~/sudo mv ~/*.mbtiles /opt/mbtileserver/tiles/
The server auto-detects the new file within a second. Confirm it's listed:
curl -s http://127.0.0.1:8000/services
You'll see an entry for each map, with its id (the file name without
.mbtiles) and image type. Add as many regions as your storage holds — the
server hosts them all at once.
Each map is served at this address pattern (replace <pi-ip> and <map-id>):
http://<pi-ip>:8000/services/<map-id>/tiles/{$z}/{$x}/{$y}.<ext>
<ext> is the map's image type (png, jpg, or webp). A quick way to see the
exact URL and preview a map in a browser is:
http://<pi-ip>:8000/services/<map-id>/map.
Add it in ATAK either way:
.xml map-source file was provided
with your maps, copy it to the device's atak/imports folder (or use ATAK's
Import Manager). It sets the name, tile type, and zoom for you.Switch the active basemap in ATAK's map manager. If you loaded both a day (bright) and a night (dark) style, toggle between them there.
Tip: if you re-download an updated map with the same name, ATAK may still show its cached tiles. Clear that map source's cache in ATAK (or remove and re-add it) to see the new version.
If your Pi runs adminTAK, the map server shows up there as mbtileserver with Start / Restart / Stop / Enable / Disable controls and a live service indicator — handy for turning maps off at boot on a Pi where you don't always need them. No configuration is required; it works the same from the command line.
systemctl is-active mbtileserver prints active.http://<pi-ip>:8000/services lists each map you installed.http://<pi-ip>:8000/services/<map-id>/map draws the map.| Action | How |
|---|---|
| Update the server | Copy the newer mbtileserver-<ver>-linux-arm64.tar.gz over, unpack, sudo ./install.sh again. Your maps in tiles/ are untouched. |
| Add / replace a map | Drop the new .mbtiles into /opt/mbtileserver/tiles/ (replace the old file of the same name). Auto-served. |
| Remove a map | sudo rm /opt/mbtileserver/tiles/<name>.mbtiles |
| Uninstall the server | sudo systemctl disable --now mbtileserver && sudo rm /etc/systemd/system/mbtileserver.service && sudo systemctl daemon-reload && sudo rm -rf /opt/mbtileserver |
If you have adminTAK and the map server doesn't appear after installing, refresh the panel once:
sudo systemctl restart adminTAK.
| Symptom | Fix |
|---|---|
systemctl is-active mbtileserver isn't active |
See the log: sudo journalctl -u mbtileserver -e. Most often a maps-folder permission issue — sudo chown -R root:root /opt/mbtileserver. |
/services stays empty after adding a map |
Confirm the file is in /opt/mbtileserver/tiles/ and ends in .mbtiles. Check the log as above. |
| Map is blank / gray in ATAK past a certain zoom | You've zoomed past the map's native max. Set the source's max zoom to the native max so ATAK overzooms instead of blanking. |
| Map looks mis-tiled or "zoomed in wrong" | The device may not handle the tile size — contact your xTAK support with the map name; a matching build can be provided. |
| ATAK shows an old version after a map update | Clear that map source's cache in ATAK, or remove + re-add the source. |
| Won't start on a Pi Zero 2 W | Confirm the OS is 64-bit Raspberry Pi OS (getconf LONG_BIT prints 64). The program is 64-bit ARM; 32-bit Pi OS is not supported. |
Live server log, any time: sudo journalctl -u mbtileserver -f
mbtileserver — offline maps for ATAK/WinTAK. A product of xTAK — www.xtak.ai. Map server: consbio/mbtileserver (ISC). Map data © OpenStreetMap contributors (ODbL).