n8n Deployment (Provisioning Flow)
Last updated: 2026-08-06
This document describes how an n8n runtime is provisioned on the HostAgentics platform: the service layout, storage, secrets, domain, health verification, and workflow import. It is an internal engineering document; customer-facing claims must stay within what this flow actually delivers.
1. Prerequisites
n8n provisioning is only possible when the license gate is open (`N8N_COMMERCIAL_LICENSE_CONFIRMED=true` **and** the `n8n_provisioning` feature flag enabled — see `docs/n8n-license-gate.md`) and the organization's payment state allows provisioning. The n8n adapter (`runtime-n8n`) drives the flow below.
2. Service layout: n8n plus a dedicated database
An n8n runtime is **two dedicated services**, never a shared database:
1. **Dedicated PostgreSQL service** (`pg-<subdomain>`, `postgres:16-alpine`) with its own persistent volume at `/var/lib/postgresql/data`. The database user, database name, and a generated `db-password` are set as its environment. Every n8n runtime gets its own database; databases are never shared between customers.
2. **The n8n service** (`n8n-<subdomain>`) from the pinned official image (`n8nio/n8n:2.33.4` at the tested default, digest-pinned via the version catalog), with its own persistent volume at `/home/node/.n8n`.
Both services live in the runtime's shard project and region; storage and compute for a runtime stay within its region.
3. Secrets: generated, encrypted, per runtime
Provisioning generates, per runtime:
Both are stored in the runtime's encrypted secret scope (`encrypted_secrets`, AES-256-GCM envelopes; see `docs/secret-rotation.md`) and injected into the service environment only at configure/deploy time. They are never logged. The n8n connection variables (`DB_TYPE=postgresdb`, host/port/database/user/password) are built from the secret scope, and the editor/webhook base URL is set to the runtime's branded HTTPS domain.
4. Domain and HTTPS
The runtime is assigned a branded domain `<subdomain>.runtime.hostagentics.com`. The provider assigns the domain, DNS records are confirmed (wildcard `*.runtime.hostagentics.com` managed via Cloudflare), and certificate status is polled until `active` before the runtime is presented as ready. `N8N_EDITOR_BASE_URL` and `WEBHOOK_URL` are set to `https://<domain>/` so workflows and webhooks resolve correctly.
5. Health verification
Readiness is gated on a real health probe: `GET https://<domain>/healthz` must return OK before the provisioning state machine moves past `checking_health`. The same probe feeds ongoing monitoring (consecutive failures → degraded → automatic restart with backoff; see `docs/monitoring.md`).
6. Concurrency and privacy hardening
7. Workflow import (migration center)
Customers migrating an existing n8n setup upload their workflow exports through the migration center (`migration_imports`, contentType `workflow_json`). Payloads are validated at upload time (name, nodes, connections structure; issues are recorded, never silently dropped), stored, and applied to the runtime only on explicit user action via the n8n API using an n8n API key scoped to that runtime. Imports are never executed blindly and never applied to a runtime the user does not own.