Hi Aya
I managed to get it working thanks!
@Maki99
I asked ChatGPT to make a guided based on what I did, this might not be 100% accurate, but it a good guide which might help you:
Getting Started with Custom Nodes in n8n Using Docker
n8n is a powerful workflow automation tool that allows you to create automation between different services and APIs. Sometimes, n8n’s built-in nodes might not cover all your needs, and that’s where custom nodes come into play. Custom nodes allow you to extend n8n’s capabilities by writing your own functionality. In this guide, we will cover how to set up a custom node for n8n and run it using Docker.
Table of Contents
- Prerequisites
- Project Setup
- Creating the Custom Node
- Docker Setup
- Running n8n with Your Custom Node
- Using Your Custom Node in n8n
- Conclusion
- Additional Resources
Prerequisites
Before you begin, ensure you have the following installed on your machine:
- Node.js and npm: For developing and building the custom node.
- TypeScript: As custom nodes are written in TypeScript.
- Docker and Docker Compose: For running n8n in a containerized environment.
- Basic Knowledge of JavaScript/TypeScript and Docker: Understanding of these technologies will help you follow along.
Project Setup
- Create a Project Directory: Start by creating a new directory for your project.
mkdir n8n-custom-node
cd n8n-custom-node
Creating the Custom Node
1. Initialize the Node Project
We’ll create a new Node.js project for our custom node.
mkdir custom-nodes
cd custom-nodes
npm init -y
This will create a package.json file in the custom-nodes directory.
2. Create the Node Files
Create the following files in the custom-nodes directory:
MyCustomNode.node.ts: The main TypeScript file for your custom node.tsconfig.json: TypeScript configuration file.index.ts: Entry point to export your node.
touch MyCustomNode.node.ts tsconfig.json index.ts
3. Write the Node Code
tsconfig.json
Configure the TypeScript compiler options.
{
"compilerOptions": {
"module": "CommonJS",
"target": "ES2019",
"lib": ["es2019"],
"outDir": "./dist",
"rootDir": "./",
"strict": true,
"esModuleInterop": true
},
"include": ["MyCustomNode.node.ts"],
"exclude": ["node_modules"]
}
package.json
Add the necessary dependencies and scripts.
{
"name": "my-custom-node",
"version": "1.0.0",
"description": "A custom node for n8n",
"main": "dist/index.js",
"scripts": {
"build": "tsc"
},
"devDependencies": {
"@types/node": "^14.14.37",
"n8n-workflow": "^0.128.0",
"typescript": "^4.2.4"
},
"dependencies": {}
}
Install the dependencies:
npm install
MyCustomNode.node.ts
Write a simple custom node that, for example, reverses a string input.
import { IExecuteFunctions } from 'n8n-core';
import { INodeType, INodeTypeDescription } from 'n8n-workflow';
export class MyCustomNode implements INodeType {
description: INodeTypeDescription = {
displayName: 'My Custom Node',
name: 'myCustomNode',
group: ['transform'],
version: 1,
description: 'A custom node that reverses a string',
defaults: {
name: 'My Custom Node',
color: '#1F8EB2',
},
inputs: ['main'],
outputs: ['main'],
properties: [
{
displayName: 'String to Reverse',
name: 'stringToReverse',
type: 'string',
default: '',
placeholder: 'Enter a string',
description: 'The string to reverse',
},
],
};
async execute(this: IExecuteFunctions) {
const items = this.getInputData();
const returnData = [];
const stringToReverse = this.getNodeParameter('stringToReverse', 0) as string;
const reversedString = stringToReverse.split('').reverse().join('');
returnData.push({ json: { reversedString } });
return this.prepareOutputData(returnData);
}
}
index.ts
Export your custom node.
import { INodeType } from 'n8n-workflow';
import { MyCustomNode } from './MyCustomNode.node';
export const nodeTypes: INodeType[] = [
new MyCustomNode(),
];
4. Compile the TypeScript Code
Run the build script to compile your TypeScript code into JavaScript.
npm run build
This will generate a dist directory containing the compiled JavaScript files.
Docker Setup
To run n8n with your custom node, we’ll set up a Docker environment.
1. Create a Dockerfile
In the root of your project (n8n-custom-node), create a Dockerfile.
touch Dockerfile
Add the following content:
FROM n8nio/n8n:latest
USER root
# Copy the custom nodes folder
COPY ./custom_nodes /home/node/.n8n/custom/node_modules/custom_nodes
# Switch back to the node user
USER node
# Set the working directory
WORKDIR /home/node
# Use the default entrypoint and CMD from the base image
2. Create a Docker Compose File
Create a docker-compose.yml file in the root directory.
touch docker-compose.yml
Add the following content, using environment variables similar to those from your example setup:
volumes:
n8n_storage:
postgres_storage:
networks:
n8n-local:
services:
postgres:
image: postgres:latest
networks: ['n8n-local']
restart: unless-stopped
ports:
- 5432:5432
environment:
- POSTGRES_USER
- POSTGRES_PASSWORD
- POSTGRES_DB
volumes:
- postgres_storage:/var/lib/postgresql/data
healthcheck:
test: ['CMD-SHELL', 'pg_isready -h localhost -U ${POSTGRES_USER} -d ${POSTGRES_DB}']
interval: 5s
timeout: 5s
retries: 10
n8n:
build:
context: .
dockerfile: Dockerfile
image: n8nio/n8n:latest
networks: ['n8n-local']
container_name: n8n
restart: unless-stopped
ports:
- 5678:5678
environment:
- DB_TYPE=postgresdb
- DB_POSTGRESDB_HOST=postgres
- DB_POSTGRESDB_USER=${POSTGRES_USER}
- DB_POSTGRESDB_PASSWORD=${POSTGRES_PASSWORD}
- N8N_ENCRYPTION_KEY=${N8N_ENCRYPTION_KEY}
- N8N_AI_OPENAI_API_KEY=${N8N_AI_OPENAI_API_KEY}
- N8N_AI_OPENAI_MODEL=gpt-4o-2024-08-06
- N8N_HOST=${N8N_HOST}
- NODE_FUNCTION_ALLOW_BUILTIN=*
- NODE_FUNCTION_ALLOW_EXTERNAL=*
- N8N_COMMUNITY_PACKAGES_ENABLED=true
- N8N_CUSTOM_EXTENSIONS=/home/node/.n8n/custom/node_modules/custom_nodes
links:
- postgres
volumes:
- n8n_storage:/home/node/.n8n
- ./custom_nodes:/home/node/.n8n/custom/node_modules/custom_nodes
depends_on:
postgres:
condition: service_healthy
Running n8n with Your Custom Node
-
Create a .env File: In the root of your project, create a .env file to store your environment variables.
POSTGRES_USER=your_postgres_user
POSTGRES_PASSWORD=your_postgres_password
N8N_ENCRYPTION_KEY=your_encryption_key
N8N_AI_OPENAI_API_KEY=your_openai_api_key
N8N_HOST=your_n8n_host
-
Build the Docker Image
In your project root, run:
docker-compose build
This will build the Docker image, including your custom node.
-
Run the Docker Container
docker-compose up -d
This will start the n8n service in detached mode.
-
Verify the Container is Running
docker-compose ps
You should see the n8n service listed and running.
-
Check n8n Logs (optional):
docker-compose logs -f n8n
This can help you verify that n8n started correctly and that your custom node was loaded.
Using Your Custom Node in n8n
-
Access n8n
Open your web browser and navigate to http://localhost:5678.
-
Create a New Workflow
Click on “New Workflow” in the top-right corner.
-
Add Your Custom Node
- Click on the “+” button to add a new node.
- Search for “My Custom Node”.
- Add it to your workflow.
-
Configure the Node
- String to Reverse: Enter any string you wish to reverse.
-
Execute the Workflow
- Click on “Execute Workflow” to run the workflow.
- After execution, click on the node to see the output.
- You should see the reversed string in the output.
Conclusion
Congratulations! You’ve successfully created a custom node for n8n, set up a Docker environment, and integrated your custom node into n8n using Docker Compose. This guide provides a foundation for you to develop more complex custom nodes tailored to your specific needs.
Additional Resources
Tips and Best Practices
- Node Development: When developing custom nodes, it’s helpful to refer to the n8n source code and existing nodes for examples.
- Testing: Regularly test your node during development to catch any issues early.
- Version Control: Use Git or another version control system to manage your code changes.
- Documentation: Comment your code and provide clear descriptions in your node’s
description object to make it easier to use and maintain.
By following this guide, you should now have the skills to create and integrate custom nodes into n8n using Docker. This setup is ideal for development and testing purposes. For production environments, consider additional security measures and optimizations.
If you have any questions or run into issues, the n8n community is a great place to seek help and share your experiences.
Happy automating