meshcore-packet-capture/DOCKER.md

Docker Deployment Guide

Prerequisites

• Docker and Docker Compose installed
• Linux host system (recommended for BLE and serial support)

Quick Start

1. Download configuration files:

   # Download docker-compose.yml and .env.local.example
   curl -O https://raw.githubusercontent.com/agessaman/meshcore-packet-capture/main/docker-compose.yml
   curl -O https://raw.githubusercontent.com/agessaman/meshcore-packet-capture/main/.env.local.example
   

2. Configure:

   # Copy example configuration
   cp .env.local.example .env.local
   # Edit .env.local with your settings (IATA code, MQTT broker, etc.)
   

3. Start the container:

   docker compose up -d
   

4. View logs:

   docker compose logs -f meshcore-capture
   

Connection Types

Serial Connection (Default)

The default configuration uses serial connection with privileged: false for improved security.

1. Find your device:

   sudo ls -la /dev/serial/by-id/
   

2. Mount device in docker-compose.yml:

   devices:
     - /dev/serial/by-id/usb-Heltec_HT-n5262_3D3B4D4A4D776001-if00:/dev/ttyUSB0
   

3. Configure serial port (if not using /dev/ttyUSB0):

   environment:
     - PACKETCAPTURE_SERIAL_PORTS=/dev/ttyUSB0
   

The container path defaults to /dev/ttyUSB0, so no additional configuration is needed if using the standard path.

BLE Connection

1. Enable privileged mode in docker-compose.yml:

   privileged: true
   

2. Set connection type:

   environment:
     - PACKETCAPTURE_CONNECTION_TYPE=ble
   

3. Optionally specify BLE device:

   environment:
     - PACKETCAPTURE_BLE_ADDRESS=AA:BB:CC:DD:EE:FF
     # or
     - PACKETCAPTURE_BLE_DEVICE_NAME=MeshCore Device
   

4. Enable host networking (may be required for BLE discovery):

   network_mode: host
   

Configuration

Configuration is provided via:

1. Environment variables in docker-compose.yml
2. .env.local file mounted as a volume (recommended)

The .env.local file supports all configuration options. See .env.local.example for available settings.

Required Settings

• PACKETCAPTURE_IATA: 3-letter airport code (e.g., SEA, LAX)
• PACKETCAPTURE_MQTT1_SERVER: MQTT broker address
• PACKETCAPTURE_MQTT1_PORT: MQTT broker port

MQTT Authentication

Username/Password:

PACKETCAPTURE_MQTT1_USERNAME=your_username
PACKETCAPTURE_MQTT1_PASSWORD=your_password

Auth Token (JWT):

PACKETCAPTURE_MQTT1_USE_AUTH_TOKEN=true
PACKETCAPTURE_MQTT1_TOKEN_AUDIENCE=mqtt.example.com
PACKETCAPTURE_PRIVATE_KEY=your_private_key_hex

Container Management

Start:

docker compose up -d

Stop:

docker compose down

Restart:

docker compose restart meshcore-capture

View logs:

docker compose logs -f meshcore-capture

View status:

docker compose ps

Execute commands in container:

docker compose exec meshcore-capture /bin/bash

Data Storage

Packet data is stored in the ./data directory, which is mounted as a volume. Data persists across container restarts.

Separate Logs Directory

To store logs separately from packet data, uncomment the logs volume mount in docker-compose.yml:

volumes:
  - ./logs:/app/logs

Create the logs directory before starting:

mkdir -p logs

Container logs are also available via Docker:

docker compose logs -f meshcore-capture > logs/container.log

Troubleshooting

Serial Device Not Found

Check device exists:

ls -la /dev/serial/by-id/

Check device permissions:

sudo chmod 666 /dev/ttyUSB0
# Or add user to dialout group
sudo usermod -a -G dialout $USER
# Then log out and back in

Verify device mount:

docker compose exec meshcore-capture ls -la /dev/ttyUSB0

BLE Connection Issues

Enable host networking:

network_mode: host

Check Bluetooth adapter:

docker compose exec meshcore-capture hciconfig

Verify privileged mode:

docker compose exec meshcore-capture cat /proc/self/status | grep CapEff

MQTT Connection Issues

Test network connectivity:

docker compose exec meshcore-capture ping mqtt-broker

Check MQTT configuration:

docker compose exec meshcore-capture env | grep MQTT

View connection logs:

docker compose logs meshcore-capture | grep -i mqtt

Container Won't Start

Check logs:

docker compose logs meshcore-capture

Verify configuration:

docker compose config

Check image:

docker pull ghcr.io/agessaman/meshcore-packet-capture:latest

Building from Source

To build the image locally instead of using the pre-built image:

1. Comment out image line in docker-compose.yml:

   # image: ghcr.io/agessaman/meshcore-packet-capture:latest
   

2. Uncomment build line:

   build: .
   

3. Build and start:

   docker compose up -d --build
   

Platform Notes

• Linux: Full support for both BLE and serial connections
• macOS: Serial connections work; BLE may require host networking
• Windows: Serial connections work with proper device mounting; BLE support is limited