Setting Up Node-RED Projects on New Device¶

Quick Setup¶

# 1. Deploy to new device with Projects enabled
task deploy DEVICE=rpi-staging-002

# 2. SSH to device and clean up any existing git repo (if needed)
task ssh DEVICE=rpi-staging-002
cd ~/.node-red && rm -rf .git .gitignore
exit

# 3. Access Node-RED editor
# Open: https://rpi-staging-002-nodered.tagai.uk

First-Time Project Setup in UI¶

Welcome Screen - You'll see a welcome screen to create your first project
Git Configuration
Username: Your name
Email: your.email@example.com
Clone Repository
Select: "Clone Repository"
Repository URL: ssh://git@github.com/mbTagai/gaisro-technika-nodered
SSH Key: Select /home/pi/.ssh/id_rsa
Encryption Key (CRITICAL!)
When prompted for credentials encryption
Enter: tagaitechteam
⚠️ This must be the same on all devices!
Project Name
Will be: gaisro-technika-nodered
Location: ~/.node-red/projects/gaisro-technika-nodered/

Fix Existing Device with Credentials Error¶

If you're seeing "credentials could not be decrypted":

# SSH to the device
task ssh DEVICE=rpi-staging-001

# Remove existing .node-red directory
sudo systemctl stop nodered
rm -rf ~/.node-red

# Exit and redeploy
exit
task deploy DEVICE=rpi-staging-001

# Now access the UI and follow setup steps above

How It Works¶

Directory Structure¶

~/.node-red/
├── settings.js              # Deployed by ansible
├── environment              # Deployed by ansible
├── mqtt/                    # MQTT certs (deployed by ansible)
│   ├── ca.crt
│   ├── client.crt
│   └── client.key
└── projects/                # Managed by Projects UI
    └── gaisro-technika-nodered/   # Your cloned project
        ├── .git/
        ├── flows.json       # Your flows
        ├── flows_cred.json  # Encrypted credentials
        ├── package.json
        └── .encryptionKey   # Stores encryption key

What Ansible Deploys¶

✅ Node-RED installation
✅ settings.js (with Projects enabled)
✅ MQTT certificates
✅ SSH keys for Git
✅ Environment variables
✅ Encryption key file (if configured)

What You Manage in UI¶

📦 Clone the repository
✏️ Edit flows
💾 Commit changes
🔄 Push/pull from Git
🌿 Branch management

Important Notes¶

Encryption Key¶

The key tagaitechteam is used for: - Encrypting flows_cred.json in the project - Must be identical on all devices - Stored in ~/.node-red/projects/gaisro-technika-nodered/.encryptionKey

If You Forget the Encryption Key¶

You'll need to re-enter credentials for all nodes: 1. Delete the project 2. Clone again 3. Use the correct key this time 4. Reconfigure all node credentials

SSH Key Authentication¶

Make sure GitHub deploy key is set up:

# Verify SSH auth works
task ssh DEVICE=rpi-staging-002
ssh -T git@github.com
# Should say: "Hi mbTagai! You've successfully authenticated"

Troubleshooting¶

# Check environment
task ssh DEVICE=rpi-staging-002
cat ~/.node-red/environment | grep PROJECTS
# Should show: NODE_RED_ENABLE_PROJECTS=true

# Check settings.js
grep -A5 "editorTheme" ~/.node-red/settings.js
# Should show: enabled: true

# Restart Node-RED
sudo systemctl restart nodered

Can't Clone Repository¶

# Test SSH key
ssh -T git@github.com

# Check if key is added to GitHub
# Go to: https://github.com/mbTagai/gaisro-technika-nodered/settings/keys

Credentials Still Won't Decrypt¶

The project might have been created with a different key. Fix:

cd ~/.node-red/projects/gaisro-technika-nodered
rm .encryptionKey
echo "tagaitechteam" > .encryptionKey
sudo systemctl restart nodered

Configuration Variables¶

In ansible/roles/node_red/defaults/main.yml:

node_red_projects_ui_enabled: true           # Enable Projects UI
node_red_project_encryption_key: "tagaitechteam"  # Encryption key
node_red_project_enabled: false              # Disable ansible git deployment