diff --git a/README-Docker.md b/README-Docker.md new file mode 100644 index 0000000..d87d368 --- /dev/null +++ b/README-Docker.md @@ -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 diff --git a/README.md b/README.md index 5655499..5ef4d9f 100644 --- a/README.md +++ b/README.md @@ -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: diff --git a/docker/README.md b/docker/README.md index d5531a5..e249712 100644 --- a/docker/README.md +++ b/docker/README.md @@ -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://: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`