n8n-nodes-pers

A custom n8n community node for the PERS (Phygital Experience Rewards System) API, with Docker deployment support.

📋 Table of Contents

• Quick Start
• Installation
• Project Structure
• Configuration
• Security
• Development
• Troubleshooting
• Resources

🚀 Quick Start

Prerequisites

• Docker (20.10+)
• Docker Compose (2.0+)

Docker Deployment

1. Clone the repository

   git clone https://github.com/guest-pizel/n8n-nodes-pers.git
   cd n8n-nodes-pers
   

2. Create your environment file

   cp .env.example .env
   

3. Edit .env with your configuration (see Configuration)

4. Build and start the container

   docker compose up -d --build
   

5. Access n8n at http://localhost:5678

📦 Installation

As a Community Node (npm)

Follow the n8n community nodes installation guide:

1. Go to Settings > Community Nodes
2. Select Install
3. Enter n8n-nodes-pers
4. Select Install

Manual Installation

npm install n8n-nodes-pers

📁 Project Structure

n8n-nodes-pers/
├── .github/workflows/      # CI/CD configuration
├── credentials/            # Credential definitions
│   ├── PersApi.credentials.ts
│   ├── pers.svg
│   └── pers.dark.svg
├── nodes/                  # Node implementations
│   └── Pers/
├── local-files/            # Mounted volume for file operations (Docker)
├── docker-compose.yaml     # Docker Compose configuration
├── Dockerfile              # Custom n8n image with PERS nodes
├── docker-entrypoint.sh    # Entrypoint script for custom node installation
├── .env.example            # Example environment variables
├── .dockerignore           # Docker build exclusions
├── package.json            # Node package configuration
├── tsconfig.json           # TypeScript configuration
└── LICENSE                 # MIT License

⚙️ Configuration

Environment Variables

Copy .env.example to .env and configure:

Variable	Description	Default
N8N_VERSION	n8n Docker image version	2.0.2
N8N_HOST	Host address	localhost
N8N_PORT	Port number	5678
N8N_PROTOCOL	Protocol (http/https)	http
WEBHOOK_URL	External webhook URL	http://localhost:5678/
GENERIC_TIMEZONE	Timezone	Europe/Madrid
N8N_LOG_LEVEL	Logging level	info

PERS API Credentials

When using the PERS node in n8n, you'll need to configure:

• Project Key: Your PERS project key
• Tenant API Key: Your PERS tenant API key

These are configured within n8n's credential system, not in environment variables.

Optional Settings

See .env.example for additional configurations:

• Basic authentication
• Database settings (PostgreSQL for production)
• SMTP for email notifications
• Encryption key for credentials

🔒 Security

Important Security Practices

1. Never commit .env files - The .gitignore excludes these automatically.

2. Use environment variables for all sensitive data:

   • Passwords
   • Database credentials
   • Encryption keys

3. Set an encryption key in production:

   # Generate a random encryption key
   openssl rand -hex 32
   

   Add to your .env:

   N8N_ENCRYPTION_KEY=your_generated_key
   

4. Enable basic auth for exposed instances:

   N8N_BASIC_AUTH_ACTIVE=true
   N8N_BASIC_AUTH_USER=your_username
   N8N_BASIC_AUTH_PASSWORD=your_secure_password
   

5. Use HTTPS in production with a reverse proxy (nginx, Traefik, etc.)

Files That Should Never Be Committed

• .env (contains secrets)
• local-files/ contents (may contain user data)
• Any files with API keys or passwords

🛠️ Development

Building the Custom Node

npm install
npm run build

Linting

npm run lint
npm run lint:fix

Rebuilding the Docker Image

After making changes:

docker compose down
docker compose up -d --build

Viewing Logs

docker compose logs -f n8n

Accessing the Container

docker compose exec n8n sh

🔧 Troubleshooting

Custom nodes not appearing

1. Check the container logs:

   docker compose logs n8n | grep -i custom
   

2. Verify nodes are installed:

   docker compose exec n8n ls -la /home/node/.n8n/custom/
   

Permission issues

The entrypoint script handles permissions automatically. If issues persist:

docker compose down -v  # Warning: This removes data volumes
docker compose up -d --build

Port conflicts

If port 5678 is in use, change N8N_PORT in your .env file.

Build failures

Ensure you have the latest base image:

docker compose build --no-cache

📚 Resources

• n8n Documentation
• n8n Community Nodes Guide
• PERS API Documentation
• PERS Website

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

👤 Author

Luis Jimenez - guest@explorins.com