n8n is the home automation workflow engine. It runs as a Docker service on a Raspberry Pi host and is the primary integration layer between Home Assistant, external APIs, and other home services.
The service stack is three containers: n8n, postgres (workflow and
credential storage), and n8n-runners (isolated execution environment).
First-time bootstrap
A fresh deployment requires a few manual steps in the n8n UI before the API is accessible. After that, subsequent operations are fully automated.
Step 1 — Initial provision
./provision-service.sh --env <dev|prod> --host <host> --service n8nThe post-deploy hook runs but skips credential import gracefully — no API key exists yet.
Step 2 — First-time UI setup
Navigate to the n8n UI (port 5678) and:
- Create the admin account — credentials are in 1Password
Labvault, item “n8n local owner account (created on n8n.iot)” (username, password, first/last name) - Enter the activation key — field “License activation key” in the same item
Step 3 — Create an API key
Settings → API → Create API key. Copy the key.
Step 4 — Store the API key in 1Password
In the env vault (devLab or prodLab), open item service.n8n and add:
| Field | Value |
|---|---|
env.N8N_API_KEY | the key from Step 3 |
The env. prefix is picked up automatically by gen-env.sh and written to
.env on the host at next deploy.
Step 5 — Re-run provision
./provision-service.sh --env <dev|prod> --host <host> --service n8npost-deploy.sh now finds the API key in .env and imports all credentials
from 1Password. Bootstrap is complete.
Updating credentials
Re-run provision-service.sh whenever:
- Adding a new credential — create the
n8n.*item in the appropriate 1Password vault, then re-run to import it - Rotating a credential value — update the field value in 1Password, then re-run to push the update to n8n
- Restoring after data loss — a fresh n8n install has an empty credential store; re-running reimports everything from 1Password automatically
1Password item reference
Credential items (n8n.* in Lab vault)
One item per n8n credential. Shared credentials go in Lab; credentials that
differ between environments go in devLab or prodLab (env-specific items
override Lab items of the same name).
| Field | Location | Purpose |
|---|---|---|
credential_type | top-level | n8n internal type string (e.g. githubApi) |
credential_name | top-level | display name in n8n UI; defaults to the part after n8n. in the item title |
| data fields | section named data | credential key/value pairs sent to n8n |
Values in the data section are strings in 1Password but are automatically
coerced to booleans (true/false) or numbers before being sent to the n8n
API.
Current credentials
| 1Password item | credential_type | Notes |
|---|---|---|
n8n.github | githubApi | GitHub personal access token |
n8n.homeassistant | homeAssistantApi | Host URL + long-lived access token |
n8n.unifi | httpBearerTokenAuth | UniFi bearer token |
Service item (service.n8n in env vault)
Holds fields consumed by gen-env.sh to generate the service .env file.
The env. prefix is stripped to produce the environment variable name.
| Field | Env var | Purpose |
|---|---|---|
env.N8N_API_KEY | N8N_API_KEY | n8n REST API key for credential import |