meshview/README-Docker.md

Running MeshView with Docker

MeshView container images are built automatically and published to GitHub Container Registry.

Quick Start

Pull and run the latest image:

docker pull ghcr.io/pablorevilla-meshtastic/meshview:latest

docker run -d \
  --name meshview \
  -p 8081:8081 \
  -v ./config:/etc/meshview \
  -v ./data:/var/lib/meshview \
  -v ./logs:/var/log/meshview \
  ghcr.io/pablorevilla-meshtastic/meshview:latest

Access the web interface at: http://localhost:8081

Volume Mounts

The container uses three volumes for persistent data:

Volume	Purpose	Required
/etc/meshview	Configuration files	Yes
/var/lib/meshview	Database storage	Recommended
/var/log/meshview	Log files	Optional

Configuration Volume

Mount a directory containing your config.ini file:

-v /path/to/your/config:/etc/meshview

If no config is provided, the container will use the default sample.config.ini.

Database Volume

Mount a directory to persist the SQLite database:

-v /path/to/your/data:/var/lib/meshview

Important: Without this mount, your database will be lost when the container stops.

Logs Volume

Mount a directory to access logs from the host:

-v /path/to/your/logs:/var/log/meshview

Complete Example

Create a directory structure and run:

# Create directories
mkdir -p meshview/{config,data,logs,backups}

# Copy sample config (first time only)
docker run --rm ghcr.io/pablorevilla-meshtastic/meshview:latest \
  cat /etc/meshview/config.ini > meshview/config/config.ini

# Edit config.ini with your MQTT settings
nano meshview/config/config.ini

# Run the container
docker run -d \
  --name meshview \
  --restart unless-stopped \
  -p 8081:8081 \
  -v $(pwd)/meshview/config:/etc/meshview \
  -v $(pwd)/meshview/data:/var/lib/meshview \
  -v $(pwd)/meshview/logs:/var/log/meshview \
  ghcr.io/pablorevilla-meshtastic/meshview:latest

Docker Compose

Create a docker-compose.yml:

version: '3.8'

services:
  meshview:
    image: ghcr.io/pablorevilla-meshtastic/meshview:latest
    container_name: meshview
    restart: unless-stopped
    ports:
      - "8081:8081"
    volumes:
      - ./config:/etc/meshview
      - ./data:/var/lib/meshview
      - ./logs:/var/log/meshview
      - ./backups:/var/lib/meshview/backups  # For database backups
    environment:
      - TZ=America/Los_Angeles  # Set your timezone

Run with:

docker-compose up -d

Configuration

Minimum Configuration

Edit your config.ini to configure MQTT connection:

[mqtt]
server = mqtt.meshtastic.org
topics = ["msh/US/#"]
port = 1883
username =
password =

[database]
# SQLAlchemy async connection string.
# Examples:
#   sqlite+aiosqlite:///var/lib/meshview/packets.db
#   postgresql+asyncpg://user:pass@host:5432/meshview
connection_string = sqlite+aiosqlite:////var/lib/meshview/packets.db

Database Backups

To enable automatic daily backups inside the container:

[cleanup]
backup_enabled = True
backup_dir = /var/lib/meshview/backups
backup_hour = 2
backup_minute = 00

Then mount the backups directory:

-v $(pwd)/meshview/backups:/var/lib/meshview/backups

Available Tags

Tag	Description
latest	Latest build from the main branch
dev-v3	Development branch
v1.2.3	Specific version tags

Updating

Pull the latest image and restart:

docker pull ghcr.io/pablorevilla-meshtastic/meshview:latest
docker restart meshview

Or with docker-compose:

docker-compose pull
docker-compose up -d

Logs

View container logs:

docker logs meshview

# Follow logs
docker logs -f meshview

# Last 100 lines
docker logs --tail 100 meshview

Troubleshooting

Container won't start

Check logs:

docker logs meshview

Database permission issues

Ensure the data directory is writable:

chmod -R 755 meshview/data

Can't connect to MQTT

1. Check your MQTT configuration in config.ini
2. Verify network connectivity from the container:

   docker exec meshview ping mqtt.meshtastic.org
   

Port already in use

Change the host port (left side):

-p 8082:8081

Then access at: http://localhost:8082

Building Your Own Image

If you want to build from source:

git clone https://github.com/pablorevilla-meshtastic/meshview.git
cd meshview
docker build -f Containerfile -t meshview:local .

Security Notes

• The container runs as a non-root user (app, UID 10001)
• No privileged access required
• Only port 8081 is exposed
• All data stored in mounted volumes

Support

• GitHub Issues: https://github.com/pablorevilla-meshtastic/meshview/issues
• Documentation: https://github.com/pablorevilla-meshtastic/meshview