iarv/mc-webui
1
0
Fork 1
mirror of https://github.com/MarekWo/mc-webui.git synced 2026-03-28 17:42:45 +01:00
Code Issues Packages Projects Releases Wiki Activity

docs: Refactor installation documentation and fix typos

Browse Source 
- Fix typos in README.md installation section:
  - "Chose" -> "Choose"
  - "prepeare" -> "prepare"
  - Fix code block formatting (line 156-158)
  - Fix markdown formatting (line 254)
- Add COMMON_ISSUES.md for troubleshooting (separate from README)
- Add DOCKER_INSTALL.md with Docker installation guide
- Add installation guide images
- Remove FRESH_INSTALL.md (consolidated into README)
- Remove MIGRATION.md (no longer needed)
- Update version date to 2026-01-06 in COMMON_ISSUES.md

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
This commit is contained in:
MarekWo
2026-01-06 17:42:39 +01:00
parent 4bd6a681db
commit 9180aa4ac9
10 changed files with 445 additions and 814 deletions
Download Patch File Download Diff File Expand all files Collapse all files

163
COMMON_ISSUES.md Normal file
View File

@@ -0,0 +1,163 @@
## 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
---
**Version:** 2026-01-06

91
DOCKER_INSTALL.md Normal file
View File

@@ -0,0 +1,91 @@
# How to Install Docker Engine on Debian / Ubuntu
This guide provides step-by-step instructions for installing Docker Engine on a Debian-based system using Docker's official repository. This is the recommended method as it ensures you get the latest and most stable version.
-----
### Step 1: Set Up the Docker Repository
Next, configure your system to download packages from the official Docker repository instead of the default Debian repository.
#### a. Update the package index and install dependencies:
```bash
sudo apt-get update
sudo apt-get install ca-certificates curl
```
#### b. Add Docker’s official GPG key:
This step ensures that the packages you download are authentic.
```bash
sudo install -m 0755 -d /etc/apt/keyrings && \
sudo curl -fsSL https://download.docker.com/linux/debian/gpg -o /etc/apt/keyrings/docker.asc && \
sudo chmod a+r /etc/apt/keyrings/docker.asc
```
#### c. Add the repository to your APT sources:
This command automatically detects your Debian version and sets up the repository accordingly.
```bash
echo \
"deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.asc] https://download.docker.com/linux/debian \
$(. /etc/os-release && echo "$VERSION_CODENAME") stable" | \
sudo tee /etc/apt/sources.list.d/docker.list > /dev/null
```
-----
### Step 2: Install Docker Engine
Now you can install the latest version of Docker Engine and its related components.
#### a. Update the package index again:
```bash
sudo apt-get update
```
#### b. Install Docker Engine, CLI, Containerd, and Compose plugin:
The `docker-compose-plugin` package provides the `docker compose` command.
```bash
sudo apt-get install docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin
```
-----
### Step 3: Verify the Installation ✅
Run the `hello-world` image to confirm that Docker Engine is installed and running correctly.
```bash
sudo docker run hello-world
```
If the installation was successful, you will see a "Hello from Docker\!" message in your terminal.
-----
### Step 4 (Optional): Manage Docker as a Non-root User
To avoid typing `sudo` every time you run a Docker command, add your user to the `docker` group.
#### a. Create the `docker` group (if it doesn't already exist):
```bash
sudo groupadd docker
```
#### b. Add your user to the `docker` group:
```bash
sudo usermod -aG docker $USER
```
**Important:** You need to **log out and log back in** for this change to take effect. Alternatively, you can run `newgrp docker` in your current terminal session to activate the new group membership.
After this, you can run Docker commands directly (e.g., `docker ps`).

396
FRESH_INSTALL.md
View File

@@ -1,396 +0,0 @@
# 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

369
MIGRATION.md
View File

@@ -1,369 +0,0 @@
# 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

240
README.md
View File

@@ -65,81 +65,223 @@ A lightweight web interface for meshcore-cli, providing browser-based access to
- ✅ **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
0. **Prepare the device**
- **Flash the device** at [https://flasher.meshcore.co.uk/](https://flasher.meshcore.co.uk/). Choose the `Companion USB` role.
- **Configure the device** with the Meshcore mobile app (from Google Play Store / App Store).
- Name
- Location (optional)
- Preset
- **Install / prepare your Linux server**. You will need the following elements installed:
- git
- docker (you may want [to check this Docker installation guide](DOCKER_INSTALL.md))
1. **Clone the repository**
```bash
git clone https://github.com/MarekWo/mc-webui
cd mc-webui
```
```bash
# Navigate to your preferred directory
cd ~
2. **Configure environment**
```bash
cp .env.example .env
# Edit .env with your settings
nano .env
```
# Clone the repository
git clone https://github.com/MarekWo/mc-webui
cd mc-webui
```
3. **Find your serial device**
**Verify:**
```bash
pwd # Should show: /home/<youruser>/mc-webui
ls # Should show: README.md, docker-compose.yml, app/, etc.
```
2. **Find your serial device ID**
```bash
# List USB serial devices
ls /dev/serial/by-id/
```
You should see a device name starting with `usb-Espressif_Systems_...`. For Heltec V4 it looks like:
You should see a device name starting with `usb-...`. For Heltec V4 may look 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
For Heltec V3 it may be something similar to:
```
usb-Silicon_Labs_CP2102_USB_to_UART_Bridge_Controller_0001-if00-port0
```
**Copy the full device ID** - you'll need it in the next step.
<br>
4. **Build and run**
```bash
docker compose up -d --build
```
3. **Configure your environment**
```bash
# Copy example configuration
cp .env.example .env
**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.
# Edit configuration
nano .env # or you can used your favorite text editor
```
5. **Access the web interface**
Open your browser and navigate to:
```
http://localhost:5000
```
Or from another device on your network:
**Required changes in .env:**
- **MC_SERIAL_PORT** - Update with your device from Step 2:
```bash
MC_SERIAL_PORT=/dev/serial/by-id/<your-device-id>
```
- **MC_DEVICE_NAME** - Set your device name (e.g., your callsign):
```bash
MC_DEVICE_NAME=<your-device-name>
```
- **TZ** - Set your timezone (optional):
```bash
TZ=Europe/Warsaw # Pick your timezone
```
**Leave these as default**:
```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
<br>
4. **Verify Serial Device Permissions**
```bash
# Check device permissions
ls -l /dev/serial/by-id/usb-*
```
You should get something like this:
```
lrwxrwxrwx 1 root root 13 Jan 6 14:07 /dev/serial/by-id/usb-<your-device-id> -> ../../ttyUSB0
```
<br>
```bash
# 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
```
5. **Build and run**
```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
```
6. **Verify instalation**
**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
```
7. **Access the web interface**
Open your browser and navigate to:
```
http://<your-server-ip>:5000
```
## Configuration
**To find your server IP:**
```bash
hostname -I | awk '{print $1}'
```
All configuration is done via environment variables in the `.env` file.
8. **Initial Configuration (In Web UI)**
**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.
- **Main page loads** ✅
- You should see the chat interface
- Default channel is "Public"
### Environment Variables
- **Wait for initial sync** (can take 1-2 minutes)
- Messages will appear as they arrive
- Check notification bell for updates
| Variable | Description | Default |
|----------|-------------|---------|
| `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` | Configuration directory (shared between containers) | `./data/meshcore` |
| `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` |
| `FLASK_PORT` | Application port | `5000` |
| `FLASK_DEBUG` | Debug mode | `false` |
| `TZ` | Timezone for container logs | `UTC` |
- **Optional but highly recommended: Enable manual contact approval**
- Open menu (☰)
- Select "Contact Management"
- Toggle "Manual Contact Approval"
**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)
- **Test sending a message**
- Type a message in the input field
- Press Enter or click Send
- Message should appear in chat history
See [.env.example](.env.example) for a complete example.
## 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.
Please also check the Common Issues guide [here](COMMON_ISSUES.md).
---
## Architecture
mc-webui uses a **2-container architecture** for improved USB stability:

BIN
images/installation guide/01-02. Flashing - selecting role.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 14 KiB

BIN
images/installation guide/01-03. Flashing - connecting to device.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 11 KiB

BIN
images/installation guide/01-04. Flashing - flashing process.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 22 KiB

BIN
images/installation guide/01. Flashing.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 117 KiB

BIN
images/installation guide/manual approval.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 32 KiB