iTechGuides is reader-supported. When you buy through links on our site, we may earn an affiliate commission. As an Amazon Associate I earn from qualifying purchases. Learn more
Run n8n and a small Node.js API as separate services in one Docker Compose project: n8n manages workflows, while the API supplies custom HTTP behavior those workflows can call. This tutorial keeps the editor on your host machine, leaves the API private to the Compose network, and saves n8n state in a named volume so workflows survive container replacement.
What this local stack does
Docker Compose starts and connects the services. n8n coordinates workflow steps, and the Node.js service provides a small custom HTTP endpoint. In this implementation, your browser reaches n8n at http://localhost:5678; the API has no host-published port and is called by n8n over the Compose network.
That is a local development arrangement, not an internet-facing webhook deployment. You do not need a public domain to open n8n locally or to let n8n call the private API. If external services must send webhooks to n8n, use a separate deployment path with a public URL, reverse proxy, TLS, and appropriate firewall controls.
Prerequisites and project files
Install Docker Engine and Docker Compose v2, which n8n lists for its hand-built Compose setup. The documentation’s recommendation of 4 GB RAM and 2 vCPUs applies to its included sandbox stack, not a universal minimum for every simpler local installation. See the n8n Docker Compose installation guide.
#1 Best Overall
- Includes Raspberry Pi 5 with 2.4Ghz 64-bit quad-core CPU (8GB RAM)
- Includes 128GB Micro SD Card pre-loaded with 64-bit Raspberry Pi OS, USB MicroSD Card Reader
- CanaKit Turbine Black Case for the Raspberry Pi 5
- CanaKit Low Noise Bearing System Fan
- Mega Heat Sink - Black Anodized
Create a project directory with these files:
local-automation/
├── compose.yaml
├── .env
├── .gitignore
└── api/
├── Dockerfile
└── server.jsThe API will accept JSON containing a non-empty message string and return it in a JSON response. The endpoint is intentionally small; do not treat it as a production API for sensitive actions without adding authentication and any other controls the action requires.
Create the Node.js API
In api/server.js, create a server using Node.js’s built-in node:http module. It listens on all container interfaces so another service on the Compose network can reach it. It rejects unsupported methods and paths, malformed JSON, and invalid fields with useful status codes.
const http = require('node:http');
const server = http.createServer((req, res) => {
const send = (status, body) => {
res.writeHead(status, { 'content-type': 'application/json; charset=utf-8' });
res.end(JSON.stringify(body));
};
if (req.method !== 'POST' || req.url !== '/echo') {
return send(404, { error: 'Not found' });
}
let body = '';
req.on('data', (chunk) => {
body += chunk;
if (body.length > 100_000) {
send(413, { error: 'Request body too large' });
req.destroy();
}
});
req.on('end', () => {
let data;
try {
data = JSON.parse(body);
} catch {
return send(400, { error: 'Request body must be valid JSON' });
}
if (!data || typeof data.message !== 'string' || !data.message.trim()) {
return send(422, { error: 'message must be a non-empty string' });
}
return send(200, { received: data.message.trim() });
});
});
server.listen(3000, '0.0.0.0');Node’s http module provides the low-level server and HTTP message handling; route design, validation, authentication, and application error behavior are choices implemented by this example. See the Node.js introduction.
Rank #2
- Includes Raspberry Pi 5 16GB with 2.4Ghz 64-bit quad-core CPU (16GB RAM)
- Includes 128GB Micro SD Card pre-loaded with 64-bit Raspberry Pi OS, USB MicroSD Card Reader
- CanaKit Turbine Black Case for the Raspberry Pi 5
- CanaKit Low Noise Bearing System Fan
- Mega Heat Sink - Black Anodized
In api/Dockerfile, use the official Node image and start the server:
FROM node:22-alpine
WORKDIR /app
COPY server.js ./server.js
EXPOSE 3000
CMD ["node", "server.js"]Configure Compose, persistence, and secrets
Create compose.yaml with a named volume mounted at n8n’s data directory. Only n8n publishes a port to the host; the API remains reachable only to services on the Compose network.
services:
n8n:
image: docker.n8n.io/n8nio/n8n
ports:
- "127.0.0.1:5678:5678"
environment:
- N8N_ENCRYPTION_KEY=${N8N_ENCRYPTION_KEY}
- N8N_BLOCK_ENV_ACCESS_IN_NODE=true
- N8N_RESTRICT_FILE_ACCESS_TO=/home/node/.n8n
volumes:
- n8n_data:/home/node/.n8n
depends_on:
- api
api:
build: ./api
expose:
- "3000"
volumes:
n8n_data:Binding the published n8n port to 127.0.0.1 limits host access to the local machine. The API’s expose declaration documents its container port; it does not publish that port on the host. Compose services can address one another by service name on their shared network, so n8n should call http://api:3000, not localhost (which would refer to the n8n container itself). This service-name routing is described in Docker’s Compose networking documentation.
Rank #3
- CanaKit Raspberry Pi 5 Essentials Starter Kit
Generate a long random encryption key and put it in .env, which Compose reads for the interpolation above:
Recommended Free Tools
N8N_ENCRYPTION_KEY=replace-with-a-long-random-secretDo not commit this file. Add the following to .gitignore:
.envThe example uses an environment file for local development convenience. Treat it as a secret: restrict access to it and keep it out of source control and shared logs. n8n supports _FILE variants for selected settings, including sensitive credential and database configuration; confirm that the particular variable you plan to load from a file supports that form in the n8n environment variables reference.
Rank #4
- All-in-One Complete Kit: This SANOOV RPi 5 bundle comes with Raspberry Pi 5 4GB RAM single board, active cooler, durable ABS case and screwdriver. No extra parts needed, ready to use right out of the box for beginners and hobbyists
- Powerful Single Board Computer: Equipped with 4GB RAM and high-performance processor, delivers fast running speed for 4K playback, AI projects, programming and daily computing tasks. SANOOV for raspberry pi 5 4GB is equipped with broadcom 64 quad-core Arm Cortex A76 processor with gigabit ethernet and upgraded with IEEE 802.11ac Wi-Fi, Bluetooth 5.0 dual-band 2.4Ghz and 5Ghz and Power Over Ethernet (POE). Upgrading delivers 2-3 x speed vs Pi 4, redefining the experience
- Efficient Active Cooler: Effectively lowers operating temperature and prevents performance throttling. Runs quietly even under long-time heavy load, ensures stable operation all day long. SANOOV RPi 5 4GB kit offer an active cooler, which combines an aluminium heatsink with a high-performance PWM fan. Active cooler is fully compatible with the Pi OS, which can effectively reduce the temperature of RPi5 and ensure its good performance during long-term high load operation
- Sturdy ABS Protective Case: Well-fitted for Raspberry Pi 5 board, can be secured with 4 screws to effectively protect the Pi 5 motherboard from damage, reserves full access to all ports and buttons. SANOOV uses ABS material to produce the case, which has a softer texture and feel. Meanwhile, SANOOV case adopts a layered design for easy disassembly and installation. (Tip: The Case cannot install M.2 HAT Add on Board and Solid State Drive!)
- Wide Application & Full Compatibility: Seamlessly compatible with official OS and mainstream peripheral accessories for Raspberry Pi 5. Whether you are a beginner, student, electronics hobbyist or professional developer, this all-in-one kit meets your diverse needs. It excels in IoT projects, robotics design, retro gaming devices, home media servers and other DIY creations. Backed by a large global community, you can easily find guides, technical support and shared projects online
Set the security variables to suit your workflows. N8N_BLOCK_ENV_ACCESS_IN_NODE=true limits access to environment variables from expressions and Code nodes; N8N_RESTRICT_FILE_ACCESS_TO limits n8n file access to the stated path. These controls do not replace authentication, network restrictions, secure secret storage, or updates. Review the n8n security documentation and run its security audit when checking an instance.
Start the services and call the API from n8n
- From the project directory, start the stack in the background:
docker compose up -d --build - Open
http://localhost:5678in a browser and complete n8n’s initial setup. - In a workflow, add an HTTP Request node. Set the method to
POST, the URL tohttp://api:3000/echo, and the body format to JSON. Send an object such as{"message":"hello from n8n"}. - Execute the node. A successful call returns HTTP 200 and a JSON body such as
{"received":"hello from n8n"}. Invalid JSON returns 400, a missing or blank message returns 422, an unsupported route or method returns 404, and a body over the example’s limit returns 413.
Inspect service output if startup or a request fails:
docker compose logs -f n8n apiAfter editing the API code, rebuild and restart it with docker compose up -d --build api. Stop the services with docker compose down; this removes the containers but keeps the named data volume. To delete that persistent volume as well, use docker compose down -v—that permanently removes the stored n8n data.
Best Value
- 【What you Get】You will get 1*Pi 5 8GB Single Board,1*RasTech Case,1*Active Cooler,1*Screwdriver,1*Installation instructions,12-month free warranty, lifetime service, 24-hour prompt and friendly response.
- 【More Connectors】There are two USB 3.0 ports(5Gbps simultaneously) and two USB 2.0 ports, which triple total bandwidth ,support any combination of up to two cameras or displays. Peak SD card performance is doubled through support for the SDR104 high-speed mode. It provides a smooth desktop experience for you. Offer Gigabit Ethernet and a PCIe interface, along with dual-band Wi-Fi and Bluetooth 5.0/BLE wireless capability. The RasTech Pi 5 Kit use the new 27W 5.1V 5A USB-C power connector.
- 【 Support Dual 4Kp60 Display 】Each of the two microHDMI sockets can control a 4K display at 60 Hertz, now support HDR, offering super HD video for media streaming projects. RPi 5 is the first RPi model that comes with a PCI Express port (PCIe 2.0 x1 with 500 MB/s) to attach SSDs (requires separate M.2 HAT).
- 【 Excellent Chips And Applications】Pi 5 is a full-size Pi computer using silicon built in-house at Pi. The RP1 “southbridge” provides the bulk of the I/O capabilities for Pi 5. Pi 5 is more friendly and convenient in the development of Internet of Things, Web development, machine identification, automatic control and other electronic equipment applications and network.
- 【 Faster CPU, Better GPU 】 Pi 5 features a Broadcom BCM2712 64-bit quad-core Arm Cortex-A76 processor running at 2.4GHz, it delivers a 2–3× increase in CPU performance relative to RaspberryPi 4. The 800MHz VideoCore VII GPU is compatible to OpenGL ES 3.1 and Vulkan 1.2, substantial uplift in graphics performance. Pi 5 Offers lightning-fast CPU speed, a PCI Express interface, a Real Time Clock (RTC) and a power button and runs significantly cooler than Pi 4.
Keep workflows safe across restarts
The named volume at /home/node/.n8n stores n8n’s persistent state. Without that mount, replacing the container can discard data held only in its writable container layer. Back up the volume on a schedule that fits the importance of your workflows, and protect the backup along with the encryption key. Restoring data without the corresponding key can make encrypted credentials unusable. n8n’s documented Compose example also shows a separate bind mount from ./local-files to /files when workflows need to share files with the host; this tutorial does not need that mount. See the official Compose example.
When to use a public webhook deployment
For a private local stack, the loopback-bound editor port and private API are sufficient. A service outside your machine cannot reach the local editor through that binding, and the API is not published on the host.
For external webhooks, treat exposure as a separate deployment decision: configure a domain and reverse proxy, enable TLS, set the public webhook URL and host/protocol settings to match the proxy, and apply firewall and access controls. n8n’s Compose example uses WEBHOOK_URL and host/protocol settings in a domain-and-proxy scenario; adapt those settings to the actual topology rather than copying them into a local-only setup.
The Tool Desk
Outbyte Driver Updater FREEFix the driver behind crashes, sound loss and screen glitchesFind Drivers →Outbyte PC Repair FREERepair Windows errors before they cause bigger problemsFix Now →Quick Recap
Common problems
- n8n cannot reach the API: use
http://api:3000/echofrom the n8n container, confirm both services are in this Compose project, and checkdocker compose logs api. Do not substitutelocalhost. - Workflows disappear after recreating containers: confirm
n8n_data:/home/node/.n8nis present and that you did not remove the volume withdocker compose down -v. - The host cannot reach the API: that is intentional in this configuration. If local host-side testing is needed, publish a port bound to
127.0.0.1and avoid exposing it broadly. - A remote service cannot deliver a webhook: this local-only setup has no public URL or proxy configuration. Configure those elements and TLS for a separate externally reachable deployment.
Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.
