meshcore-usb-dashboard/DEPLOYMENT.md

Deployment Guide

This guide covers deploying the Meshtastic MQTT Dashboard to production environments.

Pre-Deployment Checklist

• Change SESSION_SECRET to a strong random string
• Set NODE_ENV=production in .env
• Review and adjust MQTT broker settings
• Configure data retention policies
• Set up SSL/TLS certificates
• Configure firewall rules
• Plan backup strategy
• Create initial user accounts
• Test the application locally

Deployment Options

Option 1: Traditional Server (Linux)

Requirements

• Ubuntu 20.04+ or similar Linux distribution
• Node.js 16.x or higher
• Nginx (for reverse proxy and SSL)
• 1GB+ RAM
• 10GB+ disk space

Steps

1. Install Node.js

curl -fsSL https://deb.nodesource.com/setup_18.x | sudo -E bash -
sudo apt-get install -y nodejs

2. Clone/Upload Application

cd /opt
sudo mkdir meshtastic-dashboard
sudo chown $USER:$USER meshtastic-dashboard
cd meshtastic-dashboard
# Upload your files here

3. Install Dependencies

npm ci --production

4. Configure Environment

cp .env.example .env
nano .env  # Edit configuration

5. Create User

npm run create-user

6. Set Up Systemd Service

Create /etc/systemd/system/meshtastic-dashboard.service:

[Unit]
Description=Meshtastic MQTT Dashboard
After=network.target

[Service]
Type=simple
User=www-data
WorkingDirectory=/opt/meshtastic-dashboard
Environment=NODE_ENV=production
ExecStart=/usr/bin/node src/server.js
Restart=on-failure
RestartSec=10

[Install]
WantedBy=multi-user.target

Enable and start:

sudo systemctl daemon-reload
sudo systemctl enable meshtastic-dashboard
sudo systemctl start meshtastic-dashboard
sudo systemctl status meshtastic-dashboard

7. Configure Nginx

Create /etc/nginx/sites-available/meshtastic-dashboard:

server {
    listen 80;
    server_name your-domain.com;

    # Redirect to HTTPS
    return 301 https://$server_name$request_uri;
}

server {
    listen 443 ssl http2;
    server_name your-domain.com;

    ssl_certificate /etc/letsencrypt/live/your-domain.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/your-domain.com/privkey.pem;
    ssl_protocols TLSv1.2 TLSv1.3;
    ssl_ciphers HIGH:!aNULL:!MD5;

    location / {
        proxy_pass http://localhost:3000;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection 'upgrade';
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_cache_bypass $http_upgrade;
    }
}

Enable site:

sudo ln -s /etc/nginx/sites-available/meshtastic-dashboard /etc/nginx/sites-enabled/
sudo nginx -t
sudo systemctl reload nginx

8. Set Up SSL with Let's Encrypt

sudo apt-get install certbot python3-certbot-nginx
sudo certbot --nginx -d your-domain.com

Option 2: Docker Deployment

Create Dockerfile:

FROM node:18-alpine

WORKDIR /app

COPY package*.json ./
RUN npm ci --production

COPY . .

RUN mkdir -p data logs

EXPOSE 3000

CMD ["node", "src/server.js"]

Create docker-compose.yml:

version: '3.8'

services:
  meshtastic-dashboard:
    build: .
    ports:
      - "3000:3000"
    volumes:
      - ./data:/app/data
      - ./logs:/app/logs
      - ./.env:/app/.env:ro
    restart: unless-stopped
    environment:
      - NODE_ENV=production

Deploy:

docker-compose up -d

Option 3: Cloud Platforms

Heroku

1. Create Procfile:

web: node src/server.js

2. Deploy:

heroku create your-app-name
heroku config:set SESSION_SECRET=your-secret-here
git push heroku main

DigitalOcean App Platform

1. Connect your repository
2. Set environment variables in the dashboard
3. Deploy with one click

AWS EC2

Follow "Traditional Server" steps above on an EC2 instance.

Security Hardening

1. Firewall Configuration

# UFW (Ubuntu)
sudo ufw allow 22/tcp
sudo ufw allow 80/tcp
sudo ufw allow 443/tcp
sudo ufw enable

2. Environment Variables

Never commit .env file. Use secure methods to transfer:

# On server
touch .env
chmod 600 .env
nano .env  # Add your configuration

3. Database Permissions

chmod 700 data/
chmod 600 data/meshtastic.db

4. Regular Updates

# Update system packages
sudo apt update && sudo apt upgrade -y

# Update Node.js dependencies
npm audit fix
npm update

5. Monitoring

Install monitoring tools:

# PM2 for process management
npm install -g pm2
pm2 start src/server.js --name meshtastic-dashboard
pm2 startup
pm2 save

Backup Strategy

Automated Backup Script

Create /opt/backup-meshtastic.sh:

#!/bin/bash
BACKUP_DIR="/opt/backups/meshtastic"
DATE=$(date +%Y%m%d_%H%M%S)

mkdir -p $BACKUP_DIR

# Backup database
cp /opt/meshtastic-dashboard/data/meshtastic.db $BACKUP_DIR/db_$DATE.db

# Backup configuration
cp /opt/meshtastic-dashboard/.env $BACKUP_DIR/env_$DATE.txt

# Keep only last 7 days
find $BACKUP_DIR -name "db_*.db" -mtime +7 -delete
find $BACKUP_DIR -name "env_*.txt" -mtime +7 -delete

echo "Backup completed: $DATE"

Add to crontab:

chmod +x /opt/backup-meshtastic.sh
crontab -e
# Add: 0 3 * * * /opt/backup-meshtastic.sh

Monitoring and Logs

View Logs

# Systemd logs
sudo journalctl -u meshtastic-dashboard -f

# Application logs
tail -f /opt/meshtastic-dashboard/logs/combined.log
tail -f /opt/meshtastic-dashboard/logs/error.log

Log Rotation

Create /etc/logrotate.d/meshtastic-dashboard:

/opt/meshtastic-dashboard/logs/*.log {
    daily
    rotate 14
    compress
    delaycompress
    notifempty
    missingok
    copytruncate
}

Performance Optimization

1. Enable Node.js Clustering

For multi-core servers, modify src/server.js to use the cluster module.

2. Database Optimization

# Vacuum database periodically
sqlite3 data/meshtastic.db "VACUUM;"

3. Nginx Caching

Add to nginx configuration:

location /css/ {
    expires 1y;
    add_header Cache-Control "public, immutable";
}

location /js/ {
    expires 1y;
    add_header Cache-Control "public, immutable";
}

Troubleshooting

Application Won't Start

1. Check logs: sudo journalctl -u meshtastic-dashboard -n 50
2. Verify Node.js version: node --version
3. Check port availability: sudo netstat -tlnp | grep 3000
4. Verify permissions on data directory

MQTT Connection Issues

1. Check broker is accessible: telnet mqtt.meshtastic.org 1883
2. Verify credentials in .env
3. Check firewall rules

Database Errors

1. Check disk space: df -h
2. Verify database permissions: ls -la data/
3. Try rebuilding: rm data/meshtastic.db && npm start

Scaling Considerations

For high traffic deployments:

1. Load Balancing: Use multiple instances behind nginx
2. Database: Consider PostgreSQL for better concurrency
3. Caching: Add Redis for session storage
4. CDN: Use CloudFlare for static assets
5. Monitoring: Add Prometheus + Grafana

Maintenance

Weekly Tasks

• Review error logs
• Check disk space
• Verify backups

Monthly Tasks

• Update dependencies
• Review security advisories
• Optimize database
• Rotate API keys if used

Quarterly Tasks

• Review access logs
• Update SSL certificates (if not using auto-renewal)
• Performance audit
• Security audit

Support

For deployment issues:

1. Check logs first
2. Review documentation
3. Check GitHub issues
4. Contact maintainers

---

Last Updated: 2025 Maintainer: Meshtastic Community