n8n setup — a beginner's guide

For the AI Customer Service Agent — Starter (v1.1.4). You do not need to be technical to finish this page. The same guide ships inside your product download as docs/N8N_SETUP.md.

What is n8n, and why do I need it?

Your CocciFlows agent needs somewhere to run — a small always-on program that receives a question from your website, asks OpenAI for an answer, and sends the reply back. That program is n8n (say "n-eight-n"), a well-known independent automation platform. Think of it as the engine of your agent.

All you actually need from n8n:

You paste 2 and 3 into the wizard's Connect your n8n step. That's the whole job.

Note: CocciFlows does not host n8n and does not sell you n8n or a server. You choose and own your n8n; your agent, your data, and your keys stay with you.

Which option should I choose?

Not sure? Choose n8n Cloud. It is the fastest route to a working agent, and n8n keeps the server running and secure for you. Choose a VPS if you specifically want to host things yourself. Choose your Windows PC only to try the product out — a chatbot on a real public website cannot reach software running on your own PC (see §2).

Option 1 · n8n Cloud (easiest)

With n8n Cloud, n8n runs the server for you. Nothing to install, no server to administer, no security updates to apply, and the secure web address (HTTPS) is set up for you.

1. Go to n8n.io/cloud and create an account.
2. When your workspace is ready you get an address like https://something.app.n8n.cloud. Open it — you should see the n8n screen. That is your n8n address.
3. Create your API key — see Your API key.
4. In the wizard's Connect your n8n step, paste the address and the key, then press Connect.

CocciFlows has no affiliation with n8n and earns nothing from your plan. Pricing and plans are n8n's; any current plan with API access works.

Option 2 · Your Windows PC with Docker Desktop (testing)

Use this for trying the product, demos, learning, and building your knowledge base before going live. Do not use it for a live website: your PC must stay switched on and awake, and the address you get only works on that one computer.

What is Docker Desktop? Software that runs other programs in a tidy, self-contained box on your PC. It's how you run n8n on Windows without installing lots of separate pieces. It's free for personal and small-business use.

1. Install Docker Desktop from docker.com. If the installer offers to use WSL 2, say yes (it sets it up for you). Restart if asked.
2. Start Docker Desktop from the Start menu and wait until it says Engine running. Leave it running.
3. Open PowerShell: press Start, type PowerShell, open Windows PowerShell. Paste each command below and press Enter.
4. Create storage for your n8n data:

   docker volume create n8n_data

   Do not skip this. Without it, your n8n account, settings, and installed agent are erased every time the program restarts.
5. Start n8n:

   docker run -d --name n8n -p 5678:5678 -v n8n_data:/home/node/.n8n docker.n8n.io/n8nio/n8n

   In plain English: start n8n in the background, call it n8n, make it available on this PC at port 5678, and keep its data in the storage area you just created. The first run downloads n8n and can take a few minutes.
6. Open n8n in your browser at http://localhost:5678. "localhost" means this computer — it is not a website on the internet, it's a shortcut your PC uses to talk to itself.
7. Create the n8n owner account (email + password) when n8n asks. These are your n8n login details — nothing to do with CocciFlows.
8. Create the API key (below) and enter http://localhost:5678 plus the key in the wizard. Plain http is accepted here precisely because it never leaves your computer.

Because your data lives in n8n_data, stopping, updating, or recreating the container does not lose anything.

Option 3 · A VPS (recommended for self-hosting)

A VPS is a small computer running in a data center. Unlike your laptop, it stays online 24 hours a day, has a permanent public address, and doesn't mind being left alone. You rent it by the month.

You can use any hosting provider you like — CocciFlows does not supply, resell, or recommend a specific one, and nothing in this product ties you to a particular company.

Example starter specification (a guide, not a guarantee — real capacity depends on your traffic, your other workloads, and your provider): Ubuntu LTS · 1–2 CPU cores · 2 GB RAM · 20 GB+ storage · a public IP address.

1. Create the server. In your provider's control panel, create a server running Ubuntu LTS. The provider normally gives you a public IP address, a login username (often root), and a password and/or SSH key. Keep these safe — they are the keys to your server.
2. Connect to the server. On Windows open PowerShell and run, with your own IP:

   ssh root@YOUR_SERVER_IP

   ssh opens a secure remote connection, so what you type runs on the server instead of your PC. The first time it asks whether to trust the server — type yes. Then enter your password (nothing appears on screen while you type — that's normal). The prompt changes to something like root@your-server:~#.
3. Update Ubuntu:

   apt update && apt upgrade -y

   This fetches the latest security updates. It prints a lot of text — expected.
4. Install Docker. Docker publishes an official one-line installer:

   curl -fsSL https://get.docker.com -o get-docker.sh
   sh get-docker.sh

   Check it worked with docker --version. This convenience script is published and maintained by Docker and is the quickest path on a fresh Ubuntu server; Docker's own documentation notes it is not intended for production-critical environments. If your organisation requires the package-manager installation instead, follow docs.docker.com and continue at the next step.
5. Create storage for your n8n data:

   docker volume create n8n_data

   This keeps your n8n account, settings, and installed agent safe across restarts and updates. Do not skip it.
6. Start n8n:

   docker run -d --name n8n --restart unless-stopped -p 5678:5678 -v n8n_data:/home/node/.n8n docker.n8n.io/n8nio/n8n

   --restart unless-stopped means n8n comes back automatically if the server reboots.
7. Check that it is running:

   docker ps

   What you should see: one line for a container named n8n, a status like Up 30 seconds, and ports showing 5678. An empty list means n8n is not running — docker logs n8n shows why. You can now open http://YOUR_SERVER_IP:5678 and create your n8n owner account.

Make your n8n publicly available with HTTPS

For the VPS option only. n8n Cloud already handles this; local Windows testing does not need it.

Production-ready means three things:

1. A domain or subdomain you own, e.g. n8n.your-domain.com, pointed at your server's IP with a DNS "A record" (done wherever your domain is managed).
2. HTTPS — an encryption certificate so the address starts with https://. Free certificates are standard (Let's Encrypt).
3. A reverse proxy or secure tunnel — a small piece of software in front of n8n that terminates HTTPS and passes requests through.

Common, well-documented approaches (choose one; each has its own guide): Caddy, which obtains and renews certificates automatically and is usually the least work; Traefik or Nginx + Certbot, the traditional combinations; or Cloudflare Tunnel, which publishes your server without opening ports.

Whichever you choose, two practical points matter for your agent:

• Only the proxy should be exposed. Once a proxy is in front, restart n8n bound to the machine itself — replace -p 5678:5678 with -p 127.0.0.1:5678:5678 — so the internet reaches n8n only through the proxy.
• Tell n8n its public address. n8n builds your webhook URL from its own configuration; behind a proxy it must know the public name, or the webhook address shown in the wizard will be wrong. n8n's hosting documentation covers the environment variables for this (N8N_HOST, N8N_PROTOCOL, WEBHOOK_URL).

Authoritative instructions live with the projects themselves — n8n's hosting documentation is at docs.n8n.io/hosting and is kept current in a way a product manual cannot be. Follow it for the exact, up-to-date commands.

Your n8n API key (all three options)

The same last step whichever option you chose.

1. Open your n8n in a browser and log in.
2. Go to Settings (usually under your account menu, bottom-left).
3. Open n8n API. (In older versions this entry is labelled simply API.)
4. Click Create an API key.
5. n8n shows the key once — copy it now. If you lose it, delete it and create another.

Then, in the setup wizard's Connect your n8n step:

• n8n address — e.g. https://n8n.your-domain.com, https://yourname.app.n8n.cloud, or http://localhost:5678 for local testing. The same address you type in your browser, with no extra path on the end.
• n8n API key — the key you just copied.

Press Connect. The wizard checks:

A green ✓ Connected to n8n means you're ready for the next step. Two messages are normal rather than failures:

• "could not determine the n8n version…" — some n8n setups don't publish their version number. Setup can't confirm it, so it tells you honestly instead of guessing; just make sure you're on n8n 1.60 or newer.
• "…uses plain http to a non-local host — use https in production" — shown when your address is http:// and not on your own computer. Fine while testing; fix it before going live (above).

What your n8n API key is used for

In plain English: the API key is how the setup wizard does the work in n8n on your behalf, so you never have to. It is used for installation and maintenance operations:

• installing your agent workflow into your n8n
• creating credentials in n8n where your n8n supports it (your OpenAI key, and your SMTP details when you use the guided email setup)
• activating the workflow
• running the health checks
• updating or re-installing when you change your knowledge later
• uninstalling — removing the workflow and the credentials it created

The normal running of your agent does not use the n8n API key. Once installed, a customer's question goes to your workflow's webhook address in your n8n, which calls your OpenAI account and replies. The API key is not part of that conversation path.

How the key is handled: the setup wizard runs on your own computer at http://127.0.0.1:7378, an address only your computer can reach. Your n8n API key is kept in the wizard's memory for that session only and is not written to its saved settings file — close the wizard and you re-enter it next time, deliberately. It is sent only to your own n8n, never to CocciFlows, which operates no server in this path. Anything the widget puts in your website's page is public by design and contains only your agent's webhook address and appearance settings — no keys of any kind.

You can revoke the key in n8n at any time (Settings → n8n API). If you do, the agent keeps working; you'll simply need a new key the next time you run the setup wizard. No one from CocciFlows will ever ask you for your API keys.

Quick fixes

More symptoms: the troubleshooting section of the main documentation, and docs/TROUBLESHOOTING.md in your package.

← Back to all documentation