Docker Docs

2026-03-04 23:27:46 +01:00 · 2025-11-04 21:04:20 -08:00
parent 4b9dfba03d
commit f903c82c79
3 changed files with 282 additions and 39 deletions
@@ -0,0 +1,243 @@
+# Running MeshView with Docker
+
+MeshView container images are built automatically and published to GitHub Container Registry.
+
+## Quick Start
+
+Pull and run the latest image:
+
+```bash
+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:
+
+```bash
+-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:
+
+```bash
+-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:
+
+```bash
+-v /path/to/your/logs:/var/log/meshview
+```
+
+## Complete Example
+
+Create a directory structure and run:
+
+```bash
+# 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`:
+
+```yaml
+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:
+
+```bash
+docker-compose up -d
+```
+
+## Configuration
+
+### Minimum Configuration
+
+Edit your `config.ini` to configure MQTT connection:
+
+```ini
+[mqtt]
+server = mqtt.meshtastic.org
+topics = ["msh/US/#"]
+port = 1883
+username =
+password =
+
+[database]
+connection_string = sqlite+aiosqlite:///var/lib/meshview/packets.db
+```
+
+### Database Backups
+
+To enable automatic daily backups inside the container:
+
+```ini
+[cleanup]
+backup_enabled = True
+backup_dir = /var/lib/meshview/backups
+backup_hour = 2
+backup_minute = 00
+```
+
+Then mount the backups directory:
+
+```bash
+-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:
+
+```bash
+docker pull ghcr.io/pablorevilla-meshtastic/meshview:latest
+docker restart meshview
+```
+
+Or with docker-compose:
+
+```bash
+docker-compose pull
+docker-compose up -d
+```
+
+## Logs
+
+View container logs:
+
+```bash
+docker logs meshview
+
+# Follow logs
+docker logs -f meshview
+
+# Last 100 lines
+docker logs --tail 100 meshview
+```
+
+## Troubleshooting
+
+### Container won't start
+
+Check logs:
+```bash
+docker logs meshview
+```
+
+### Database permission issues
+
+Ensure the data directory is writable:
+```bash
+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:
+   ```bash
+   docker exec meshview ping mqtt.meshtastic.org
+   ```
+
+### Port already in use
+
+Change the host port (left side):
+```bash
+-p 8082:8081
+```
+
+Then access at: http://localhost:8082
+
+## Building Your Own Image
+
+If you want to build from source:
+
+```bash
+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
@@ -61,6 +61,14 @@ Samples of currently running instances:

 ## Installing

+### Using Docker (Recommended)
+
+The easiest way to run MeshView is using Docker. Pre-built images are available from GitHub Container Registry.
+
+See **[README-Docker.md](README-Docker.md)** for complete Docker installation and usage instructions.
+
+### Manual Installation
+
 Requires **`python3.11`** or above.

 Clone the repo from GitHub:
@@ -1,44 +1,36 @@
 # MeshView Docker Container

-This Dockerfile builds a containerized version of the [MeshView](https://github.com/pablorevilla-meshtastic/meshview) application. It uses a lightweight Python environment and sets up the required virtual environment as expected by the application.
+> **Note:** This directory contains legacy Docker build files.
+>
+> **For current Docker usage instructions, please see [README-Docker.md](../README-Docker.md) in the project root.**

-## Image Details
+## Current Approach

- **Base Image**: `python:3.12-slim`
- **Working Directory**: `/app`
- **Python Virtual Environment**: `/app/env`
+Pre-built container images are automatically built and published to GitHub Container Registry:
+
+```bash
+docker pull ghcr.io/pablorevilla-meshtastic/meshview:latest
+```
+
+See **[README-Docker.md](../README-Docker.md)** for:
+- Quick start instructions
+- Volume mount configuration
+- Docker Compose examples
+- Backup configuration
+- Troubleshooting
+
+## Legacy Build (Not Recommended)
+
+If you need to build your own image for development:
+
+```bash
+# From project root
+docker build -f Containerfile -t meshview:local .
+```
+
+The current Containerfile uses:
+- **Base Image**: `python:3.13-slim` (Debian-based)
+- **Build tool**: `uv` for fast dependency installation
+- **User**: Non-root user `app` (UID 10001)
 - **Exposed Port**: `8081`
-
-## Build Instructions
-
-Build the Docker image:
-
-```bash
-docker build -t meshview-docker .
-```
-
-## Run Instructions
-
-Run the container:
-
-```bash
-docker run -d --name meshview-docker -p 8081:8081 meshview-docker
-```
-
-This maps container port `8081` to your host. The application runs via:
-
-```bash
-/app/env/bin/python /app/mvrun.py
-```
-
-## Web Interface
-
-Once the container is running, you can access the MeshView web interface by visiting:
-
-http://localhost:8081
-
-If running on a remote server, replace `localhost` with the host's IP or domain name:
-
-http://<host>:8081
-
-Ensure that port `8081` is open and not blocked by a firewall or security group.
+- **Volumes**: `/etc/meshview`, `/var/lib/meshview`, `/var/log/meshview`