diff --git a/DOCKER.md b/DOCKER.md index 2c3a1b4..91c7163 100644 --- a/DOCKER.md +++ b/DOCKER.md @@ -1,103 +1,85 @@ -# PotatoMesh Docker Setup +# PotatoMesh Docker Guide -## Quick Start +PotatoMesh publishes ready-to-run container images to the GitHub Packages container +registry (GHCR). You do not need to clone the repository to deploy them—Compose +will pull the latest release images for you. -```bash -./configure.sh -docker-compose up -d -docker-compose logs -f +## Prerequisites + +- Docker Engine 24+ or Docker Desktop with the Compose plugin +- Access to `/dev/ttyACM*` (or equivalent) if you plan to attach a Meshtastic + device to the ingestor container +- An API token that authorises the ingestor to post to your PotatoMesh instance + +## Images on GHCR + +| Service | Image | +|----------|-------------------------------------------------------------------| +| Web UI | `ghcr.io/l5yth/potato-mesh-web-linux-amd64:latest` | +| Ingestor | `ghcr.io/l5yth/potato-mesh-ingestor-linux-amd64:latest` | + +Images are published for every tagged release. Replace `latest` with a +specific version tag if you prefer pinned deployments. + +## Configure environment + +Create a `.env` file alongside your Compose file and populate the variables you +need. At a minimum you must set `API_TOKEN` so the ingestor can authenticate +against the web API. + +```env +API_TOKEN=replace-with-a-strong-token +SITE_NAME=My Meshtastic Network +MESH_SERIAL=/dev/ttyACM0 ``` -The default configuration attaches both services to the host network. This -avoids creating Docker bridge interfaces on platforms where that operation is -blocked. Access the dashboard at `http://127.0.0.1:41447` as soon as the -containers are running. On Docker Desktop (macOS/Windows) or when you prefer -traditional bridged networking, start Compose with the `bridge` profile: +Additional environment variables are optional: + +- `DEFAULT_CHANNEL`, `DEFAULT_FREQUENCY`, `MAP_CENTER_LAT`, `MAP_CENTER_LON`, + `MAX_NODE_DISTANCE_KM`, and `MATRIX_ROOM` customise the UI. +- `POTATOMESH_INSTANCE` (defaults to `http://web:41447`) lets the ingestor post + to a remote PotatoMesh instance if you do not run both services together. +- `MESH_CHANNEL_INDEX`, `MESH_SNAPSHOT_SECS`, and `DEBUG` adjust ingestor + behaviour. + +## Docker Compose file + +Use the `docker-compose.yml` file provided in the repository (or download the +[raw file from GitHub](https://raw.githubusercontent.com/l5yth/potato-mesh/main/docker-compose.yml)). +It already references the published GHCR images, defines persistent volumes for +data and logs, and includes optional bridge-profile services for environments +that require classic port mapping. Place this file in the same directory as +your `.env` file so Compose can pick up both. + +## Start the stack + +From the directory containing the Compose file: ```bash -COMPOSE_PROFILES=bridge docker-compose up -d +docker compose up -d ``` -Access at `http://localhost:41447` - -## Configuration - -Edit `.env` file or run `./configure.sh` to set: - -- `API_TOKEN` - Required for ingestor authentication -- `MESH_SERIAL` - Your Meshtastic device path (e.g., `/dev/ttyACM0`) -- `SITE_NAME` - Your mesh network name -- `MAP_CENTER_LAT/LON` - Map center coordinates - -## Device Setup - -**Find your device:** +Docker automatically pulls the GHCR images when they are not present locally. +The dashboard becomes available at `http://127.0.0.1:41447`. Use the bridge +profile when you need to map the port explicitly: ```bash -# Linux -ls /dev/ttyACM* /dev/ttyUSB* - -# macOS -ls /dev/cu.usbserial-* - -# Windows -ls /dev/ttyS* +COMPOSE_PROFILES=bridge docker compose up -d ``` -**Set permissions (Linux/macOS):** +## Updating ```bash -sudo chmod 666 /dev/ttyACM0 -# Or add user to dialout group -sudo usermod -a -G dialout $USER -``` - -## Common Commands - -```bash -# Start services -docker-compose up -d - -# View logs -docker-compose logs -f - -# Stop services -docker-compose down - -# Stop and remove data -docker-compose down -v - -# Update images -docker-compose pull && docker-compose up -d +docker compose pull +docker compose up -d ``` ## Troubleshooting -**Device access issues:** +- **Serial device permissions (Linux/macOS):** grant access with `sudo chmod 666 + /dev/ttyACM0` or add your user to the `dialout` group. +- **Port already in use:** identify the conflicting service with `sudo lsof -i + :41447`. +- **Viewing logs:** `docker compose logs -f` tails output from both services. -```bash -# Check device exists and permissions -ls -la /dev/ttyACM0 - -# Fix permissions -sudo chmod 666 /dev/ttyACM0 -``` - -**Port conflicts:** - -```bash -# Find what's using port 41447 -sudo lsof -i :41447 -``` - -**Container issues:** - -```bash -# Check logs -docker-compose logs - -# Restart services -docker-compose restart -``` - -For more Docker help, see [Docker Compose documentation](https://docs.docker.com/compose/). +For general Docker support, consult the [Docker Compose documentation](https://docs.docker.com/compose/). diff --git a/README.md b/README.md index 3f561f2..ac34a1f 100644 --- a/README.md +++ b/README.md @@ -18,24 +18,6 @@ Live demo for Berlin #MediumFast: [potatomesh.net](https://potatomesh.net) ![screenshot of the third version](./scrot-0.3.png) -## Quick Start with Docker - -```bash -./configure.sh # Configure your setup -docker-compose up -d # Start services -docker-compose logs -f # View logs -``` - -PotatoMesh uses host networking by default so it can run on restricted -systems where Docker cannot create bridged interfaces. The web UI listens on -`http://127.0.0.1:41447` immediately without explicit port mappings. If you -are using Docker Desktop (macOS/Windows) or otherwise require bridged -networking, enable the Compose profile with: - -```bash -COMPOSE_PROFILES=bridge docker-compose up -d -``` - ## Web App Requires Ruby for the Sinatra web app and SQLite3 for the app's database. @@ -142,6 +124,10 @@ address (for example `192.168.1.20:4403`) to use the Meshtastic TCP interface. * * +## Docker + +Looking for container deployment instructions? See the [Docker guide](DOCKER.md). + ## License Apache v2.0, Contact