Skip to content

Node-RED Projects Feature Setup

Problem: Projects Feature Not Showing in UI

The Node-RED Projects feature was not appearing in the UI because of a fundamental conflict between two deployment approaches:

Conflicting Approaches

  1. Ansible Git Deployment (was enabled):
  2. Clones Git repository directly into ~/.node-red/
  3. Manages the entire directory as a Git repo

  4. Controlled by node_red_project_enabled: true in ansible

  5. Node-RED Projects UI (what we want):

  6. Node-RED manages Git repos in ~/.node-red/projects/<project-name>
  7. Users create/clone projects via the UI
  8. Enabled by editorTheme.projects.enabled: true in settings.js

These two approaches cannot coexist! When ~/.node-red is already a Git repository, Node-RED's Projects UI won't work properly.

Solution

1. Configuration Changes Made

a) Settings.js - Enable Projects Feature

Added to node-red/settings.js: 

editorTheme: {
  projects: {
    enabled: true,
    workflow: {
      mode: "auto"
    }
  }
}

b) Environment Variable - Enable Projects

Added to ansible/roles/node_red/templates/nodered-env.j2: 

NODE_RED_ENABLE_PROJECTS=true

c) Disable Ansible Git Deployment

Changed in ansible/roles/node_red/defaults/main.yml: 

node_red_project_enabled: false  # Was: true

2. Deploy the Changes

# Deploy to a test device first
task deploy-device DEVICE=rpi-dev-001 PLAYBOOK=provision.yml

# Or update just Node-RED config
ansible-playbook ansible/playbooks/provision.yml -i ansible/inventory/production/hosts.yml --limit rpi-dev-001 --tags node_red

3. Clean Up Existing Git Repository (if needed)

If a device already has ~/.node-red as a Git repo, you'll need to clean it up:

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

# On the device:
cd ~/.node-red

# Remove git repository (keep the files)
rm -rf .git

# Remove git-related files
rm -f .gitignore .gitattributes

# Restart Node-RED
sudo systemctl restart nodered

4. Using Node-RED Projects UI

Once deployed and cleaned up, access the Node-RED editor:

  1. Open: https://rpi-dev-001-nodered.tagai.uk
  2. You should see a welcome screen to create your first project
  3. Click "Create a project" and follow the wizard:
  4. Set your Git username and email
  5. Name your project (e.g., "gaisro-technika-flows")
  6. Choose to create new or clone existing repository
  7. Set encryption key for credentials file

Clone Your Existing Repository

To use your existing gaisro-technika-nodered repository:

  1. In Projects UI, select "Clone Repository"
  2. Use SSH URL: ssh://git@github.com/mbTagai/gaisro-technika-nodered
  3. Note: GitHub SSH URLs need ssh:// prefix for Node-RED
  4. Select your SSH key: /home/pi/.ssh/id_rsa
  5. The project will be cloned to ~/.node-red/projects/gaisro-technika-nodered

Requirements

The Projects feature needs these tools (already installed by ansible): - ✅ git - version control - ✅ ssh-keygen - SSH key management - ✅ SSH keys configured (~/.ssh/id_rsa)

Features You Get

With Projects enabled:

  • 📦 Version Control - Git integration built into the UI
  • 🔄 Commit & Push - Manage changes via the editor
  • 🌿 Branch Management - Switch branches, create new ones
  • 📜 History View - See commit log and diffs
  • 🔐 Credential Encryption - Secure your credentials with a key
  • 📚 Dependencies - Manage package.json via UI
  • 🚀 Multiple Projects - Switch between different projects

Deployment Workflows

Pros: - Users can manage flows via Git in the UI - No ansible deployment needed for flow updates - Full Git workflow (commit, branch, push/pull)

Cons: - Each device manages its own repository - Need to clone the project on each device - No centralized ansible-controlled deployment

Option B: Use Ansible Git Deployment

Pros: - Centralized control via ansible - One command deploys to all devices - Consistent versions across fleet

Cons: - Projects UI won't work - Users can't use Git features in the editor - Manual git operations only

Option C: Hybrid Approach

Use ansible to deploy base settings.js and certificates, but let users manage flows via Projects UI:

# In ansible/roles/node_red/defaults/main.yml
node_red_project_enabled: false  # Don't manage flows via ansible

# In ansible playbooks:
# - Deploy settings.js (with projects enabled)
# - Deploy MQTT certificates
# - Install dependencies
# - Users manage flows via Projects UI

Troubleshooting

Projects Menu Not Showing

  1. Check settings.js has editorTheme.projects.enabled: true
  2. Check environment has NODE_RED_ENABLE_PROJECTS=true
  3. Restart Node-RED: sudo systemctl restart nodered
  4. Clear browser cache and reload

"Not a Git Repository" Error

This happens if ~/.node-red is already a Git repo:

cd ~/.node-red
rm -rf .git
sudo systemctl restart nodered

Can't Clone Repository

Check SSH key authentication: 

ssh -T git@github.com
# Should say: "Hi mbTagai! You've successfully authenticated"

Projects Directory Structure

Correct structure when using Projects: 

~/.node-red/
├── settings.js          # Node-RED settings
├── package.json         # Base dependencies
├── environment          # Environment variables
├── mqtt/                # MQTT certificates
│   ├── ca.crt
│   ├── client.crt
│   └── client.key
└── projects/            # Projects managed by Node-RED
    └── gaisro-technika-nodered/  # Your project
        ├── .git/
        ├── flows.json
        ├── flows_cred.json
        ├── package.json
        └── README.md

Migration Strategy

For existing devices with ansible-managed Git deployment:

  1. Backup current flows: 

    task ssh DEVICE=rpi-001
cp ~/.node-red/flows.json ~/flows.json.backup

  2. Clean up Git repository: 

    cd ~/.node-red
rm -rf .git .gitignore

  3. Redeploy with new settings: 

    task deploy-device DEVICE=rpi-001 PLAYBOOK=provision.yml

  4. Create project in UI:

  5. Clone your repository via Projects UI

  6. Or copy flows manually to new project

  7. Verify:

  8. Check Projects menu appears
  9. Test Git operations in UI
  10. Confirm MQTT connectivity still works

References