Skip to content

TapMap

TapMap is a network connection visualizer daemon that plots active network connections on a 3D world map in real-time.

🛠 Installation

Default Port: 8050

Binary path: /opt/tapmap/tapmap

TapMap is built from source for both amd64 and arm64 via Docker + PyInstaller using our reprepro builder, and installed as a .deb package from our local reprepro repository.

apt update
apt install tapmap

⚙ Config

Configure the environment file by decrypting secrets and symlinking the .env using Stow.

task decrypt

task stow

homelab/lxc/tapmap/.env.tmpl

CONFIG_DIR=/etc/tapmap
INSTALL_DIR=/opt/tapmap
SERVICE_NAME=tapmap

# GitHub
GITHUB_TOKEN=

# Notifications
ENABLE_NOTIFICATIONS=false
MAILRISE_URL=
MAILRISE_FROM=
MAILRISE_RCPT=

TAPMAP_HOST=0.0.0.0
# You can add optional overrides here as well, for example:
# TAPMAP_PORT=8050
# TAPMAP_LAT=33.6012
# TAPMAP_LON=-117.6524

# MaxMind GeoLite2 (https://www.maxmind.com/en/my_license_key)
MAXMIND_ACCOUNT_ID=
MAXMIND_LICENSE_KEY=

🌐 GeoLite2 Database Setup

TapMap uses the MaxMind GeoLite2 databases to map IP addresses to physical coordinates.

task geolite2:setup

task geolite2:update

:gears: Systemd Service

/etc/systemd/system/tapmap.service

[Unit]
Description=TapMap Network Connection Visualizer Daemon
After=network.target

[Service]
Type=simple
User=root
WorkingDirectory=/opt/tapmap
EnvironmentFile=/opt/tapmap/.env
ExecStart=/opt/tapmap/tapmap

# Restart configuration if the daemon crashes
Restart=on-failure
RestartSec=5s

# Security hardening and resource constraints
CapabilityBoundingSet=CAP_NET_ADMIN CAP_NET_RAW
AmbientCapabilities=CAP_NET_ADMIN CAP_NET_RAW

[Install]
WantedBy=multi-user.target

Traefik

homelab/pve/traefik/conf.d/tapmap.yaml 
---
http:
 #region routers 
  routers:
    tapmap:
      entryPoints:
        - "websecure"
      rule: "Host(`tapmap.l.nicholaswilde.io`)"
      middlewares:
        - default-headers@file
        - https-redirectscheme@file
      tls: {}
      service: tapmap
#endregion
#region services
  services:
    tapmap:
      loadBalancer:
        servers:
          - url: "http://192.168.1.200:8050"
        passHostHeader: true
#endregion
  middlewares:
    https-redirectscheme:
      redirectScheme:
        scheme: https
        permanent: true
    default-headers:
      headers:
        frameDeny: true
        browserXssFilter: true
        contentTypeNosniff: true
        forceSTSHeader: true
        stsIncludeSubdomains: true
        stsPreload: true
        stsSeconds: 15552000
        customFrameOptionsValue: SAMEORIGIN
        customRequestHeaders:
          X-Forwarded-Proto: https

    default-whitelist:
      ipAllowList:
        sourceRange:
        - "10.0.0.0/8"
        - "192.168.0.0/16"
        - "172.16.0.0/12"

    secured:
      chain:
        middlewares:
        - default-whitelist
        - default-headers

🚀 Upgrade

To upgrade the application, you can pull the latest changes and run the update script, or use the webhook service.

task upgrade

./update.sh

Webhook Service

TapMap includes a webhook listener service to trigger updates automatically.

task wh:install

task wh:status

task wh:logs

task wh:test

Task List

task: Available tasks for this project:
* create-template:       Create template from existing .env file
* decrypt:               Decrypt sensitive configuration files using SOPS.
* default:               List all available tasks.
* enable:                Enable the application's systemd service.
* encrypt:               Encrypt sensitive configuration files using SOPS.
* export:                Export the task list to `task-list.txt`.
* init:                  Initialize the application's environment and configuration files.
* mklinks:               Create symbolic links for configuration files.
* restart:               Restart the application's systemd service.
* start:                 Start the application's systemd service.
* status:                Check the status of the application's systemd service.
* stop:                  Stop the application's systemd service.
* stow:                  Symlink .env from homelab repo to /opt/tapmap using stow.
* update:                Update the application or its running containers.
* upgrade:               Upgrade the application by pulling the latest changes and updating.
* verify-secrets:        Checks if the decrypted secret matches the local file
* geolite2:setup:        Configure GeoIP.conf with MaxMind credentials and install systemd override.
* geolite2:update:       Download/update GeoLite2 databases for TapMap using geoipupdate.
* wh:install:            Install and start the systemd webhook service
* wh:logs:               View the webhook service logs
* wh:status:             Check the status of the systemd webhook service
* wh:test:               Test the webhook listener locally

🔗 References