mc-webui/docs/troubleshooting.md

Troubleshooting Guide

Common issues and solutions for mc-webui.

Table of Contents

• Common Issues
• Docker Commands
• Testing Bridge API
• Backup and Restore
• Next Steps
• Getting Help

---

Common Issues

Container won't start

Check logs:

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
• Port 5000 already in use → Change FLASK_PORT in .env

---

Cannot access web interface

Check if port is open:

sudo netstat -tulpn | grep 5000

Check firewall:

# Allow port 5000 (if using UFW)
sudo ufw allow 5000/tcp

Check container is running:

docker compose ps

---

No messages appearing

Verify meshcli is working:

# Test meshcli directly in bridge container
docker compose exec meshcore-bridge meshcli -s /dev/ttyUSB0 infos

Check .msgs file:

docker compose exec mc-webui cat /root/.config/meshcore/YourDeviceName.msgs

Replace YourDeviceName with your MC_DEVICE_NAME.

---

Device not found

# Check if device is connected
ls -l /dev/serial/by-id/

# Verify device permissions
sudo chmod 666 /dev/serial/by-id/usb-Espressif*

---

USB device errors

Check device connection:

ls -l /dev/serial/by-id/

Restart bridge container:

docker compose restart meshcore-bridge

Check device permissions:

ls -l /dev/serial/by-id/usb-Espressif*

Should show crw-rw---- with group dialout.

---

USB Communication Issues

The 2-container architecture resolves common USB timeout/deadlock problems:

• meshcore-bridge has exclusive USB access
• mc-webui uses HTTP (no direct device access)
• Restarting mc-webui does not affect USB connection
• If bridge has USB issues, restart only that service:

  docker compose restart meshcore-bridge
  

---

Bridge connection errors

# Check bridge health
docker compose exec mc-webui curl http://meshcore-bridge:5001/health

# Bridge logs
docker compose logs -f meshcore-bridge

# Test meshcli directly in bridge container
docker compose exec meshcore-bridge meshcli -s /dev/ttyUSB0 infos

---

Messages not updating

• Check that .msgs file exists in MC_CONFIG_DIR
• Verify bridge service is healthy: docker compose ps
• Check bridge logs for command errors

---

Contact Management Issues

Check logs:

# mc-webui container logs
docker compose logs -f mc-webui

# meshcore-bridge container logs (where settings are applied)
docker compose logs -f meshcore-bridge

Look for:

• "Loaded webui settings" - confirms settings file is being read
• "manual_add_contacts set to on/off" - confirms setting is applied to meshcli session
• "Saved manual_add_contacts=..." - confirms setting is persisted to file

---

Docker Commands

View logs

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

docker compose restart              # Restart both
docker compose restart mc-webui     # Restart main app only
docker compose restart meshcore-bridge  # Restart bridge only

Start / Stop

# Start the application
docker compose up -d

# Stop the application
docker compose down

# Rebuild after code changes
docker compose up -d --build

Check status

docker compose ps

Access container shell

docker compose exec mc-webui sh
docker compose exec meshcore-bridge sh

---

Testing Bridge API

The meshcore-bridge container exposes HTTP endpoints for diagnostics.

Test endpoints

# List pending contacts (from inside mc-webui container or server)
curl -s http://meshcore-bridge:5001/pending_contacts | jq

# Add a pending contact
curl -s -X POST http://meshcore-bridge:5001/add_pending \
  -H 'Content-Type: application/json' \
  -d '{"selector":"Skyllancer"}' | jq

# Check bridge health
docker compose exec mc-webui curl http://meshcore-bridge:5001/health

Example responses

GET /pending_contacts:

{
  "success": true,
  "pending": [
    {
      "name": "Skyllancer",
      "public_key": "f9ef..."
    },
    {
      "name": "KRA Reksio mob2🐕",
      "public_key": "41d5..."
    }
  ],
  "raw_stdout": "Skyllancer: f9ef...\nKRA Reksio mob2🐕: 41d5..."
}

POST /add_pending:

{
  "success": true,
  "stdout": "Contact added successfully",
  "stderr": "",
  "returncode": 0
}

Note: These endpoints require manual_add_contacts mode to be enabled.

---

Backup and Restore

All important data is in the data/ directory.

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

# 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 User Guide for all features

---

Getting Help

Documentation:

• User Guide - How to use all features
• Architecture - Technical documentation
• README - Installation guide
• 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