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**
```bash
curl -fsSL https://deb.nodesource.com/setup_18.x | sudo -E bash -
sudo apt-get install -y nodejs
```

2. **Clone/Upload Application**
```bash
cd /opt
sudo mkdir meshtastic-dashboard
sudo chown $USER:$USER meshtastic-dashboard
cd meshtastic-dashboard
# Upload your files here
```

3. **Install Dependencies**
```bash
npm ci --production
```

4. **Configure Environment**
```bash
cp .env.example .env
nano .env  # Edit configuration
```

5. **Create User**
```bash
npm run create-user
```

6. **Set Up Systemd Service**

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

```ini
[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:
```bash
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`:

```nginx
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:
```bash
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**
```bash
sudo apt-get install certbot python3-certbot-nginx
sudo certbot --nginx -d your-domain.com
```

### Option 2: Docker Deployment

Create `Dockerfile`:

```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`:

```yaml
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:
```bash
docker-compose up -d
```

### Option 3: Cloud Platforms

#### Heroku

1. Create `Procfile`:
```
web: node src/server.js
```

2. Deploy:
```bash
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

```bash
# 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:
```bash
# On server
touch .env
chmod 600 .env
nano .env  # Add your configuration
```

### 3. Database Permissions

```bash
chmod 700 data/
chmod 600 data/meshtastic.db
```

### 4. Regular Updates

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

# Update Node.js dependencies
npm audit fix
npm update
```

### 5. Monitoring

Install monitoring tools:
```bash
# 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`:

```bash
#!/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:
```bash
chmod +x /opt/backup-meshtastic.sh
crontab -e
# Add: 0 3 * * * /opt/backup-meshtastic.sh
```

## Monitoring and Logs

### View Logs

```bash
# 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

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

### 3. Nginx Caching

Add to nginx configuration:
```nginx
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