Merge pull request #56 from agessaman/dev

Version 0.8

Author: agessaman

.dockerignore

@@ -0,0 +1,76 @@
+# Git
+.git
+.gitignore
+.gitattributes
+
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+*.egg-info/
+dist/
+build/
+*.egg
+
+# Virtual environments
+venv/
+env/
+ENV/
+
+# IDE
+.vscode/
+.idea/
+*.swp
+*.swo
+*~
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Project specific
+*.db
+*.db-shm
+*.db-wal
+*.log
+logs/
+backups/
+*.ini
+config.ini
+config.ini.example
+config.ini.minimal-example
+config.min.ini
+
+# Documentation
+docs/
+*.md
+!README.md
+
+# Test files
+test_scripts/
+*.test.py
+*_test.py
+
+# Development
+dev/
+flake.lock
+flake.nix
+nix/
+
+# Service files
+*.service
+*.plist
+*.sh
+!install-service.sh
+!uninstall-service.sh
+
+# Website
+website/
+
+# MQTT bridge
+mctomqtt.py
+
+# Database backups
+backup_database.py

.env.example

@@ -0,0 +1,12 @@
+# Docker image configuration
+# This file is auto-generated by docker-setup.sh based on your current git branch
+# You can manually override these values if needed
+
+# Docker image registry (default: ghcr.io/agessaman/meshcore-bot)
+DOCKER_IMAGE_REGISTRY=ghcr.io/agessaman/meshcore-bot
+
+# Docker image tag (auto-detected from git branch)
+# - main/master branches -> latest
+# - dev branch -> dev
+# - other branches -> branch name (with / replaced by -)
+DOCKER_IMAGE_TAG=latest

.github/workflows/docker-build.yml

@@ -54,7 +54,7 @@ jobs:
             type=semver,pattern={{version}}
             type=semver,pattern={{major}}.{{minor}}
             type=semver,pattern={{major}}
-            type=sha,prefix={{branch}}-
+            type=sha,prefix=sha-
             type=raw,value=latest,enable=${{ github.ref == 'refs/heads/main' || github.ref == 'refs/heads/master' }}
 
       - name: Build and push Docker image

.github/workflows/docs.yml

@@ -0,0 +1,28 @@
+# Build and deploy Material for MkDocs to GitHub Pages
+name: Deploy docs
+
+on:
+  push:
+    branches:
+      - main
+  workflow_dispatch:
+
+permissions:
+  contents: write
+
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.x"
+
+      - name: Install MkDocs and Material
+        run: pip install mkdocs-material
+
+      - name: Deploy to GitHub Pages
+        run: mkdocs gh-deploy --force

.github/workflows/test.yml

@@ -0,0 +1,33 @@
+name: Tests
+
+on:
+  push:
+    branches:
+      - main
+      - master
+      - dev
+  pull_request:
+    branches:
+      - main
+      - master
+      - dev
+  workflow_dispatch:
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install -e ".[test]"
+
+      - name: Run tests
+        run: pytest tests/ -v --tb=short

.gitignore

@@ -129,15 +129,28 @@ mctomqtt.py
 bot_cli.py
 bot_start_time.txt
 
-# Test files and development artifacts
+# Test files and development artifacts (root level)
 test_*.py
 test_*.db
 test_*.log
 *_test.py
 *_test.db
+# Allow tests/ directory (pytest convention)
+!tests/
+!tests/**/*.py
 
 # Local documentation and development files
 docs/local/
-tests/
 test_scripts/
 dev/
+website/
+# pytest.ini committed for asyncio_mode and test discovery
+pymc-test/*
+config-pymc.ini
+*.key
+
+# Docker data directory (user-specific config, databases, logs)
+# Ignore contents but keep directory structure
+data/*
+!data/.gitkeep
+

Dockerfile

@@ -0,0 +1,62 @@
+# Multi-stage build for meshcore-bot
+FROM python:3.11-slim AS builder
+
+# Install build dependencies (with cache mount for apt)
+RUN --mount=type=cache,target=/var/cache/apt,sharing=locked \
+    --mount=type=cache,target=/var/lib/apt,sharing=locked \
+    apt-get update && apt-get install -y --no-install-recommends \
+    build-essential \
+    && rm -rf /var/lib/apt/lists/*
+
+# Set working directory
+WORKDIR /build
+
+# Copy dependency files
+COPY requirements.txt pyproject.toml ./
+
+# Install Python dependencies (with cache mount for pip)
+RUN --mount=type=cache,target=/root/.cache/pip \
+    pip install --user -r requirements.txt
+
+# Final stage
+FROM python:3.11-slim
+
+# Install runtime dependencies (with cache mount for apt)
+RUN --mount=type=cache,target=/var/cache/apt,sharing=locked \
+    --mount=type=cache,target=/var/lib/apt,sharing=locked \
+    apt-get update && apt-get install -y --no-install-recommends \
+    # For serial port access
+    udev \
+    # For BLE support (optional, but commonly needed)
+    libbluetooth3 \
+    # Cleanup
+    && rm -rf /var/lib/apt/lists/*
+
+# Create non-root user and add to dialout group for serial port access
+RUN useradd -m -u 1000 -G dialout,tty meshcore && \
+    mkdir -p /app /data/config /data/databases /data/logs /data/backups && \
+    chown -R meshcore:meshcore /app /data
+
+# Copy Python dependencies from builder
+COPY --from=builder /root/.local /home/meshcore/.local
+
+# Set working directory
+WORKDIR /app
+
+# Copy application files
+COPY --chown=meshcore:meshcore . /app/
+
+# Set PATH to include user's local bin
+ENV PATH=/home/meshcore/.local/bin:$PATH \
+    PYTHONUNBUFFERED=1 \
+    PYTHONDONTWRITEBYTECODE=1
+
+# Switch to non-root user
+USER meshcore
+
+# Health check: verify the main process (PID 1, the bot) is still running
+HEALTHCHECK --interval=30s --timeout=10s --start-period=40s --retries=3 \
+    CMD ["sh", "-c", "kill -0 1"]
+
+# Default command
+CMD ["python3", "meshcore_bot.py", "--config", "/data/config/config.ini"]

README.md

@@ -7,7 +7,7 @@ A Python bot that connects to MeshCore mesh networks via serial port, BLE, or TC
 - **Connection Methods**: Serial port, BLE (Bluetooth Low Energy), or TCP/IP
 - **Keyword Responses**: Configurable keyword-response pairs with template variables
 - **Command System**: Plugin-based command architecture with built-in commands
-- **Rate Limiting**: Configurable rate limiting to prevent network spam
+- **Rate Limiting**: Global, per-user (by pubkey or name), and bot transmission rate limits to prevent spam
 - **User Management**: Ban/unban users with persistent storage
 - **Scheduled Messages**: Send messages at configured times
 - **Direct Message Support**: Respond to private messages
@@ -84,6 +84,43 @@ sudo systemctl status meshcore-bot
 
 See [SERVICE-INSTALLATION.md](SERVICE-INSTALLATION.md) for detailed service installation instructions.
 
+### Docker Deployment
+For containerized deployment using Docker:
+
+1. **Create data directories and configuration**:
+   ```bash
+   mkdir -p data/{config,databases,logs,backups}
+   cp config.ini.example data/config/config.ini
+   # Edit data/config/config.ini with your settings
+   ```
+
+2. **Update paths in config.ini** to use `/data/` directories:
+   ```ini
+   [Bot]
+   db_path = /data/databases/meshcore_bot.db
+   
+   [Logging]
+   log_file = /data/logs/meshcore_bot.log
+   ```
+
+3. **Build and start with Docker Compose**:
+   ```bash
+   docker compose build
+   docker compose up -d
+   ```
+   
+   Or build and start in one command:
+   ```bash
+   docker compose up -d --build
+   ```
+
+4. **View logs**:
+   ```bash
+   docker-compose logs -f
+   ```
+
+See [DOCKER.md](docs/DOCKER.md) for detailed Docker deployment instructions, including serial port access, web viewer configuration, and troubleshooting.
+
 ## NixOS
 Use the Nix flake via flake.nix
 ```nix
@@ -127,7 +164,10 @@ timeout = 30                      # Connection timeout
 [Bot]
 bot_name = MeshCoreBot            # Bot identification name
 enabled = true                    # Enable/disable bot
-rate_limit_seconds = 2            # Rate limiting interval
+rate_limit_seconds = 2            # Global: min seconds between any bot reply
+bot_tx_rate_limit_seconds = 1.0   # Min seconds between bot transmissions
+per_user_rate_limit_seconds = 5   # Per-user: min seconds between replies to same user (pubkey or name)
+per_user_rate_limit_enabled = true
 startup_advert = flood            # Send advert on startup
 ```
 
@@ -145,6 +185,8 @@ help = "Bot Help: test, ping, help, hello, cmd, wx, aqi, sun, moon, solar, hfcon
 [Channels]
 monitor_channels = general,test,emergency  # Channels to monitor
 respond_to_dms = true                      # Enable DM responses
+# Optional: limit channel responses to certain keywords (DM gets all triggers)
+# channel_keywords = help,ping,test,hello
 ```
 
 ### External Data APIs
@@ -158,7 +200,7 @@ airnow_api_key =                  # Air quality data
 ### Alert Command
 ```ini
 [Alert_Command]
-alert_enabled = true                    # Enable/disable alert command
+enabled = true                           # Enable/disable alert command
 max_incident_age_hours = 24             # Maximum age for incidents (hours)
 max_distance_km = 20.0                  # Maximum distance for proximity queries (km)
 agency.city.<city_name> = <agency_ids>   # City-specific agency IDs (e.g., agency.city.seattle = 17D20,17M15)
@@ -183,7 +225,7 @@ python meshcore_bot.py
 
 ### Available Commands
 
-For a comprehensive list of all available commands with examples and detailed explanations, see [COMMANDS.md](COMMANDS.md).
+For a comprehensive list of all available commands with examples and detailed explanations, see [COMMANDS.md](docs/COMMANDS.md).
 
 Quick reference:
 - **Basic:** `test`, `ping`, `help`, `hello`, `cmd`
@@ -205,6 +247,25 @@ Keyword responses support these template variables:
 - `{timestamp}` - Message timestamp
 - `{path}` - Message routing path
 
+### Adding Newlines
+
+To add newlines in keyword responses, use `\n` (single backslash + n):
+
+```ini
+[Keywords]
+test = "Line 1\nLine 2\nLine 3"
+```
+
+This will output:
+```
+Line 1
+Line 2
+Line 3
+```
+
+To use a literal backslash + n, use `\\n` (double backslash + n).  
+Other escape sequences: `\t` (tab), `\r` (carriage return), `\\` (literal backslash)
+
 Example:
 ```ini
 [Keywords]
@@ -275,7 +336,9 @@ help = "Bot Help: test, ping, help, hello, cmd, wx, gwx, aqi, sun, moon, solar,
    - Check meshcore library documentation for protocol details
 
 5. **Rate Limiting**:
-   - Adjust `rate_limit_seconds` in config
+   - **Global**: `rate_limit_seconds` — minimum time between any two bot replies
+   - **Per-user**: `per_user_rate_limit_seconds` and `per_user_rate_limit_enabled` — minimum time between replies to the same user (user identified by public key when available, else sender name; channel senders often matched by name)
+   - **Bot TX**: `bot_tx_rate_limit_seconds` — minimum time between bot transmissions on the mesh
    - Check logs for rate limiting messages
 
 ### Debug Mode