Node-RED Complete Provisioning Guide¶
Overview¶
This guide covers the complete Ansible workflow for provisioning Raspberry Pi devices with Node-RED and the gaisro-technika-nodered Git project.
After provisioning, each device will have:
- ✅ Node-RED installed (pinned version 4.1.3)
- ✅ Projects feature enabled in UI
- ✅ gaisro-technika-nodered repository cloned
- ✅ All npm dependencies installed (from package.json)
- ✅ MQTT certificates deployed (for mTLS connection)
- ✅ Encryption key for credentials (auto-decrypts flows_cred.json)
- ✅ Git user configured for commits
- ✅ Environment variables set (MQTT, device ID, etc.)
Quick Start¶
# 1. Provision a single device (local network)
task ansible:provision-nodered DEVICE=rpi-staging-001
# 2. Provision via Cloudflare Tunnel (remote)
task ansible:provision-nodered DEVICE=rpi-staging-001 TUNNEL=true
# 3. Force git update (reset local changes)
task ansible:provision-nodered DEVICE=rpi-001 FORCE=true
Prerequisites¶
Before provisioning a new device, ensure:
1. SSH Keys Deployed¶
# Generate device SSH keys (if not exists)
task provision:generate-ssh-keys DEVICE=rpi-001
# Deploy SSH keys to device
task provision:single DEVICE=rpi-001 IP=192.168.1.xxx
2. MQTT Certificates Generated¶
# Generate MQTT client certificates
task mqtt:generate-cert DEVICE=rpi-001
# Verify certificates exist
ls config/rpi-001/mqtt/
# Should show: client.crt, client.key
3. GitHub Deploy Key Added¶
The device needs SSH key added as deploy key to gaisro-technika-nodered repository:
1. Copy device public key: cat config/rpi-001/ssh/id_rsa.pub
2. Go to: https://github.com/mbTagai/gaisro-technika-nodered/settings/keys
3. Add new deploy key with read access
Provisioning Commands¶
Single Device¶
# Local network (faster)
task ansible:provision-nodered DEVICE=rpi-001
# Via Cloudflare Tunnel (works remotely)
task ansible:provision-nodered DEVICE=rpi-001 TUNNEL=true
Environment Groups¶
# All staging devices
task ansible:provision-nodered-staging
# All production devices (requires confirmation)
task ansible:provision-nodered-prod
Update Project Only¶
# Pull latest changes without full reprovisioning
task ansible:update-nodered-project DEVICE=rpi-001
# Update to specific branch
task ansible:update-nodered-project DEVICE=rpi-001 VERSION=develop
What Gets Deployed¶
Directory Structure on Device¶
/home/tagai/.node-red/
├── settings.js # Node-RED settings (from infra repo)
├── environment # Environment variables
├── .config.projects.json # Active project registration
├── .config.users.json # Git user config
├── mqtt/ # MQTT certificates
│ ├── ca.crt # CA certificate
│ ├── client.crt # Device client certificate
│ └── client.key # Device private key
└── projects/
└── gaisro-technika-nodered/ # Your Git project
├── .git/ # Git repo
├── .encryptionKey # Credentials encryption key
├── flows.json # Your flows
├── flows_cred.json # Encrypted credentials
├── package.json # Node dependencies
└── node_modules/ # Installed modules
Environment Variables¶
The environment file contains:
DEVICE_ID=rpi-001
NODE_RED_PORT=1880
NODE_RED_ENABLE_PROJECTS=true
NODE_RED_CREDENTIAL_SECRET=tagaitechteam # For credential decryption
# MQTT Configuration
MQTT_BROKER=mqtts.tagai.xyz
MQTT_PORT=8883
MQTT_DEVICE_ID=rpi-001
MQTT_CERT_PATH=/home/tagai/.node-red/mqtt/client.crt
MQTT_KEY_PATH=/home/tagai/.node-red/mqtt/client.key
MQTT_CA_PATH=/home/tagai/.node-red/mqtt/ca.crt
Credentials Handling¶
Encryption Key¶
The encryption key tagaitechteam is used to:
1. Decrypt flows_cred.json in the project
2. Encrypt new credentials you add in Node-RED UI
CRITICAL: This key MUST be identical across all devices!
How Credentials Work¶
- Credentials (MQTT passwords, API keys) are stored encrypted in
flows_cred.json - The
.encryptionKeyfile contains the decryption key - Ansible deploys both the project AND the encryption key
- Node-RED automatically decrypts credentials on startup
Adding New Credentials¶
- Open Node-RED editor
- Configure a node (e.g., MQTT node credentials)
- Deploy the flow
- Commit and push via Projects UI
- The encrypted
flows_cred.jsonis stored in Git
Troubleshooting¶
Credentials Won't Decrypt¶
# SSH to device
task ssh DEVICE=rpi-001
# Check encryption key exists
cat ~/.node-red/projects/gaisro-technika-nodered/.encryptionKey
# Should output: tagaitechteam
# If missing or wrong, redeploy:
exit
task ansible:provision-nodered DEVICE=rpi-001 FORCE=true
Project Not Loading¶
# Check active project config
task ansible:shell DEVICE=rpi-001 CMD="cat ~/.node-red/.config.projects.json"
# Should show:
# {"activeProject":"gaisro-technika-nodered",...}
# Restart Node-RED
task ansible:shell DEVICE=rpi-001 CMD="sudo systemctl restart nodered"
Git Clone Fails¶
# Test SSH auth from device
task ansible:shell DEVICE=rpi-001 CMD="ssh -T git@github.com"
# Expected output:
# Hi mbTagai! You've successfully authenticated...
# If fails, check deploy key is added to repo
Dependencies Not Installed¶
# SSH to device and install manually
task ssh DEVICE=rpi-001
cd ~/.node-red/projects/gaisro-technika-nodered
npm install
sudo systemctl restart nodered
Configuration Files¶
Role Defaults¶
ansible/roles/node_red/defaults/main.yml
Group Variables¶
ansible/group_vars/all/nodered.yml
Playbook¶
ansible/playbooks/provision-nodered-complete.yml
Tasks¶
ansible/roles/node_red/tasks/projects.yml
Email Configuration (Optional)¶
To enable email nodes in flows, add to your vault:
node_red_email_enabled: true
node_red_email_server: "smtp.gmail.com"
node_red_email_port: 587
node_red_email_secure: false
node_red_email_user: "your-email@gmail.com"
node_red_email_password: "your-app-password"
These will be passed via environment variables to Node-RED.
Workflow Summary¶
┌─────────────────────────────────────────────────────────────┐
│ PROVISIONING FLOW │
├─────────────────────────────────────────────────────────────┤
│ 1. Run: task ansible:provision-nodered DEVICE=rpi-001 │
│ ↓ │
│ 2. Ansible connects to device │
│ ↓ │
│ 3. Installs/updates Node-RED │
│ ↓ │
│ 4. Creates directories (.node-red/projects) │
│ ↓ │
│ 5. Clones gaisro-technika-nodered repo │
│ ↓ │
│ 6. Deploys encryption key (.encryptionKey) │
│ ↓ │
│ 7. Runs npm install (package.json) │
│ ↓ │
│ 8. Deploys MQTT certificates │
│ ↓ │
│ 9. Creates environment file │
│ ↓ │
│ 10. Registers project as active │
│ ↓ │
│ 11. Restarts Node-RED │
│ ↓ │
│ 12. Health check (waits for HTTP 200) │
│ ↓ │
│ ✅ DONE - Device ready with flows + credentials │
└─────────────────────────────────────────────────────────────┘