Skip to content

Docker

TapMap supports running in Docker on Linux hosts.

Docker support is intended for users who want to monitor network activity on a Linux system without installing TapMap directly on the host.

Docker Desktop on Windows and macOS is not supported.

Run from Docker Hub

The published Docker image supports:

  • AMD64 (x86_64)
  • ARM64

Create a local data directory:

mkdir -p ~/tapmap-data

Start TapMap:

docker run --rm \
  --network host \
  --pid host \
  -v ~/tapmap-data:/data \
  -e TAPMAP_IN_DOCKER=1 \
  olalie/tapmap:latest

The mounted host directory is used as the container data directory (/data).

If no supported GeoIP databases are found, GeoIP Database Management opens automatically and guides you through the installation process.

Open:

http://127.0.0.1:8050

Access from another machine

By default, TapMap listens on:

0.0.0.0

when running in Docker.

If the host machine has IP address:

192.168.1.50

TapMap can be accessed from another machine using:

http://192.168.1.50:8050

Environment variables

TapMap supports runtime configuration through environment variables.

A common example is changing the default port:

-e TAPMAP_PORT=8060

See Environment Variables for details.

MQTT

Desktop notifications are not available in Docker. MQTT can be used to receive notifications for new Significant Connections.

To configure MQTT, run the configuration wizard with the same data directory mounted to /data:

docker run --rm -it \
  --network host \
  -v ~/tapmap-data:/data \
  -e TAPMAP_IN_DOCKER=1 \
  olalie/tapmap:latest \
  tapmap --configure-mqtt

The MQTT configuration is stored in /data/mqtt.json and persists in the mounted host directory.

Unlike desktop installations, Docker stores MQTT credentials in mqtt.json. The file is created with permissions 0600.

The broker must be specified by IPv4 or IPv6 address. Hostnames, including localhost, are not supported.

See MQTT for MQTT configuration and notification behavior.

Process information

TapMap always shows network activity.

Process visibility in Docker depends on host security policies.

On Ubuntu with the default Docker AppArmor profile (docker-default), SYS_PTRACE alone was not sufficient.

In this setup, process names became available with:

--cap-add=SYS_PTRACE
--security-opt apparmor=unconfined

Behavior may vary across systems.

Updating the Docker image

Docker does not automatically download newer versions of an existing image.

To update:

docker pull olalie/tapmap:latest

or start the container with:

docker run --pull always ...

Building a Docker image from source

For advanced users, a Docker image can be built directly from the repository.

Build the image:

docker build -t tapmap .

Start using the provided Docker Compose configuration:

docker compose -f compose-linux.yml up

GeoIP databases

TapMap requires GeoIP databases to display locations on the map.

GeoIP databases are stored in the directory mounted to /data.

For example:

-v ~/tapmap-data:/data

stores the databases in:

~/tapmap-data

on the host system.

For installation, updates, manual installation, and provider selection, see GeoIP Database Management.

Troubleshooting

No map locations

Verify that supported GeoIP databases are installed and detected.

See GeoIP Database Management.

Cannot access TapMap from another machine

Verify:

  • The host machine is reachable on the network.
  • Port 8050 is not blocked by a firewall.
  • The correct host IP address is being used.