From f8ef1ac2979887ed7104f3d6ac1c77bb2cc0b2ed Mon Sep 17 00:00:00 2001 From: MarekWo Date: Tue, 30 Dec 2025 15:31:26 +0100 Subject: [PATCH] docs: Move data storage to project directory and cleanup configuration MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Major documentation update with new data structure: Breaking Changes: - Data storage moved from host directories to ./data/ inside project - MC_CONFIG_DIR default changed: /root/.config/meshcore β†’ ./data/meshcore - MC_ARCHIVE_DIR default changed: /mnt/archive/meshcore β†’ ./data/archive - Requires migration for existing installations (see MIGRATION.md) Documentation: - Add MIGRATION.md - step-by-step guide for existing users - Add FRESH_INSTALL.md - complete installation guide for new users - Update README.md - new Configuration section with ./data/ structure - Update .env.example - placeholders instead of real values, new defaults - Update .claude/CLAUDE.md - updated environment variables documentation - Change serial device detection from 'ls -l' to 'ls' (cleaner output) Code Cleanup: - Remove deprecated MC_REFRESH_INTERVAL variable (unused since intelligent refresh) - Remove MC_REFRESH_INTERVAL from app/config.py - Remove refresh_interval from app/routes/views.py (5 functions) - Remove refresh_interval from app/routes/api.py - Remove refreshInterval from app/templates/index.html - Remove refreshInterval from app/templates/dm.html - Remove MC_REFRESH_INTERVAL from docker-compose.yml Configuration: - Update .gitignore - exclude data/ and docs/github-discussion-*.md - Serial port: use /dev/serial/by-id/[YOUR_DEVICE_ID] placeholder - Device name: use [YOUR_DEVICE_NAME] placeholder Benefits: - All project data in one location (easier backups) - Better portability (no host dependencies) - Cleaner codebase (removed unused variables) - Comprehensive documentation for migration and fresh install πŸ€– Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Sonnet 4.5 --- .env.example | 24 ++- .gitignore | 110 +++++++++++ FRESH_INSTALL.md | 396 +++++++++++++++++++++++++++++++++++++++ MIGRATION.md | 369 ++++++++++++++++++++++++++++++++++++ README.md | 49 +++-- app/config.py | 1 - app/routes/api.py | 3 +- app/routes/views.py | 13 +- app/templates/dm.html | 1 - app/templates/index.html | 1 - docker-compose.yml | 1 - 11 files changed, 929 insertions(+), 39 deletions(-) create mode 100644 .gitignore create mode 100644 FRESH_INSTALL.md create mode 100644 MIGRATION.md diff --git a/.env.example b/.env.example index fc6761a..19ac8b2 100644 --- a/.env.example +++ b/.env.example @@ -6,31 +6,37 @@ # ============================================ # Serial port path (use /dev/serial/by-id for stable device names) -# Find your device: ls -l /dev/serial/by-id/ -MC_SERIAL_PORT=/dev/serial/by-id/usb-Espressif_Systems_heltec_wifi_lora_32_v4__16_MB_FLASH__2_MB_PSRAM__90706984A000-if00 +# Find your device: ls /dev/serial/by-id/ +# Example: usb-Espressif_Systems_heltec_wifi_lora_32_v4__16_MB_FLASH__2_MB_PSRAM__90706984A000-if00 +MC_SERIAL_PORT=/dev/serial/by-id/[YOUR_DEVICE_ID] # Your MeshCore device name (used for .msgs file) -MC_DEVICE_NAME=MarWoj +# Example: MarWoj, SP5XYZ, MyNode +MC_DEVICE_NAME=[YOUR_DEVICE_NAME] -# MeshCore configuration directory (where .msgs file is stored) -MC_CONFIG_DIR=/home/marek/.config/meshcore +# MeshCore configuration directory (where .msgs and settings files are stored) +# Default: ./data/meshcore (inside project directory) +# This directory is mounted as a Docker volume and shared between both containers +MC_CONFIG_DIR=./data/meshcore # ============================================ # Application Settings # ============================================ -# Auto-refresh interval in seconds -MC_REFRESH_INTERVAL=60 - # Hours of inactivity before contacts can be cleaned up MC_INACTIVE_HOURS=48 +# Note: Auto-refresh is now intelligent and checks for new messages every 10 seconds +# No configuration needed - the system automatically updates UI only when new messages arrive + # ============================================ # Archive Configuration # ============================================ # Directory for storing archived messages -MC_ARCHIVE_DIR=/home/marek/.config/meshcore/archive +# Default: ./data/archive (inside project directory) +# This directory is mounted as a Docker volume for mc-webui container +MC_ARCHIVE_DIR=./data/archive # Enable automatic daily archiving at midnight MC_ARCHIVE_ENABLED=true diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000..4596db6 --- /dev/null +++ b/.gitignore @@ -0,0 +1,110 @@ +# mc-webui .gitignore + +# ============================================ +# Environment and Configuration +# ============================================ +.env +*.env +!.env.example + +# ============================================ +# Python +# ============================================ +__pycache__/ +*.py[cod] +*$py.class +*.so +.Python +build/ +develop-eggs/ +dist/ +downloads/ +eggs/ +.eggs/ +lib/ +lib64/ +parts/ +sdist/ +var/ +wheels/ +*.egg-info/ +.installed.cfg +*.egg +MANIFEST + +# ============================================ +# Virtual Environment +# ============================================ +venv/ +ENV/ +env/ +.venv + +# ============================================ +# IDE and Editors +# ============================================ +.vscode/ +.idea/ +*.swp +*.swo +*~ +.DS_Store + +# ============================================ +# Testing and Coverage +# ============================================ +.pytest_cache/ +.coverage +htmlcov/ +*.cover +.hypothesis/ + +# ============================================ +# Docker +# ============================================ +docker-compose.override.yml + +# ============================================ +# Runtime Data (Docker volumes) +# ============================================ +data/ + +# ============================================ +# Logs and Databases +# ============================================ +*.log +*.sql +*.sqlite +*.db + +# ============================================ +# OS +# ============================================ +Thumbs.db +.DS_Store + +# ============================================ +# Miscellaneous +# ============================================ +.claude/ +technotes/prompt-dms.md +technotes/channels.md +technotes/limity.md +technotes/smart-refresh-feature.md +docs/Pomoc w zwiΔ™kszeniu zasiΔ™gu.pdf +PRD.md +.gitignore +CLAUDE_CODE_PROMPT.md +technotes/advert-vs-floodadv.md +technotes/conversation-with-user-Xahgmah.md +technotes/issue_diagnosis_missing_recv.md +technotes/reddit_response.txt +technotes/troubleshooting_guide_for_user.md +technotes/reddit_response_final.txt +docs/Mesh Core – Lista Zakupowa (repeater Dachowy).pdf +docs/contact-management-next-step.md +docs/response-to-xahgmah.md +docs/UI-Contact-Management-MVP-v1.md +docs/TEST-PLAN-Contact-Management-v2.md +technotes/API-Diagnostic-Commands-private.md +docs/github-discussion-*.md diff --git a/FRESH_INSTALL.md b/FRESH_INSTALL.md new file mode 100644 index 0000000..6350a7f --- /dev/null +++ b/FRESH_INSTALL.md @@ -0,0 +1,396 @@ +# Fresh Installation Guide - mc-webui + +Step-by-step installation guide for new users. Print this page for easy reference during installation. + +## Prerequisites Checklist + +Before starting, ensure you have: + +- [ ] **Linux server** (tested on Debian, Ubuntu) +- [ ] **Docker** installed (version 20.10+) +- [ ] **Docker Compose** installed (version 2.0+) +- [ ] **Meshcore device** (e.g., Heltec V4) connected via USB +- [ ] **Git** installed +- [ ] **Basic terminal knowledge** + +**Installation guides:** +- Docker: https://wiki.wojtaszek.it/pl/home/apps/docker/installation +- Git: `sudo apt install git` + +## Installation Steps + +### Step 1: Clone the Repository + +```bash +# Navigate to your preferred directory +cd ~ + +# Clone the repository +git clone https://github.com/MarekWo/mc-webui +cd mc-webui +``` + +**Verify:** +```bash +pwd # Should show: /home/youruser/mc-webui +ls # Should show: README.md, docker-compose.yml, app/, etc. +``` + +### Step 2: Find Your Serial Device + +```bash +# List USB serial devices +ls /dev/serial/by-id/ +``` + +**Expected output (device ID):** +``` +usb-Espressif_Systems_heltec_wifi_lora_32_v4__16_MB_FLASH__2_MB_PSRAM__90706984A000-if00 +``` + +**Copy the full device ID** - you'll need it in the next step. + +### Step 3: Configure Environment + +```bash +# Copy example configuration +cp .env.example .env + +# Edit configuration +nano .env +``` + +**Required changes in .env:** + +1. **MC_SERIAL_PORT** - Update with your device from Step 2: + ```bash + MC_SERIAL_PORT=/dev/serial/by-id/usb-Espressif_Systems_heltec_wifi_lora_32_v4__16_MB_FLASH__2_MB_PSRAM__90706984A000-if00 + ``` + +2. **MC_DEVICE_NAME** - Set your device name (e.g., your callsign): + ```bash + MC_DEVICE_NAME=YourDeviceName + ``` + +3. **TZ** - Set your timezone (optional): + ```bash + TZ=Europe/Warsaw # Or your timezone + ``` + +**Leave these as default** (they use the new `./data/` structure): +```bash +MC_CONFIG_DIR=./data/meshcore # βœ… Correct - inside project +MC_ARCHIVE_DIR=./data/archive # βœ… Correct - inside project +``` + +**Save and exit:** +- Press `Ctrl+O` to save +- Press `Enter` to confirm +- Press `Ctrl+X` to exit + +### Step 4: Verify Serial Device Permissions + +```bash +# Check device permissions +ls -l /dev/serial/by-id/usb-Espressif* + +# If needed, add your user to dialout group +sudo usermod -aG dialout $USER + +# Log out and log back in for group changes to take effect +# Or use: newgrp dialout +``` + +### Step 5: Build and Start Containers + +```bash +# Build and start in detached mode +docker compose up -d --build +``` + +**This will:** +- Download base images (Python, Alpine Linux) +- Install meshcore-cli inside containers (no host installation needed!) +- Create `./data/` directory structure automatically +- Start both containers (meshcore-bridge and mc-webui) + +**Expected output:** +``` +[+] Building 45.2s (24/24) FINISHED +[+] Running 3/3 + βœ” Network mc-webui_meshcore-net Created + βœ” Container meshcore-bridge Started + βœ” Container mc-webui Started +``` + +### Step 6: Verify Installation + +**Check container status:** +```bash +docker compose ps +``` + +**Expected output:** +``` +NAME IMAGE STATUS PORTS +meshcore-bridge mc-webui-bridge Up 10 seconds +mc-webui mc-webui-app Up 10 seconds 0.0.0.0:5000->5000/tcp +``` + +Both containers should show `Up` status. + +**Check logs:** +```bash +# View all logs +docker compose logs -f + +# Or specific container +docker compose logs -f mc-webui +docker compose logs -f meshcore-bridge +``` + +**Look for:** +- βœ… "meshcli process started" (in meshcore-bridge logs) +- βœ… "Running on http://0.0.0.0:5000" (in mc-webui logs) +- ❌ No errors about USB device or permissions + +Press `Ctrl+C` to stop viewing logs. + +**Verify data directory:** +```bash +ls -la data/ +``` + +**Expected output:** +``` +drwxr-xr-x meshcore/ # Configuration directory +drwxr-xr-x archive/ # Archive directory +``` + +### Step 7: Access Web Interface + +**From the same machine:** +``` +http://localhost:5000 +``` + +**From another device on the network:** +``` +http://YOUR_SERVER_IP:5000 +``` + +**To find your server IP:** +```bash +hostname -I | awk '{print $1}' +``` + +### Step 8: Initial Configuration (In Web UI) + +1. **Main page loads** βœ… + - You should see the chat interface + - Default channel is "Public" + +2. **Wait for initial sync** (can take 1-2 minutes) + - Messages will appear as they arrive + - Check notification bell for updates + +3. **Optional: Enable manual contact approval** + - Open menu (☰) + - Select "Contact Management" + - Toggle "Manual Contact Approval" if desired + +4. **Test sending a message** + - Type a message in the input field + - Press Enter or click Send + - Message should appear in chat history + +### Step 9: Test Basic Features + +**Checklist:** + +- [ ] View messages in Public channel +- [ ] Send a test message +- [ ] Check notification bell (should show unread count) +- [ ] Open menu (☰) - verify it slides out +- [ ] View "Manage Channels" modal +- [ ] Check "Contact Management" page +- [ ] Verify device info (Settings β†’ Device Info) + +## Common Issues and Solutions + +### Issue: Container won't start + +**Check logs:** +```bash +docker compose logs meshcore-bridge +docker compose logs mc-webui +``` + +**Common causes:** +- Serial port not found β†’ Verify MC_SERIAL_PORT in .env +- Permission denied β†’ Add user to dialout group (Step 4) +- Port 5000 already in use β†’ Change FLASK_PORT in .env + +### Issue: Cannot access web interface + +**Check if port is open:** +```bash +sudo netstat -tulpn | grep 5000 +``` + +**Check firewall:** +```bash +# Allow port 5000 (if using UFW) +sudo ufw allow 5000/tcp +``` + +**Check container is running:** +```bash +docker compose ps +``` + +### Issue: No messages appearing + +**Verify meshcli is working:** +```bash +# Test meshcli directly in bridge container +docker compose exec meshcore-bridge meshcli -s /dev/ttyUSB0 infos +``` + +**Check .msgs file:** +```bash +docker compose exec mc-webui cat /root/.config/meshcore/YourDeviceName.msgs +``` + +Replace `YourDeviceName` with your MC_DEVICE_NAME. + +### Issue: USB device errors + +**Check device connection:** +```bash +ls -l /dev/serial/by-id/ +``` + +**Restart bridge container:** +```bash +docker compose restart meshcore-bridge +``` + +**Check device permissions:** +```bash +ls -l /dev/serial/by-id/usb-Espressif* +``` + +Should show `crw-rw----` with group `dialout`. + +## Maintenance Commands + +**View logs:** +```bash +docker compose logs -f # All services +docker compose logs -f mc-webui # Main app only +docker compose logs -f meshcore-bridge # Bridge only +``` + +**Restart services:** +```bash +docker compose restart # Restart both +docker compose restart mc-webui # Restart main app only +docker compose restart meshcore-bridge # Restart bridge only +``` + +**Stop application:** +```bash +docker compose down +``` + +**Update to latest version:** +```bash +git pull origin main +docker compose down +docker compose up -d --build +``` + +**View container status:** +```bash +docker compose ps +``` + +**Access container shell:** +```bash +docker compose exec mc-webui sh +docker compose exec meshcore-bridge sh +``` + +## Backup Your Data + +**All important data is in the `data/` directory:** + +```bash +# Create backup +cd ~/mc-webui +tar -czf ../mc-webui-backup-$(date +%Y%m%d).tar.gz data/ + +# Verify backup +ls -lh ../mc-webui-backup-*.tar.gz +``` + +**Recommended backup schedule:** +- Weekly backups of `data/` directory +- Before major updates +- After significant configuration changes + +**Restore from backup:** +```bash +# Stop application +cd ~/mc-webui +docker compose down + +# Restore data +tar -xzf ../mc-webui-backup-YYYYMMDD.tar.gz + +# Restart +docker compose up -d +``` + +## Next Steps + +After successful installation: + +1. **Join channels** - Create or join encrypted channels with other users +2. **Configure contacts** - Enable manual approval if desired +3. **Test Direct Messages** - Send DM to other CLI contacts +4. **Set up backups** - Schedule regular backups of `data/` directory +5. **Read full documentation** - See [README.md](README.md) for all features + +## Getting Help + +**Documentation:** +- Full README: [README.md](README.md) +- MeshCore docs: https://meshcore.org +- meshcore-cli docs: https://github.com/meshcore-dev/meshcore-cli + +**Issues:** +- GitHub Issues: https://github.com/MarekWo/mc-webui/issues +- Check existing issues before creating new ones +- Include logs when reporting problems + +## Installation Summary + +After completing this guide, you should have: + +- βœ… mc-webui running in Docker containers +- βœ… Web interface accessible at http://YOUR_IP:5000 +- βœ… All data stored in `./data/` directory +- βœ… meshcore-cli integrated (no host installation) +- βœ… Basic understanding of Docker commands +- βœ… Backup strategy in place + +**Congratulations! Your mc-webui installation is complete.** πŸŽ‰ + +You can now use the web interface to chat on the MeshCore network without SSH/terminal access. + +--- + +**Version:** 2025-12-30 +**For:** mc-webui fresh installations with new `./data/` structure diff --git a/MIGRATION.md b/MIGRATION.md new file mode 100644 index 0000000..c50315f --- /dev/null +++ b/MIGRATION.md @@ -0,0 +1,369 @@ +# Migration Guide - Moving Data to Project Directory + +This guide helps you migrate from the old configuration (data stored outside project) to the new configuration (all data in `./data/` inside project). + +## Who Needs This Guide? + +If you installed mc-webui **before 2025-12-29** and your `.env` file contains **absolute paths** (starting with `/`) like these examples: +```bash +MC_CONFIG_DIR=/home/marek/.config/meshcore +MC_CONFIG_DIR=/opt/meshcore +MC_CONFIG_DIR=/var/lib/meshcore +# ... or any other absolute path outside the project directory +``` + +Then you should follow this migration guide to move your data into the project directory. + +**You do NOT need this guide if:** +- Your `.env` already has `MC_CONFIG_DIR=./data/meshcore` (you're already using the new structure) +- You just installed mc-webui for the first time + +## Why Migrate? + +**Benefits of new structure:** +- βœ… All project data in one place (easier backups) +- βœ… No dependency on host directories +- βœ… Better isolation and portability +- βœ… Simpler setup for new deployments + +## Before You Start + +**⚠️ IMPORTANT: Check your current paths!** + +Before proceeding, you need to know where YOUR data is currently stored. Run this command to check your current configuration: + +```bash +cd ~/mc-webui +grep -E "^MC_CONFIG_DIR|^MC_ARCHIVE_DIR" .env +``` + +**Example output:** +``` +MC_CONFIG_DIR=/home/marek/.config/meshcore +MC_ARCHIVE_DIR=/home/marek/.config/meshcore/archive +``` + +**Write down these paths!** You will need them in the following steps. Replace any example paths shown below with YOUR actual paths from the .env file. + +## Migration Steps + +### Step 1: Stop the Application + +```bash +cd ~/mc-webui +docker compose down +``` + +### Step 2: Backup Your Current Data + +**Important:** Always backup before migration! + +**Replace the paths below with YOUR paths from the previous check!** + +```bash +# IMPORTANT: Replace /home/marek/.config/meshcore with YOUR MC_CONFIG_DIR path! +# Example command (adjust paths to match your .env): +tar -czf ~/mc-webui-backup-$(date +%Y%m%d).tar.gz \ + /home/marek/.config/meshcore/*.msgs \ + /home/marek/.config/meshcore/*.adverts.jsonl \ + /home/marek/.config/meshcore/*_dm_sent.jsonl \ + /home/marek/.config/meshcore/.webui_settings.json \ + /home/marek/.config/meshcore/archive/ +``` + +**If your MC_CONFIG_DIR is different, use it instead!** For example: +- If `MC_CONFIG_DIR=/opt/meshcore`, use `/opt/meshcore/*.msgs` etc. +- If `MC_CONFIG_DIR=/var/lib/meshcore`, use `/var/lib/meshcore/*.msgs` etc. + +Verify backup was created: +```bash +ls -lh ~/mc-webui-backup-*.tar.gz +``` + +### Step 3: Create New Data Directory Structure + +```bash +cd ~/mc-webui + +# Create new directory structure +mkdir -p data/meshcore +mkdir -p data/archive +``` + +### Step 4: Copy Existing Data + +**⚠️ IMPORTANT: Use YOUR paths from the "Before You Start" check!** + +The commands below use `/home/marek/.config/meshcore` as an example. **Replace it with your actual MC_CONFIG_DIR path!** + +```bash +# Copy meshcore configuration files +# Replace /home/marek/.config/meshcore with YOUR MC_CONFIG_DIR path! +cp /home/marek/.config/meshcore/*.msgs data/meshcore/ 2>/dev/null || true +cp /home/marek/.config/meshcore/*.adverts.jsonl data/meshcore/ 2>/dev/null || true +cp /home/marek/.config/meshcore/*_dm_sent.jsonl data/meshcore/ 2>/dev/null || true +cp /home/marek/.config/meshcore/.webui_settings.json data/meshcore/ 2>/dev/null || true + +# Copy archive files +# Replace /home/marek/.config/meshcore/archive with YOUR MC_ARCHIVE_DIR path! +cp -r /home/marek/.config/meshcore/archive/* data/archive/ 2>/dev/null || true +``` + +**Alternative: Use variables for easier path substitution** + +```bash +# Set your paths from .env (replace with YOUR actual paths!) +OLD_CONFIG_DIR="/home/marek/.config/meshcore" +OLD_ARCHIVE_DIR="/home/marek/.config/meshcore/archive" + +# Copy files using variables +cp $OLD_CONFIG_DIR/*.msgs data/meshcore/ 2>/dev/null || true +cp $OLD_CONFIG_DIR/*.adverts.jsonl data/meshcore/ 2>/dev/null || true +cp $OLD_CONFIG_DIR/*_dm_sent.jsonl data/meshcore/ 2>/dev/null || true +cp $OLD_CONFIG_DIR/.webui_settings.json data/meshcore/ 2>/dev/null || true +cp -r $OLD_ARCHIVE_DIR/* data/archive/ 2>/dev/null || true +``` + +Verify files were copied: +```bash +ls -la data/meshcore/ +ls -la data/archive/ +``` + +### Step 5: Update .env File + +**Goal:** Change your old paths to new project-relative paths. + +**Old configuration (your current paths):** +```bash +MC_CONFIG_DIR=/home/marek/.config/meshcore # Example - yours may be different! +MC_ARCHIVE_DIR=/home/marek/.config/meshcore/archive # Example - yours may be different! +``` + +**New configuration (same for everyone):** +```bash +MC_CONFIG_DIR=./data/meshcore +MC_ARCHIVE_DIR=./data/archive +``` + +**Option A: Automatic update with sed (recommended)** + +This will work regardless of your old paths: + +```bash +cd ~/mc-webui + +# Backup .env +cp .env .env.backup + +# Update MC_CONFIG_DIR (replaces any old path with new one) +sed -i 's|MC_CONFIG_DIR=.*|MC_CONFIG_DIR=./data/meshcore|' .env + +# Update MC_ARCHIVE_DIR (replaces any old path with new one) +sed -i 's|MC_ARCHIVE_DIR=.*|MC_ARCHIVE_DIR=./data/archive|' .env +``` + +**Option B: Manual edit** + +```bash +nano .env +# Change MC_CONFIG_DIR to: ./data/meshcore +# Change MC_ARCHIVE_DIR to: ./data/archive +# Save and exit (Ctrl+O, Enter, Ctrl+X) +``` + +**Verify changes (IMPORTANT!):** +```bash +grep -E "MC_CONFIG_DIR|MC_ARCHIVE_DIR" .env +``` + +**Expected output (should be the same for everyone):** +``` +MC_CONFIG_DIR=./data/meshcore +MC_ARCHIVE_DIR=./data/archive +``` + +If you see anything different, fix it before proceeding! + +### Step 6: Set Correct Permissions + +```bash +# Ensure Docker can read/write the data directory +chmod -R 755 data/ +``` + +### Step 7: Restart Application + +```bash +cd ~/mc-webui +docker compose up -d --build +``` + +### Step 8: Verify Migration + +Check that the application is running correctly: + +```bash +# Check container status +docker compose ps + +# Check logs for errors +docker compose logs -f mc-webui +docker compose logs -f meshcore-bridge + +# Verify data files are accessible in containers +docker compose exec mc-webui ls -la /root/.config/meshcore/ +docker compose exec mc-webui ls -la /root/.archive/meshcore/ +``` + +**Test the web interface:** +1. Open http://localhost:5000 (or your server IP) +2. Verify that old messages are visible +3. Send a test message to confirm everything works +4. Check if your contact list is preserved +5. Verify archived messages are accessible (if you had any) + +### Step 9: Cleanup (Optional) + +**⚠️ DANGER ZONE - Only after confirming everything works!** + +If you're confident the migration was successful and have tested the application for several days, you can remove old data. + +**⚠️ USE YOUR OLD PATH - not the example below!** + +```bash +# CAREFUL! This deletes old data permanently +# Only run this after verifying the new setup works! + +# Remove old meshcore data +# Replace /home/marek/.config/meshcore with YOUR old MC_CONFIG_DIR path! +rm -rf /home/marek/.config/meshcore/ + +# Alternative: Use the path from your .env.backup +OLD_PATH=$(grep "^MC_CONFIG_DIR=" .env.backup | cut -d'=' -f2) +echo "About to delete: $OLD_PATH" +# Verify the path is correct, then uncomment the line below: +# rm -rf "$OLD_PATH" + +# Remove backup after a few days of successful operation +# rm ~/mc-webui-backup-*.tar.gz +``` + +**Recommendations:** +- Keep the backup for at least **one week** before deleting it +- Test all features before cleanup (messaging, channels, DM, contacts, archives) +- Consider keeping old data as additional backup for a month + +## Troubleshooting + +### Issue: No messages visible after migration + +**Solution:** +1. Check if files were copied correctly: + ```bash + ls -la data/meshcore/ + ``` +2. Verify the `.msgs` file exists and has content: + ```bash + cat data/meshcore/MarWoj.msgs # Replace MarWoj with your device name + ``` +3. Check container logs for errors: + ```bash + docker compose logs mc-webui | grep -i error + ``` + +### Issue: Permission denied errors + +**Solution:** +```bash +# Fix permissions +sudo chown -R $USER:$USER data/ +chmod -R 755 data/ +``` + +### Issue: Archives not showing + +**Solution:** +1. Check if archive files exist: + ```bash + ls -la data/archive/ + ``` +2. Verify MC_ARCHIVE_DIR in .env: + ```bash + grep MC_ARCHIVE_DIR .env + ``` +3. Restart the application: + ```bash + docker compose restart + ``` + +### Issue: Contact settings lost + +**Solution:** +1. Check if `.webui_settings.json` was copied: + ```bash + cat data/meshcore/.webui_settings.json + ``` +2. If missing, recreate it manually: + ```bash + echo '{"manual_add_contacts": false}' > data/meshcore/.webui_settings.json + ``` +3. Restart bridge: + ```bash + docker compose restart meshcore-bridge + ``` + +## Rollback Plan + +If migration fails and you need to rollback: + +```bash +# Stop containers +docker compose down + +# Restore .env from backup +cd ~/mc-webui +cp .env.backup .env + +# Remove new data directory (optional) +rm -rf data/ + +# Restore from backup +cd ~ +tar -xzf mc-webui-backup-*.tar.gz + +# Start with old configuration +cd ~/mc-webui +docker compose up -d +``` + +## Getting Help + +If you encounter issues during migration: + +1. Check the logs: + ```bash + docker compose logs -f + ``` + +2. Verify your configuration: + ```bash + cat .env | grep -E "MC_CONFIG_DIR|MC_ARCHIVE_DIR|MC_DEVICE_NAME" + ``` + +3. Report the issue on GitHub: + - Repository: https://github.com/MarekWo/mc-webui + - Include: error logs, .env configuration (remove sensitive data), system info + +## Summary + +After successful migration: +- βœ… All data is in `./data/` directory inside project +- βœ… Configuration uses relative paths (`./data/meshcore`, `./data/archive`) +- βœ… Backups are simpler (just backup the `data/` directory) +- βœ… Project is more portable (can move entire directory to another server) + +**Next steps:** +- Keep backup for at least one week +- Test all features (messaging, channels, DM, contacts, archives) +- Consider setting up automated backups of `./data/` directory diff --git a/README.md b/README.md index 6d3c1f2..faab8cb 100644 --- a/README.md +++ b/README.md @@ -42,18 +42,19 @@ A lightweight web interface for meshcore-cli, providing browser-based access to ### Prerequisites -- Docker and Docker Compose installed -- Heltec V4 device connected via USB +- **Docker** and **Docker Compose** installed ([installation guide](https://wiki.wojtaszek.it/pl/home/apps/docker/installation)) +- **Meshcore device** connected via USB (tested on Heltec V4) -**Note:** meshcore-cli is automatically installed inside the Docker container - no host installation required! - -**Important:** This application requires meshcore-cli version **1.3.12 or newer** for proper Direct Messages (DM) functionality. The Docker container automatically installs the latest version. +**Important Notes:** +- βœ… **No meshcore-cli installation required on host** - meshcore-cli is automatically installed inside the Docker container +- βœ… **No manual directory setup needed** - all data is stored in `./data/` inside the project directory +- βœ… **meshcore-cli version 1.3.12+** is automatically installed for proper Direct Messages (DM) functionality ### Installation 1. **Clone the repository** ```bash - git clone + git clone https://github.com/MarekWo/mc-webui cd mc-webui ``` @@ -66,15 +67,24 @@ A lightweight web interface for meshcore-cli, providing browser-based access to 3. **Find your serial device** ```bash - ls -l /dev/serial/by-id/ + ls /dev/serial/by-id/ + ``` + You should see a device name starting with `usb-Espressif_Systems_...`. For Heltec V4 it looks like: + ``` + usb-Espressif_Systems_heltec_wifi_lora_32_v4__16_MB_FLASH__2_MB_PSRAM__90706984A000-if00 + ``` + Copy the **full device ID** and update `MC_SERIAL_PORT` in `.env`: + ```bash + MC_SERIAL_PORT=/dev/serial/by-id/usb-Espressif_Systems_heltec_wifi_lora_32_v4__16_MB_FLASH__2_MB_PSRAM__90706984A000-if00 ``` - Update `MC_SERIAL_PORT` in `.env` with your device path. 4. **Build and run** ```bash docker compose up -d --build ``` + **Note:** Docker will automatically create the `./data/` directory with necessary subdirectories (`meshcore/` and `archive/`) on first run. All runtime data (messages, contacts, settings, archives) will be stored there. + 5. **Access the web interface** Open your browser and navigate to: ``` @@ -82,21 +92,24 @@ A lightweight web interface for meshcore-cli, providing browser-based access to ``` Or from another device on your network: ``` - http://:5000 + http://:5000 ``` ## Configuration -All configuration is done via environment variables in the `.env` file: +All configuration is done via environment variables in the `.env` file. + +**Important:** All data files (messages, contacts, settings, archives) are stored in the `./data/` directory inside your project folder. This directory is automatically created by Docker and should be included in your backups. + +### Environment Variables | Variable | Description | Default | |----------|-------------|---------| -| `MC_SERIAL_PORT` | Path to serial device | `/dev/ttyUSB0` | +| `MC_SERIAL_PORT` | Serial device path (use /dev/serial/by-id/ for stability) | `/dev/ttyUSB0` | | `MC_DEVICE_NAME` | Device name (for .msgs and .adverts.jsonl files) | `MeshCore` | -| `MC_CONFIG_DIR` | meshcore configuration directory | `/root/.config/meshcore` | -| `MC_REFRESH_INTERVAL` | Auto-refresh interval (seconds) | `60` | -| `MC_INACTIVE_HOURS` | Inactivity threshold for cleanup | `48` | -| `MC_ARCHIVE_DIR` | Archive directory path | `/mnt/archive/meshcore` | +| `MC_CONFIG_DIR` | Configuration directory (shared between containers) | `./data/meshcore` | +| `MC_INACTIVE_HOURS` | Inactivity threshold for contact cleanup (hours) | `48` | +| `MC_ARCHIVE_DIR` | Archive directory path | `./data/archive` | | `MC_ARCHIVE_ENABLED` | Enable automatic archiving | `true` | | `MC_ARCHIVE_RETENTION_DAYS` | Days to show in live view | `7` | | `FLASK_HOST` | Listen address | `0.0.0.0` | @@ -104,6 +117,12 @@ All configuration is done via environment variables in the `.env` file: | `FLASK_DEBUG` | Debug mode | `false` | | `TZ` | Timezone for container logs | `UTC` | +**Notes:** +- `MC_CONFIG_DIR` is mounted as a shared volume for both containers (meshcore-bridge and mc-webui) +- All paths starting with `./` are relative to the project root directory +- The `data/` directory is excluded from git via `.gitignore` +- Auto-refresh is intelligent: checks for new messages every 10 seconds, updates UI only when needed (no configuration required) + See [.env.example](.env.example) for a complete example. ## Architecture diff --git a/app/config.py b/app/config.py index 09430a4..73f6f9f 100644 --- a/app/config.py +++ b/app/config.py @@ -18,7 +18,6 @@ class Config: MC_BRIDGE_URL = os.getenv('MC_BRIDGE_URL', 'http://meshcore-bridge:5001/cli') # Application settings - MC_REFRESH_INTERVAL = int(os.getenv('MC_REFRESH_INTERVAL', '60')) MC_INACTIVE_HOURS = int(os.getenv('MC_INACTIVE_HOURS', '48')) # Archive configuration diff --git a/app/routes/api.py b/app/routes/api.py index 883bd4c..6d0b387 100644 --- a/app/routes/api.py +++ b/app/routes/api.py @@ -212,8 +212,7 @@ def get_status(): 'device_name': config.MC_DEVICE_NAME, 'serial_port': config.MC_SERIAL_PORT, 'message_count': message_count, - 'latest_message_timestamp': latest_timestamp, - 'refresh_interval': config.MC_REFRESH_INTERVAL + 'latest_message_timestamp': latest_timestamp }), 200 except Exception as e: diff --git a/app/routes/views.py b/app/routes/views.py index 1abebec..f182b8a 100644 --- a/app/routes/views.py +++ b/app/routes/views.py @@ -18,8 +18,7 @@ def index(): """ return render_template( 'index.html', - device_name=config.MC_DEVICE_NAME, - refresh_interval=config.MC_REFRESH_INTERVAL + device_name=config.MC_DEVICE_NAME ) @@ -36,7 +35,6 @@ def direct_messages(): return render_template( 'dm.html', device_name=config.MC_DEVICE_NAME, - refresh_interval=config.MC_REFRESH_INTERVAL, initial_conversation=initial_conversation ) @@ -48,8 +46,7 @@ def contact_management(): """ return render_template( 'contacts-manage.html', - device_name=config.MC_DEVICE_NAME, - refresh_interval=config.MC_REFRESH_INTERVAL + device_name=config.MC_DEVICE_NAME ) @@ -60,8 +57,7 @@ def contact_pending_list(): """ return render_template( 'contacts-pending.html', - device_name=config.MC_DEVICE_NAME, - refresh_interval=config.MC_REFRESH_INTERVAL + device_name=config.MC_DEVICE_NAME ) @@ -72,8 +68,7 @@ def contact_existing_list(): """ return render_template( 'contacts-existing.html', - device_name=config.MC_DEVICE_NAME, - refresh_interval=config.MC_REFRESH_INTERVAL + device_name=config.MC_DEVICE_NAME ) diff --git a/app/templates/dm.html b/app/templates/dm.html index 6ff9b61..e254ac2 100644 --- a/app/templates/dm.html +++ b/app/templates/dm.html @@ -169,7 +169,6 @@ diff --git a/docker-compose.yml b/docker-compose.yml index e3ad321..80a18e6 100644 --- a/docker-compose.yml +++ b/docker-compose.yml @@ -40,7 +40,6 @@ services: - MC_BRIDGE_URL=http://meshcore-bridge:5001/cli - MC_DEVICE_NAME=${MC_DEVICE_NAME} - MC_CONFIG_DIR=/root/.config/meshcore - - MC_REFRESH_INTERVAL=${MC_REFRESH_INTERVAL:-60} - MC_INACTIVE_HOURS=${MC_INACTIVE_HOURS:-48} - MC_ARCHIVE_DIR=/root/.archive/meshcore - MC_ARCHIVE_ENABLED=${MC_ARCHIVE_ENABLED:-true}