Vibecode n8n Cloud
track this build5 phases, 15 steps, beginner friendly0%YES · one-shottable
Because n8n itself is open source, the core cloud subscription can be replaced by self-hosting if you can own hosting, updates, and backups.
the project pack5 files · written for this build, step by step
You are building a lean indie version of n8n Cloud. Create the following project files first, then implement the application by following them. Keep the files updated as decisions change. Do not collapse this into a single README or prompt. ===== README.md ===== # n8n Cloud · indie build Build an owner-operated n8n workflow instance with persistent credentials and tested recovery. Estimated effort: **multi-day**. Work `BUILD_PLAN.md` top to bottom · every phase ends in a check that has to pass before the next one starts. ## Stack | Part | Choice | Why | | --- | --- | --- | | Application | Upstream n8n container | Reuse the maintained application; the work is deployment and operations. | | Storage | Persistent upstream SQLite pilot volume | Use the upstream schema and keep data across container replacement. | | Deployment | Docker Compose; Caddy for product HTTPS | Explicit volumes, ports and configuration can be reviewed and recreated. | ## Before you start Have every one of these ready. The plan assumes them from step one. - [ ] **Docker Engine and Compose v2** · Docker Engine has no hosting fee; Desktop licensing depends on your use, and a rented host is billed separately. - Why: The upstream application runs in containers. - Get it: Install Docker Engine and the Compose plugin on Linux using the official instructions. On Windows use Docker Desktop with WSL2, then work inside a Linux project folder. - Verify: docker compose version prints a v2 version and docker info reaches the daemon. - [ ] **Choose and record the upstream release** · Software/edition terms and optional paid features are defined by the upstream project. - Why: The guide must match the software you actually deploy. - Get it: Open https://docs.n8n.io/deploy/host-n8n/install-options/install-with-docker, choose a stable release compatible with its database requirements, record its tag and resolved digest in versions.txt, and use those values in compose.yaml. Avoid unattended latest-tag updates. - Verify: versions.txt names both application and database versions or states that the pilot uses embedded SQLite. - [ ] **n8n Cloud acceptance sample** · No paid service required for this local step. - Why: This fixture makes the first end-to-end check reproducible. - Get it: Create synthetic sample data before implementation: A Manual Trigger to Edit Fields workflow producing hello plus a Schedule Trigger proof using no external account. Save it under fixtures/ with the expected results in fixtures/README.md; use no real credentials or customer records. - Verify: The fixture files and expected outcomes exist and can be inspected without a vendor account. - [ ] **Confirm the bounded replacement** · No paid service required for this local step. - Why: The full commercial product is larger than this guide. - Get it: The deliverable is an owner-operated n8n workflow instance with persistent credentials and tested recovery. Read every exclusion below. Indie mode runs locally; any public or shared use requires the product access and deployment gates first. - Verify: You can name the primary workflow and the vendor features this version deliberately leaves out. ## Quick start ```sh docker compose config --quiet ``` Then copy `.env.example` to `.env` and fill in the values it documents. ## Honest limits This build deliberately does not replace: - Workflow JSON alone is not a backup of credentials or execution data; changing to PostgreSQL does not copy old SQLite data. - This is an owner-operated n8n workflow instance with persistent credentials and tested recovery; full n8n Cloud feature parity, vendor hosting and support are not included. - managed hosting - backups - scaling - email support - reduced ops burden - team/admin features If one of those is essential to you, that is the reason to keep paying for n8n Cloud, and the README should say so rather than pretend. ===== BRIEF.md ===== # Build brief · n8n Cloud The one-shot brief this plan expands. `BUILD_PLAN.md` (or `MILESTONES.md`) is the same sequence broken into steps and checks; where the two disagree, the plan wins. Build me an owner-operated n8n workflow instance with persistent credentials and tested recovery as a bounded replacement for n8n Cloud. Build it in phases in the order below. Do not write the whole product in one pass. Finish the current phase, run its Done when checks, fix failures, then continue. Indie mode completes Phases 1-5. Phase 6 is required before shared or public deployment. ### Stack (fixed, do not substitute) - Application: Upstream n8n container. Reuse the maintained application; the work is deployment and operations. - Storage: Persistent upstream SQLite pilot volume. Use the upstream schema and keep data across container replacement. - Deployment: Docker Compose; Caddy for product HTTPS. Explicit volumes, ports and configuration can be reviewed and recreated. ### Data model (create this before Phase 1) - Use the upstream n8n schema. For the local pilot retain the entire /home/node/.n8n volume, including its SQLite database and encryption material - keep workflow exports and pinned image digest. Product mode must rehearse the documented PostgreSQL migration/export path rather than simply changing database settings. - Use stable ids and explicit relationships; add auxiliary tables named by the phases before those phases use them. - Acceptance fixture: A Manual Trigger to Edit Fields workflow producing hello plus a Schedule Trigger proof using no external account. ### Prerequisites and configuration - Docker Engine and Compose v2: Install Docker Engine and the Compose plugin on Linux using the official instructions. On Windows use Docker Desktop with WSL2, then work inside a Linux project folder. Verify: docker compose version prints a v2 version and docker info reaches the daemon. Cost: Docker Engine has no hosting fee; Desktop licensing depends on your use, and a rented host is billed separately. - Choose and record the upstream release: Open https://docs.n8n.io/deploy/host-n8n/install-options/install-with-docker, choose a stable release compatible with its database requirements, record its tag and resolved digest in versions.txt, and use those values in compose.yaml. Avoid unattended latest-tag updates. Verify: versions.txt names both application and database versions or states that the pilot uses embedded SQLite. Cost: Software/edition terms and optional paid features are defined by the upstream project. - n8n Cloud acceptance sample: Create synthetic sample data before implementation: A Manual Trigger to Edit Fields workflow producing hello plus a Schedule Trigger proof using no external account. Save it under fixtures/ with the expected results in fixtures/README.md; use no real credentials or customer records. Verify: The fixture files and expected outcomes exist and can be inspected without a vendor account. Cost: No paid service required for this local step. - Confirm the bounded replacement: The deliverable is an owner-operated n8n workflow instance with persistent credentials and tested recovery. Read every exclusion below. Indie mode runs locally; any public or shared use requires the product access and deployment gates first. Verify: You can name the primary workflow and the vendor features this version deliberately leaves out. Cost: No paid service required for this local step. - Configuration: APP_IMAGE, SITE_URL, GENERIC_TIMEZONE, TZ. Ship .env.example, replace placeholders and exclude secrets from git. ### Phase 1 · Deployment inventory and safe pilot Build: Prepare the pinned upstream deployment for an owner-operated n8n workflow instance with persistent credentials and tested recovery. - Read the linked upstream installation guide and create compose.yaml, .env.example, versions.txt and OPERATIONS.md. Map APP_IMAGE and only each service's required environment variables explicitly. Keep database ports internal and map the pilot application port to 127.0.0.1. - Use the upstream n8n schema. For the local pilot retain the entire /home/node/.n8n volume, including its SQLite database and encryption material; keep workflow exports and pinned image digest. Product mode must rehearse the documented PostgreSQL migration/export path rather than simply changing database settings. Name each volume and its mount path in OPERATIONS.md; never use ephemeral container storage for the only copy. Create .env manually from .env.example and replace placeholders before starting. Commands, after creating the named files: `docker compose config --quiet`. - Create a private fixtures/ folder containing: A Manual Trigger to Edit Fields workflow producing hello plus a Schedule Trigger proof using no external account. Create a separate backup destination and an isolated restore-project name; do not reuse live volumes in restore exercises. - Trap: A valid Compose file proves configuration syntax only, not application health. Done when: docker compose config --quiet succeeds with no unresolved required variables. The documented volume list includes every persistent asset and no secret is committed. Do not build yet: Do not start persistent local instance until these checks pass. ### Phase 2 · Persistent local instance Build: Persistent local instance for n8n Cloud: Deploy the official n8n image using Compose with a persistent /home/node/.n8n mount and a loopback mapping for port 5678. - Deploy the official n8n image using Compose with a persistent /home/node/.n8n mount and a loopback mapping for port 5678. - Create the owner account and retain the generated encryption material with restricted backups; disable optional AI/cloud features for this pilot. - Use A Manual Trigger to Edit Fields workflow producing hello plus a Schedule Trigger proof using no external account. Check: Restarting the container retains the owner account and a saved workflow. Then check: The editor is unreachable through a non-loopback host interface. Record commands, observed results and the date in OPERATIONS.md. - Trap: Follow upstream settings for the selected release; do not copy deprecated task-runner flags from old examples. Done when: Restarting the container retains the owner account and a saved workflow. The editor is unreachable through a non-loopback host interface. Do not build yet: Do not start useful workflow proof until these checks pass. ### Phase 3 · Useful workflow proof Build: Useful workflow proof for n8n Cloud: Build the Manual Trigger and Edit Fields proof, inspect output, then add a Schedule Trigger with the intended timezone. - Build the Manual Trigger and Edit Fields proof, inspect output, then add a Schedule Trigger with the intended timezone. - Export the workflow JSON and record its expected output; keep credentials in the n8n credential store, never in exported node parameters. - Use A Manual Trigger to Edit Fields workflow producing hello plus a Schedule Trigger proof using no external account. Check: The manual workflow produces the exact hello field. Then check: The scheduled proof runs at the documented timezone and appears in execution history. Record commands, observed results and the date in OPERATIONS.md. - Trap: An enabled schedule is an actual side effect; test only a harmless local workflow. Done when: The manual workflow produces the exact hello field. The scheduled proof runs at the documented timezone and appears in execution history. Do not build yet: Do not start recovery and upgrade until these checks pass. ### Phase 4 · Recovery and upgrade Build: Recovery and upgrade for n8n Cloud: Stop the local SQLite instance for a consistent complete volume backup and store encryption material securely alongside it. - Stop the local SQLite instance for a consistent complete volume backup and store encryption material securely alongside it. - Restore into a new isolated volume with schedules disabled, import or inspect the proof workflow and test before selecting a new image. - Use A Manual Trigger to Edit Fields workflow producing hello plus a Schedule Trigger proof using no external account. Check: The restored proof workflow runs and any test credential remains decryptable. Then check: The backup manifest includes the encryption material, image version and restore date. Record commands, observed results and the date in OPERATIONS.md. - Trap: Workflow JSON alone is not a backup of credentials or execution data; changing to PostgreSQL does not copy old SQLite data. Done when: The restored proof workflow runs and any test credential remains decryptable. The backup manifest includes the encryption material, image version and restore date. Do not build yet: Do not start portable delivery and clean-start proof until these checks pass. ### Phase 5 · Portable delivery and clean-start proof Build: Finish the n8n Cloud replacement with a documented first-run path and a recoverable export. - Document prerequisites, every configuration variable, data locations and the three domain workflows: Persistent local instance; Useful workflow proof; Recovery and upgrade. Include the exclusions, actual costs and source check date 2026-09-05. Commands shown earlier that reference project files are files the builder must implement before running them. - Stop the pilot service and back up its complete persistent volume including SQLite and encryption material; retain versioned workflow exports as a secondary aid. Restore into a separate empty directory or isolated deployment, with all outbound actions and schedules disabled. Recreate this proof: A Manual Trigger to Edit Fields workflow producing hello plus a Schedule Trigger proof using no external account. Compare ids/counts and open the result before recording the restore date. Never test a restore over the only live copy. - Use a new folder and only README instructions to reach the fixture outcome. Verify upstream login, persistence, proof output and restore. Record exactly what passed; do not mark unrun checks complete. Commands, after creating the named files: `docker compose ps`. - Trap: Export without an import or restore rehearsal is not verified portability. Done when: A new folder reaches the documented fixture outcome using only README instructions. A backup restored in isolation preserves the proof data and can be opened. Do not build yet: Do not start operate and share with access controls until these checks pass. ### Phase 6 · Operate and share with access controls (product-builder only) Build: Product-builder only: make an owner-operated n8n workflow instance with persistent credentials and tested recovery operable for its stated audience before allowing remote access. - Use upstream authentication, replace default credentials, restrict the editor/admin surface and inventory public ingestion/webhook paths. Review upstream edition and license boundaries before offering this as a service. - Put Caddy HTTPS in front of the upstream app, keep database and management ports private and configure public URLs from the chosen domain. For n8n, rehearse upstream PostgreSQL migration/import and recovery before claiming production readiness; disable any unused AI sandbox services. - Add a scheduled encrypted off-host backup using this procedure: Stop the pilot service and back up its complete persistent volume including SQLite and encryption material; retain versioned workflow exports as a secondary aid. Monitor health, disk space, failed jobs and backup age. Stop the service to test an alert; rehearse recovery with outbound effects disabled and record recovery time. Rotate any exposed credentials and require reconciliation before resuming queues. - Trap: Product mode is additional engineering, not a switch that makes a local prototype production-ready. Done when: An unauthenticated visitor cannot read private records, download private files or mutate the admin surface. A viewer cannot mutate data by making a direct request, and guessed ids cannot cross ownership boundaries. Stopping the service triggers the configured alert and the latest off-host backup restores the fixture in isolation. Do not build yet: Do not add new providers or vendor-scale features until the release gates are recorded. ### Out of scope (and why) - Workflow JSON alone is not a backup of credentials or execution data; changing to PostgreSQL does not copy old SQLite data. - This is an owner-operated n8n workflow instance with persistent credentials and tested recovery; full n8n Cloud feature parity, vendor hosting and support are not included. - managed hosting: retain the paid product if this capability is essential; it is outside this bounded build. - backups: retain the paid product if this capability is essential; it is outside this bounded build. - scaling: retain the paid product if this capability is essential; it is outside this bounded build. - email support: retain the paid product if this capability is essential; it is outside this bounded build. - reduced ops burden: retain the paid product if this capability is essential; it is outside this bounded build. - team/admin features: retain the paid product if this capability is essential; it is outside this bounded build. ### README must contain - Exact install, configure, initialize, start, test and recovery commands for a clean folder. - The schema, fixture, acceptance results, private data locations and export format. - Every prerequisite and secret source, actual running costs and deliberately excluded capabilities. - An honest distinction between tests actually run and checks still awaiting real credentials or deployment. - Dependency documentation reviewed 2026-09-05: https://docs.n8n.io/deploy/host-n8n/install-options/install-with-docker ; https://docs.n8n.io/deploy/host-n8n/install-options/install-using-docker-compose. Recheck before upgrading; freeze the versions actually tested. ===== AGENTS.md ===== # Agent instructions · n8n Cloud indie build - Read `README.md` and `BUILD_PLAN.md` before writing code. The stack is fixed: Upstream n8n container, Persistent upstream SQLite pilot volume, Docker Compose; Caddy for product HTTPS. Do not substitute. - Work one phase at a time, in order. Do not start a phase until every "Done when" item of the previous one passes. - Prefer the fewest moving parts that satisfy the step. No frameworks, services or dependencies the plan does not name. - Secrets live in `.env`, never in source or logs. Keep `.env.example` current when a variable is introduced. - Do not invent cryptography, security guarantees, APIs or compliance claims. - Add a focused test for every destructive, security-sensitive or data-loss path the plan names. - Run the project checks before declaring a phase complete, and record any deliberate shortcut in the README under "Tradeoffs". ## Known traps - A valid Compose file proves configuration syntax only, not application health. - Follow upstream settings for the selected release; do not copy deprecated task-runner flags from old examples. - An enabled schedule is an actual side effect; test only a harmless local workflow. - Workflow JSON alone is not a backup of credentials or execution data; changing to PostgreSQL does not copy old SQLite data. - Export without an import or restore rehearsal is not verified portability. ===== BUILD_PLAN.md ===== # Build plan · n8n Cloud Build an owner-operated n8n workflow instance with persistent credentials and tested recovery. Phases are in dependency order. Each ends in a "Done when" list; treat an unticked item as a blocker, not a note. ## Phase 1 · Deployment inventory and safe pilot Prepare the pinned upstream deployment for an owner-operated n8n workflow instance with persistent credentials and tested recovery. ### Steps 1. Create the deployment files Read the linked upstream installation guide and create compose.yaml, .env.example, versions.txt and OPERATIONS.md. Map APP_IMAGE and only each service's required environment variables explicitly. Keep database ports internal and map the pilot application port to 127.0.0.1. Files: `compose.yaml`, `.env.example`, `versions.txt` 2. Identify every persistent asset Use the upstream n8n schema. For the local pilot retain the entire /home/node/.n8n volume, including its SQLite database and encryption material; keep workflow exports and pinned image digest. Product mode must rehearse the documented PostgreSQL migration/export path rather than simply changing database settings. Name each volume and its mount path in OPERATIONS.md; never use ephemeral container storage for the only copy. Create .env manually from .env.example and replace placeholders before starting. Files: `OPERATIONS.md`, `.gitignore` ```sh docker compose config --quiet ``` 3. Prepare the proof and recovery folder Create a private fixtures/ folder containing: A Manual Trigger to Edit Fields workflow producing hello plus a Schedule Trigger proof using no external account. Create a separate backup destination and an isolated restore-project name; do not reuse live volumes in restore exercises. Files: `fixtures/README.md`, `OPERATIONS.md` ### Done when - [ ] docker compose config --quiet succeeds with no unresolved required variables. - [ ] The documented volume list includes every persistent asset and no secret is committed. ### Watch out - A valid Compose file proves configuration syntax only, not application health. ## Phase 2 · Persistent local instance Persistent local instance for n8n Cloud: Deploy the official n8n image using Compose with a persistent /home/node/.n8n mount and a loopback mapping for port 5678. ### Steps 1. Deploy the official n8n image using Compose with a persistent /home/node/.n8n mount and a loopback mapping for port 5678. Deploy the official n8n image using Compose with a persistent /home/node/.n8n mount and a loopback mapping for port 5678. Files: `compose.yaml`, `OPERATIONS.md` 2. Create the owner account and retain the generated encryption material with restricted backups; disable optional AI/cloud features for this pilot. Create the owner account and retain the generated encryption material with restricted backups; disable optional AI/cloud features for this pilot. Files: `OPERATIONS.md` 3. Exercise the acceptance fixture Use A Manual Trigger to Edit Fields workflow producing hello plus a Schedule Trigger proof using no external account. Check: Restarting the container retains the owner account and a saved workflow. Then check: The editor is unreachable through a non-loopback host interface. Record commands, observed results and the date in OPERATIONS.md. Files: `OPERATIONS.md` ### Done when - [ ] Restarting the container retains the owner account and a saved workflow. - [ ] The editor is unreachable through a non-loopback host interface. ### Watch out - Follow upstream settings for the selected release; do not copy deprecated task-runner flags from old examples. ## Phase 3 · Useful workflow proof Useful workflow proof for n8n Cloud: Build the Manual Trigger and Edit Fields proof, inspect output, then add a Schedule Trigger with the intended timezone. ### Steps 1. Build the Manual Trigger and Edit Fields proof, inspect output, then add a Schedule Trigger with the intended timezone. Build the Manual Trigger and Edit Fields proof, inspect output, then add a Schedule Trigger with the intended timezone. Files: `compose.yaml`, `OPERATIONS.md` 2. Export the workflow JSON and record its expected output; keep credentials in the n8n credential store, never in exported node parameters. Export the workflow JSON and record its expected output; keep credentials in the n8n credential store, never in exported node parameters. Files: `OPERATIONS.md` 3. Exercise the acceptance fixture Use A Manual Trigger to Edit Fields workflow producing hello plus a Schedule Trigger proof using no external account. Check: The manual workflow produces the exact hello field. Then check: The scheduled proof runs at the documented timezone and appears in execution history. Record commands, observed results and the date in OPERATIONS.md. Files: `OPERATIONS.md` ### Done when - [ ] The manual workflow produces the exact hello field. - [ ] The scheduled proof runs at the documented timezone and appears in execution history. ### Watch out - An enabled schedule is an actual side effect; test only a harmless local workflow. ## Phase 4 · Recovery and upgrade Recovery and upgrade for n8n Cloud: Stop the local SQLite instance for a consistent complete volume backup and store encryption material securely alongside it. ### Steps 1. Stop the local SQLite instance for a consistent complete volume backup and store encryption material securely alongside it. Stop the local SQLite instance for a consistent complete volume backup and store encryption material securely alongside it. Files: `compose.yaml`, `OPERATIONS.md` 2. Restore into a new isolated volume with schedules disabled, import or inspect the proof workflow and test before selecting a new image. Restore into a new isolated volume with schedules disabled, import or inspect the proof workflow and test before selecting a new image. Files: `OPERATIONS.md` 3. Exercise the acceptance fixture Use A Manual Trigger to Edit Fields workflow producing hello plus a Schedule Trigger proof using no external account. Check: The restored proof workflow runs and any test credential remains decryptable. Then check: The backup manifest includes the encryption material, image version and restore date. Record commands, observed results and the date in OPERATIONS.md. Files: `OPERATIONS.md` ### Done when - [ ] The restored proof workflow runs and any test credential remains decryptable. - [ ] The backup manifest includes the encryption material, image version and restore date. ### Watch out - Workflow JSON alone is not a backup of credentials or execution data; changing to PostgreSQL does not copy old SQLite data. ## Phase 5 · Portable delivery and clean-start proof Finish the n8n Cloud replacement with a documented first-run path and a recoverable export. ### Steps 1. Write the user-facing runbook Document prerequisites, every configuration variable, data locations and the three domain workflows: Persistent local instance; Useful workflow proof; Recovery and upgrade. Include the exclusions, actual costs and source check date 2026-09-05. Commands shown earlier that reference project files are files the builder must implement before running them. Files: `README.md`, `.env.example` 2. Create and rehearse a recoverable backup Stop the pilot service and back up its complete persistent volume including SQLite and encryption material; retain versioned workflow exports as a secondary aid. Restore into a separate empty directory or isolated deployment, with all outbound actions and schedules disabled. Recreate this proof: A Manual Trigger to Edit Fields workflow producing hello plus a Schedule Trigger proof using no external account. Compare ids/counts and open the result before recording the restore date. Never test a restore over the only live copy. Files: `OPERATIONS.md`, `backup/README.md` 3. Reproduce the first-run experience Use a new folder and only README instructions to reach the fixture outcome. Verify upstream login, persistence, proof output and restore. Record exactly what passed; do not mark unrun checks complete. Files: `README.md`, `verification.md` ```sh docker compose ps ``` ### Done when - [ ] A new folder reaches the documented fixture outcome using only README instructions. - [ ] A backup restored in isolation preserves the proof data and can be opened. ### Watch out - Export without an import or restore rehearsal is not verified portability. ## Not in this build - Workflow JSON alone is not a backup of credentials or execution data; changing to PostgreSQL does not copy old SQLite data. - This is an owner-operated n8n workflow instance with persistent credentials and tested recovery; full n8n Cloud feature parity, vendor hosting and support are not included. - managed hosting - backups - scaling - email support - reduced ops burden - team/admin features ## After v1, if you want it - Extend recovery and upgrade only after the fixture and recovery checks pass. - Before adding another integration, document its credentials, limits, cost and failure behavior with primary-source links. ===== .env.example ===== # Copy to .env and fill in. Never commit .env; this file documents it. # Required. Copy the exact application image reference selected from upstream into compose.yaml via this variable. APP_IMAGE=replace-with-tested-image-and-digest # Required. The loopback URL selected in compose.yaml; replace with your HTTPS origin only after completing product deployment. SITE_URL=http://localhost:5678 # Required. Set the intended workflow timezone in the n8n service; record it beside the schedule proof. GENERIC_TIMEZONE=UTC # Required. Container system timezone; keep it consistent with the intended pilot timezone. TZ=UTC
You are building a lean indie version of n8n Cloud. Create the following project files first, then implement the application by following them. Keep the files updated as decisions change. Do not collapse this into a single README or prompt. ===== README.md ===== # n8n Cloud · indie build Build an owner-operated n8n workflow instance with persistent credentials and tested recovery. Estimated effort: **multi-day**. Work `BUILD_PLAN.md` top to bottom · every phase ends in a check that has to pass before the next one starts. ## Stack | Part | Choice | Why | | --- | --- | --- | | Application | Upstream n8n container | Reuse the maintained application; the work is deployment and operations. | | Storage | Persistent upstream SQLite pilot volume | Use the upstream schema and keep data across container replacement. | | Deployment | Docker Compose; Caddy for product HTTPS | Explicit volumes, ports and configuration can be reviewed and recreated. | ## Before you start Have every one of these ready. The plan assumes them from step one. - [ ] **Docker Engine and Compose v2** · Docker Engine has no hosting fee; Desktop licensing depends on your use, and a rented host is billed separately. - Why: The upstream application runs in containers. - Get it: Install Docker Engine and the Compose plugin on Linux using the official instructions. On Windows use Docker Desktop with WSL2, then work inside a Linux project folder. - Verify: docker compose version prints a v2 version and docker info reaches the daemon. - [ ] **Choose and record the upstream release** · Software/edition terms and optional paid features are defined by the upstream project. - Why: The guide must match the software you actually deploy. - Get it: Open https://docs.n8n.io/deploy/host-n8n/install-options/install-with-docker, choose a stable release compatible with its database requirements, record its tag and resolved digest in versions.txt, and use those values in compose.yaml. Avoid unattended latest-tag updates. - Verify: versions.txt names both application and database versions or states that the pilot uses embedded SQLite. - [ ] **n8n Cloud acceptance sample** · No paid service required for this local step. - Why: This fixture makes the first end-to-end check reproducible. - Get it: Create synthetic sample data before implementation: A Manual Trigger to Edit Fields workflow producing hello plus a Schedule Trigger proof using no external account. Save it under fixtures/ with the expected results in fixtures/README.md; use no real credentials or customer records. - Verify: The fixture files and expected outcomes exist and can be inspected without a vendor account. - [ ] **Confirm the bounded replacement** · No paid service required for this local step. - Why: The full commercial product is larger than this guide. - Get it: The deliverable is an owner-operated n8n workflow instance with persistent credentials and tested recovery. Read every exclusion below. Indie mode runs locally; any public or shared use requires the product access and deployment gates first. - Verify: You can name the primary workflow and the vendor features this version deliberately leaves out. ## Quick start ```sh docker compose config --quiet ``` Then copy `.env.example` to `.env` and fill in the values it documents. ## Honest limits This build deliberately does not replace: - Workflow JSON alone is not a backup of credentials or execution data; changing to PostgreSQL does not copy old SQLite data. - This is an owner-operated n8n workflow instance with persistent credentials and tested recovery; full n8n Cloud feature parity, vendor hosting and support are not included. - managed hosting - backups - scaling - email support - reduced ops burden - team/admin features If one of those is essential to you, that is the reason to keep paying for n8n Cloud, and the README should say so rather than pretend. ===== BRIEF.md ===== # Build brief · n8n Cloud The one-shot brief this plan expands. `BUILD_PLAN.md` (or `MILESTONES.md`) is the same sequence broken into steps and checks; where the two disagree, the plan wins. Build me an owner-operated n8n workflow instance with persistent credentials and tested recovery as a bounded replacement for n8n Cloud. Build it in phases in the order below. Do not write the whole product in one pass. Finish the current phase, run its Done when checks, fix failures, then continue. Indie mode completes Phases 1-5. Phase 6 is required before shared or public deployment. ### Stack (fixed, do not substitute) - Application: Upstream n8n container. Reuse the maintained application; the work is deployment and operations. - Storage: Persistent upstream SQLite pilot volume. Use the upstream schema and keep data across container replacement. - Deployment: Docker Compose; Caddy for product HTTPS. Explicit volumes, ports and configuration can be reviewed and recreated. ### Data model (create this before Phase 1) - Use the upstream n8n schema. For the local pilot retain the entire /home/node/.n8n volume, including its SQLite database and encryption material - keep workflow exports and pinned image digest. Product mode must rehearse the documented PostgreSQL migration/export path rather than simply changing database settings. - Use stable ids and explicit relationships; add auxiliary tables named by the phases before those phases use them. - Acceptance fixture: A Manual Trigger to Edit Fields workflow producing hello plus a Schedule Trigger proof using no external account. ### Prerequisites and configuration - Docker Engine and Compose v2: Install Docker Engine and the Compose plugin on Linux using the official instructions. On Windows use Docker Desktop with WSL2, then work inside a Linux project folder. Verify: docker compose version prints a v2 version and docker info reaches the daemon. Cost: Docker Engine has no hosting fee; Desktop licensing depends on your use, and a rented host is billed separately. - Choose and record the upstream release: Open https://docs.n8n.io/deploy/host-n8n/install-options/install-with-docker, choose a stable release compatible with its database requirements, record its tag and resolved digest in versions.txt, and use those values in compose.yaml. Avoid unattended latest-tag updates. Verify: versions.txt names both application and database versions or states that the pilot uses embedded SQLite. Cost: Software/edition terms and optional paid features are defined by the upstream project. - n8n Cloud acceptance sample: Create synthetic sample data before implementation: A Manual Trigger to Edit Fields workflow producing hello plus a Schedule Trigger proof using no external account. Save it under fixtures/ with the expected results in fixtures/README.md; use no real credentials or customer records. Verify: The fixture files and expected outcomes exist and can be inspected without a vendor account. Cost: No paid service required for this local step. - Confirm the bounded replacement: The deliverable is an owner-operated n8n workflow instance with persistent credentials and tested recovery. Read every exclusion below. Indie mode runs locally; any public or shared use requires the product access and deployment gates first. Verify: You can name the primary workflow and the vendor features this version deliberately leaves out. Cost: No paid service required for this local step. - Configuration: APP_IMAGE, SITE_URL, GENERIC_TIMEZONE, TZ. Ship .env.example, replace placeholders and exclude secrets from git. ### Phase 1 · Deployment inventory and safe pilot Build: Prepare the pinned upstream deployment for an owner-operated n8n workflow instance with persistent credentials and tested recovery. - Read the linked upstream installation guide and create compose.yaml, .env.example, versions.txt and OPERATIONS.md. Map APP_IMAGE and only each service's required environment variables explicitly. Keep database ports internal and map the pilot application port to 127.0.0.1. - Use the upstream n8n schema. For the local pilot retain the entire /home/node/.n8n volume, including its SQLite database and encryption material; keep workflow exports and pinned image digest. Product mode must rehearse the documented PostgreSQL migration/export path rather than simply changing database settings. Name each volume and its mount path in OPERATIONS.md; never use ephemeral container storage for the only copy. Create .env manually from .env.example and replace placeholders before starting. Commands, after creating the named files: `docker compose config --quiet`. - Create a private fixtures/ folder containing: A Manual Trigger to Edit Fields workflow producing hello plus a Schedule Trigger proof using no external account. Create a separate backup destination and an isolated restore-project name; do not reuse live volumes in restore exercises. - Trap: A valid Compose file proves configuration syntax only, not application health. Done when: docker compose config --quiet succeeds with no unresolved required variables. The documented volume list includes every persistent asset and no secret is committed. Do not build yet: Do not start persistent local instance until these checks pass. ### Phase 2 · Persistent local instance Build: Persistent local instance for n8n Cloud: Deploy the official n8n image using Compose with a persistent /home/node/.n8n mount and a loopback mapping for port 5678. - Deploy the official n8n image using Compose with a persistent /home/node/.n8n mount and a loopback mapping for port 5678. - Create the owner account and retain the generated encryption material with restricted backups; disable optional AI/cloud features for this pilot. - Use A Manual Trigger to Edit Fields workflow producing hello plus a Schedule Trigger proof using no external account. Check: Restarting the container retains the owner account and a saved workflow. Then check: The editor is unreachable through a non-loopback host interface. Record commands, observed results and the date in OPERATIONS.md. - Trap: Follow upstream settings for the selected release; do not copy deprecated task-runner flags from old examples. Done when: Restarting the container retains the owner account and a saved workflow. The editor is unreachable through a non-loopback host interface. Do not build yet: Do not start useful workflow proof until these checks pass. ### Phase 3 · Useful workflow proof Build: Useful workflow proof for n8n Cloud: Build the Manual Trigger and Edit Fields proof, inspect output, then add a Schedule Trigger with the intended timezone. - Build the Manual Trigger and Edit Fields proof, inspect output, then add a Schedule Trigger with the intended timezone. - Export the workflow JSON and record its expected output; keep credentials in the n8n credential store, never in exported node parameters. - Use A Manual Trigger to Edit Fields workflow producing hello plus a Schedule Trigger proof using no external account. Check: The manual workflow produces the exact hello field. Then check: The scheduled proof runs at the documented timezone and appears in execution history. Record commands, observed results and the date in OPERATIONS.md. - Trap: An enabled schedule is an actual side effect; test only a harmless local workflow. Done when: The manual workflow produces the exact hello field. The scheduled proof runs at the documented timezone and appears in execution history. Do not build yet: Do not start recovery and upgrade until these checks pass. ### Phase 4 · Recovery and upgrade Build: Recovery and upgrade for n8n Cloud: Stop the local SQLite instance for a consistent complete volume backup and store encryption material securely alongside it. - Stop the local SQLite instance for a consistent complete volume backup and store encryption material securely alongside it. - Restore into a new isolated volume with schedules disabled, import or inspect the proof workflow and test before selecting a new image. - Use A Manual Trigger to Edit Fields workflow producing hello plus a Schedule Trigger proof using no external account. Check: The restored proof workflow runs and any test credential remains decryptable. Then check: The backup manifest includes the encryption material, image version and restore date. Record commands, observed results and the date in OPERATIONS.md. - Trap: Workflow JSON alone is not a backup of credentials or execution data; changing to PostgreSQL does not copy old SQLite data. Done when: The restored proof workflow runs and any test credential remains decryptable. The backup manifest includes the encryption material, image version and restore date. Do not build yet: Do not start portable delivery and clean-start proof until these checks pass. ### Phase 5 · Portable delivery and clean-start proof Build: Finish the n8n Cloud replacement with a documented first-run path and a recoverable export. - Document prerequisites, every configuration variable, data locations and the three domain workflows: Persistent local instance; Useful workflow proof; Recovery and upgrade. Include the exclusions, actual costs and source check date 2026-09-05. Commands shown earlier that reference project files are files the builder must implement before running them. - Stop the pilot service and back up its complete persistent volume including SQLite and encryption material; retain versioned workflow exports as a secondary aid. Restore into a separate empty directory or isolated deployment, with all outbound actions and schedules disabled. Recreate this proof: A Manual Trigger to Edit Fields workflow producing hello plus a Schedule Trigger proof using no external account. Compare ids/counts and open the result before recording the restore date. Never test a restore over the only live copy. - Use a new folder and only README instructions to reach the fixture outcome. Verify upstream login, persistence, proof output and restore. Record exactly what passed; do not mark unrun checks complete. Commands, after creating the named files: `docker compose ps`. - Trap: Export without an import or restore rehearsal is not verified portability. Done when: A new folder reaches the documented fixture outcome using only README instructions. A backup restored in isolation preserves the proof data and can be opened. Do not build yet: Do not start operate and share with access controls until these checks pass. ### Phase 6 · Operate and share with access controls (product-builder only) Build: Product-builder only: make an owner-operated n8n workflow instance with persistent credentials and tested recovery operable for its stated audience before allowing remote access. - Use upstream authentication, replace default credentials, restrict the editor/admin surface and inventory public ingestion/webhook paths. Review upstream edition and license boundaries before offering this as a service. - Put Caddy HTTPS in front of the upstream app, keep database and management ports private and configure public URLs from the chosen domain. For n8n, rehearse upstream PostgreSQL migration/import and recovery before claiming production readiness; disable any unused AI sandbox services. - Add a scheduled encrypted off-host backup using this procedure: Stop the pilot service and back up its complete persistent volume including SQLite and encryption material; retain versioned workflow exports as a secondary aid. Monitor health, disk space, failed jobs and backup age. Stop the service to test an alert; rehearse recovery with outbound effects disabled and record recovery time. Rotate any exposed credentials and require reconciliation before resuming queues. - Trap: Product mode is additional engineering, not a switch that makes a local prototype production-ready. Done when: An unauthenticated visitor cannot read private records, download private files or mutate the admin surface. A viewer cannot mutate data by making a direct request, and guessed ids cannot cross ownership boundaries. Stopping the service triggers the configured alert and the latest off-host backup restores the fixture in isolation. Do not build yet: Do not add new providers or vendor-scale features until the release gates are recorded. ### Out of scope (and why) - Workflow JSON alone is not a backup of credentials or execution data; changing to PostgreSQL does not copy old SQLite data. - This is an owner-operated n8n workflow instance with persistent credentials and tested recovery; full n8n Cloud feature parity, vendor hosting and support are not included. - managed hosting: retain the paid product if this capability is essential; it is outside this bounded build. - backups: retain the paid product if this capability is essential; it is outside this bounded build. - scaling: retain the paid product if this capability is essential; it is outside this bounded build. - email support: retain the paid product if this capability is essential; it is outside this bounded build. - reduced ops burden: retain the paid product if this capability is essential; it is outside this bounded build. - team/admin features: retain the paid product if this capability is essential; it is outside this bounded build. ### README must contain - Exact install, configure, initialize, start, test and recovery commands for a clean folder. - The schema, fixture, acceptance results, private data locations and export format. - Every prerequisite and secret source, actual running costs and deliberately excluded capabilities. - An honest distinction between tests actually run and checks still awaiting real credentials or deployment. - Dependency documentation reviewed 2026-09-05: https://docs.n8n.io/deploy/host-n8n/install-options/install-with-docker ; https://docs.n8n.io/deploy/host-n8n/install-options/install-using-docker-compose. Recheck before upgrading; freeze the versions actually tested. ===== AGENTS.md ===== # Agent instructions · n8n Cloud indie build - Read `README.md` and `BUILD_PLAN.md` before writing code. The stack is fixed: Upstream n8n container, Persistent upstream SQLite pilot volume, Docker Compose; Caddy for product HTTPS. Do not substitute. - Work one phase at a time, in order. Do not start a phase until every "Done when" item of the previous one passes. - Prefer the fewest moving parts that satisfy the step. No frameworks, services or dependencies the plan does not name. - Secrets live in `.env`, never in source or logs. Keep `.env.example` current when a variable is introduced. - Do not invent cryptography, security guarantees, APIs or compliance claims. - Add a focused test for every destructive, security-sensitive or data-loss path the plan names. - Run the project checks before declaring a phase complete, and record any deliberate shortcut in the README under "Tradeoffs". ## Known traps - A valid Compose file proves configuration syntax only, not application health. - Follow upstream settings for the selected release; do not copy deprecated task-runner flags from old examples. - An enabled schedule is an actual side effect; test only a harmless local workflow. - Workflow JSON alone is not a backup of credentials or execution data; changing to PostgreSQL does not copy old SQLite data. - Export without an import or restore rehearsal is not verified portability. ===== BUILD_PLAN.md ===== # Build plan · n8n Cloud Build an owner-operated n8n workflow instance with persistent credentials and tested recovery. Phases are in dependency order. Each ends in a "Done when" list; treat an unticked item as a blocker, not a note. ## Phase 1 · Deployment inventory and safe pilot Prepare the pinned upstream deployment for an owner-operated n8n workflow instance with persistent credentials and tested recovery. ### Steps 1. Create the deployment files Read the linked upstream installation guide and create compose.yaml, .env.example, versions.txt and OPERATIONS.md. Map APP_IMAGE and only each service's required environment variables explicitly. Keep database ports internal and map the pilot application port to 127.0.0.1. Files: `compose.yaml`, `.env.example`, `versions.txt` 2. Identify every persistent asset Use the upstream n8n schema. For the local pilot retain the entire /home/node/.n8n volume, including its SQLite database and encryption material; keep workflow exports and pinned image digest. Product mode must rehearse the documented PostgreSQL migration/export path rather than simply changing database settings. Name each volume and its mount path in OPERATIONS.md; never use ephemeral container storage for the only copy. Create .env manually from .env.example and replace placeholders before starting. Files: `OPERATIONS.md`, `.gitignore` ```sh docker compose config --quiet ``` 3. Prepare the proof and recovery folder Create a private fixtures/ folder containing: A Manual Trigger to Edit Fields workflow producing hello plus a Schedule Trigger proof using no external account. Create a separate backup destination and an isolated restore-project name; do not reuse live volumes in restore exercises. Files: `fixtures/README.md`, `OPERATIONS.md` ### Done when - [ ] docker compose config --quiet succeeds with no unresolved required variables. - [ ] The documented volume list includes every persistent asset and no secret is committed. ### Watch out - A valid Compose file proves configuration syntax only, not application health. ## Phase 2 · Persistent local instance Persistent local instance for n8n Cloud: Deploy the official n8n image using Compose with a persistent /home/node/.n8n mount and a loopback mapping for port 5678. ### Steps 1. Deploy the official n8n image using Compose with a persistent /home/node/.n8n mount and a loopback mapping for port 5678. Deploy the official n8n image using Compose with a persistent /home/node/.n8n mount and a loopback mapping for port 5678. Files: `compose.yaml`, `OPERATIONS.md` 2. Create the owner account and retain the generated encryption material with restricted backups; disable optional AI/cloud features for this pilot. Create the owner account and retain the generated encryption material with restricted backups; disable optional AI/cloud features for this pilot. Files: `OPERATIONS.md` 3. Exercise the acceptance fixture Use A Manual Trigger to Edit Fields workflow producing hello plus a Schedule Trigger proof using no external account. Check: Restarting the container retains the owner account and a saved workflow. Then check: The editor is unreachable through a non-loopback host interface. Record commands, observed results and the date in OPERATIONS.md. Files: `OPERATIONS.md` ### Done when - [ ] Restarting the container retains the owner account and a saved workflow. - [ ] The editor is unreachable through a non-loopback host interface. ### Watch out - Follow upstream settings for the selected release; do not copy deprecated task-runner flags from old examples. ## Phase 3 · Useful workflow proof Useful workflow proof for n8n Cloud: Build the Manual Trigger and Edit Fields proof, inspect output, then add a Schedule Trigger with the intended timezone. ### Steps 1. Build the Manual Trigger and Edit Fields proof, inspect output, then add a Schedule Trigger with the intended timezone. Build the Manual Trigger and Edit Fields proof, inspect output, then add a Schedule Trigger with the intended timezone. Files: `compose.yaml`, `OPERATIONS.md` 2. Export the workflow JSON and record its expected output; keep credentials in the n8n credential store, never in exported node parameters. Export the workflow JSON and record its expected output; keep credentials in the n8n credential store, never in exported node parameters. Files: `OPERATIONS.md` 3. Exercise the acceptance fixture Use A Manual Trigger to Edit Fields workflow producing hello plus a Schedule Trigger proof using no external account. Check: The manual workflow produces the exact hello field. Then check: The scheduled proof runs at the documented timezone and appears in execution history. Record commands, observed results and the date in OPERATIONS.md. Files: `OPERATIONS.md` ### Done when - [ ] The manual workflow produces the exact hello field. - [ ] The scheduled proof runs at the documented timezone and appears in execution history. ### Watch out - An enabled schedule is an actual side effect; test only a harmless local workflow. ## Phase 4 · Recovery and upgrade Recovery and upgrade for n8n Cloud: Stop the local SQLite instance for a consistent complete volume backup and store encryption material securely alongside it. ### Steps 1. Stop the local SQLite instance for a consistent complete volume backup and store encryption material securely alongside it. Stop the local SQLite instance for a consistent complete volume backup and store encryption material securely alongside it. Files: `compose.yaml`, `OPERATIONS.md` 2. Restore into a new isolated volume with schedules disabled, import or inspect the proof workflow and test before selecting a new image. Restore into a new isolated volume with schedules disabled, import or inspect the proof workflow and test before selecting a new image. Files: `OPERATIONS.md` 3. Exercise the acceptance fixture Use A Manual Trigger to Edit Fields workflow producing hello plus a Schedule Trigger proof using no external account. Check: The restored proof workflow runs and any test credential remains decryptable. Then check: The backup manifest includes the encryption material, image version and restore date. Record commands, observed results and the date in OPERATIONS.md. Files: `OPERATIONS.md` ### Done when - [ ] The restored proof workflow runs and any test credential remains decryptable. - [ ] The backup manifest includes the encryption material, image version and restore date. ### Watch out - Workflow JSON alone is not a backup of credentials or execution data; changing to PostgreSQL does not copy old SQLite data. ## Phase 5 · Portable delivery and clean-start proof Finish the n8n Cloud replacement with a documented first-run path and a recoverable export. ### Steps 1. Write the user-facing runbook Document prerequisites, every configuration variable, data locations and the three domain workflows: Persistent local instance; Useful workflow proof; Recovery and upgrade. Include the exclusions, actual costs and source check date 2026-09-05. Commands shown earlier that reference project files are files the builder must implement before running them. Files: `README.md`, `.env.example` 2. Create and rehearse a recoverable backup Stop the pilot service and back up its complete persistent volume including SQLite and encryption material; retain versioned workflow exports as a secondary aid. Restore into a separate empty directory or isolated deployment, with all outbound actions and schedules disabled. Recreate this proof: A Manual Trigger to Edit Fields workflow producing hello plus a Schedule Trigger proof using no external account. Compare ids/counts and open the result before recording the restore date. Never test a restore over the only live copy. Files: `OPERATIONS.md`, `backup/README.md` 3. Reproduce the first-run experience Use a new folder and only README instructions to reach the fixture outcome. Verify upstream login, persistence, proof output and restore. Record exactly what passed; do not mark unrun checks complete. Files: `README.md`, `verification.md` ```sh docker compose ps ``` ### Done when - [ ] A new folder reaches the documented fixture outcome using only README instructions. - [ ] A backup restored in isolation preserves the proof data and can be opened. ### Watch out - Export without an import or restore rehearsal is not verified portability. ## Not in this build - Workflow JSON alone is not a backup of credentials or execution data; changing to PostgreSQL does not copy old SQLite data. - This is an owner-operated n8n workflow instance with persistent credentials and tested recovery; full n8n Cloud feature parity, vendor hosting and support are not included. - managed hosting - backups - scaling - email support - reduced ops burden - team/admin features ## After v1, if you want it - Extend recovery and upgrade only after the fixture and recovery checks pass. - Before adding another integration, document its credentials, limits, cost and failure behavior with primary-source links. ===== .env.example ===== # Copy to .env and fill in. Never commit .env; this file documents it. # Required. Copy the exact application image reference selected from upstream into compose.yaml via this variable. APP_IMAGE=replace-with-tested-image-and-digest # Required. The loopback URL selected in compose.yaml; replace with your HTTPS origin only after completing product deployment. SITE_URL=http://localhost:5678 # Required. Set the intended workflow timezone in the n8n service; record it beside the schedule proof. GENERIC_TIMEZONE=UTC # Required. Container system timezone; keep it consistent with the intended pilot timezone. TZ=UTC
You are building a production product version of n8n Cloud. Create the following project files first, then implement the application by following them. Keep the files updated as decisions change. Do not collapse this into a single README or prompt. ===== PRODUCT.md ===== # n8n Cloud · product brief ## Problem Because n8n itself is open source, the core cloud subscription can be replaced by self-hosting if you can own hosting, updates, and backups. ## Product outcome An operated version of an owner-operated n8n workflow instance with persistent credentials and tested recovery, with authorized access, restore evidence and honest scope limits. ## Target user A builder who needs a maintainable product foundation, not a one-off demo. ## Required capabilities - VPS or Docker host - domain/HTTPS - database/storage - backups - API credentials - update routine ## Explicit non-goals for v1 - Workflow JSON alone is not a backup of credentials or execution data; changing to PostgreSQL does not copy old SQLite data. - This is an owner-operated n8n workflow instance with persistent credentials and tested recovery; full n8n Cloud feature parity, vendor hosting and support are not included. - managed hosting - backups - scaling - email support - reduced ops burden - team/admin features ## Success criteria - Restarting the container retains the owner account and a saved workflow. - The manual workflow produces the exact hello field. - The restored proof workflow runs and any test credential remains decryptable. - A private-data authorization check passes using a second identity. - An off-host restore drill has a date, observed result and recovery time in OPERATIONS.md. - README names the excluded vendor capabilities and actual provider/hosting costs. ===== BRIEF.md ===== # Build brief · n8n Cloud The one-shot brief this plan expands. `BUILD_PLAN.md` (or `MILESTONES.md`) is the same sequence broken into steps and checks; where the two disagree, the plan wins. Build me an owner-operated n8n workflow instance with persistent credentials and tested recovery as a bounded replacement for n8n Cloud. Build it in phases in the order below. Do not write the whole product in one pass. Finish the current phase, run its Done when checks, fix failures, then continue. Indie mode completes Phases 1-5. Phase 6 is required before shared or public deployment. ### Stack (fixed, do not substitute) - Application: Upstream n8n container. Reuse the maintained application; the work is deployment and operations. - Storage: Persistent upstream SQLite pilot volume. Use the upstream schema and keep data across container replacement. - Deployment: Docker Compose; Caddy for product HTTPS. Explicit volumes, ports and configuration can be reviewed and recreated. ### Data model (create this before Phase 1) - Use the upstream n8n schema. For the local pilot retain the entire /home/node/.n8n volume, including its SQLite database and encryption material - keep workflow exports and pinned image digest. Product mode must rehearse the documented PostgreSQL migration/export path rather than simply changing database settings. - Use stable ids and explicit relationships; add auxiliary tables named by the phases before those phases use them. - Acceptance fixture: A Manual Trigger to Edit Fields workflow producing hello plus a Schedule Trigger proof using no external account. ### Prerequisites and configuration - Docker Engine and Compose v2: Install Docker Engine and the Compose plugin on Linux using the official instructions. On Windows use Docker Desktop with WSL2, then work inside a Linux project folder. Verify: docker compose version prints a v2 version and docker info reaches the daemon. Cost: Docker Engine has no hosting fee; Desktop licensing depends on your use, and a rented host is billed separately. - Choose and record the upstream release: Open https://docs.n8n.io/deploy/host-n8n/install-options/install-with-docker, choose a stable release compatible with its database requirements, record its tag and resolved digest in versions.txt, and use those values in compose.yaml. Avoid unattended latest-tag updates. Verify: versions.txt names both application and database versions or states that the pilot uses embedded SQLite. Cost: Software/edition terms and optional paid features are defined by the upstream project. - n8n Cloud acceptance sample: Create synthetic sample data before implementation: A Manual Trigger to Edit Fields workflow producing hello plus a Schedule Trigger proof using no external account. Save it under fixtures/ with the expected results in fixtures/README.md; use no real credentials or customer records. Verify: The fixture files and expected outcomes exist and can be inspected without a vendor account. Cost: No paid service required for this local step. - Confirm the bounded replacement: The deliverable is an owner-operated n8n workflow instance with persistent credentials and tested recovery. Read every exclusion below. Indie mode runs locally; any public or shared use requires the product access and deployment gates first. Verify: You can name the primary workflow and the vendor features this version deliberately leaves out. Cost: No paid service required for this local step. - Configuration: APP_IMAGE, SITE_URL, GENERIC_TIMEZONE, TZ. Ship .env.example, replace placeholders and exclude secrets from git. ### Phase 1 · Deployment inventory and safe pilot Build: Prepare the pinned upstream deployment for an owner-operated n8n workflow instance with persistent credentials and tested recovery. - Read the linked upstream installation guide and create compose.yaml, .env.example, versions.txt and OPERATIONS.md. Map APP_IMAGE and only each service's required environment variables explicitly. Keep database ports internal and map the pilot application port to 127.0.0.1. - Use the upstream n8n schema. For the local pilot retain the entire /home/node/.n8n volume, including its SQLite database and encryption material; keep workflow exports and pinned image digest. Product mode must rehearse the documented PostgreSQL migration/export path rather than simply changing database settings. Name each volume and its mount path in OPERATIONS.md; never use ephemeral container storage for the only copy. Create .env manually from .env.example and replace placeholders before starting. Commands, after creating the named files: `docker compose config --quiet`. - Create a private fixtures/ folder containing: A Manual Trigger to Edit Fields workflow producing hello plus a Schedule Trigger proof using no external account. Create a separate backup destination and an isolated restore-project name; do not reuse live volumes in restore exercises. - Trap: A valid Compose file proves configuration syntax only, not application health. Done when: docker compose config --quiet succeeds with no unresolved required variables. The documented volume list includes every persistent asset and no secret is committed. Do not build yet: Do not start persistent local instance until these checks pass. ### Phase 2 · Persistent local instance Build: Persistent local instance for n8n Cloud: Deploy the official n8n image using Compose with a persistent /home/node/.n8n mount and a loopback mapping for port 5678. - Deploy the official n8n image using Compose with a persistent /home/node/.n8n mount and a loopback mapping for port 5678. - Create the owner account and retain the generated encryption material with restricted backups; disable optional AI/cloud features for this pilot. - Use A Manual Trigger to Edit Fields workflow producing hello plus a Schedule Trigger proof using no external account. Check: Restarting the container retains the owner account and a saved workflow. Then check: The editor is unreachable through a non-loopback host interface. Record commands, observed results and the date in OPERATIONS.md. - Trap: Follow upstream settings for the selected release; do not copy deprecated task-runner flags from old examples. Done when: Restarting the container retains the owner account and a saved workflow. The editor is unreachable through a non-loopback host interface. Do not build yet: Do not start useful workflow proof until these checks pass. ### Phase 3 · Useful workflow proof Build: Useful workflow proof for n8n Cloud: Build the Manual Trigger and Edit Fields proof, inspect output, then add a Schedule Trigger with the intended timezone. - Build the Manual Trigger and Edit Fields proof, inspect output, then add a Schedule Trigger with the intended timezone. - Export the workflow JSON and record its expected output; keep credentials in the n8n credential store, never in exported node parameters. - Use A Manual Trigger to Edit Fields workflow producing hello plus a Schedule Trigger proof using no external account. Check: The manual workflow produces the exact hello field. Then check: The scheduled proof runs at the documented timezone and appears in execution history. Record commands, observed results and the date in OPERATIONS.md. - Trap: An enabled schedule is an actual side effect; test only a harmless local workflow. Done when: The manual workflow produces the exact hello field. The scheduled proof runs at the documented timezone and appears in execution history. Do not build yet: Do not start recovery and upgrade until these checks pass. ### Phase 4 · Recovery and upgrade Build: Recovery and upgrade for n8n Cloud: Stop the local SQLite instance for a consistent complete volume backup and store encryption material securely alongside it. - Stop the local SQLite instance for a consistent complete volume backup and store encryption material securely alongside it. - Restore into a new isolated volume with schedules disabled, import or inspect the proof workflow and test before selecting a new image. - Use A Manual Trigger to Edit Fields workflow producing hello plus a Schedule Trigger proof using no external account. Check: The restored proof workflow runs and any test credential remains decryptable. Then check: The backup manifest includes the encryption material, image version and restore date. Record commands, observed results and the date in OPERATIONS.md. - Trap: Workflow JSON alone is not a backup of credentials or execution data; changing to PostgreSQL does not copy old SQLite data. Done when: The restored proof workflow runs and any test credential remains decryptable. The backup manifest includes the encryption material, image version and restore date. Do not build yet: Do not start portable delivery and clean-start proof until these checks pass. ### Phase 5 · Portable delivery and clean-start proof Build: Finish the n8n Cloud replacement with a documented first-run path and a recoverable export. - Document prerequisites, every configuration variable, data locations and the three domain workflows: Persistent local instance; Useful workflow proof; Recovery and upgrade. Include the exclusions, actual costs and source check date 2026-09-05. Commands shown earlier that reference project files are files the builder must implement before running them. - Stop the pilot service and back up its complete persistent volume including SQLite and encryption material; retain versioned workflow exports as a secondary aid. Restore into a separate empty directory or isolated deployment, with all outbound actions and schedules disabled. Recreate this proof: A Manual Trigger to Edit Fields workflow producing hello plus a Schedule Trigger proof using no external account. Compare ids/counts and open the result before recording the restore date. Never test a restore over the only live copy. - Use a new folder and only README instructions to reach the fixture outcome. Verify upstream login, persistence, proof output and restore. Record exactly what passed; do not mark unrun checks complete. Commands, after creating the named files: `docker compose ps`. - Trap: Export without an import or restore rehearsal is not verified portability. Done when: A new folder reaches the documented fixture outcome using only README instructions. A backup restored in isolation preserves the proof data and can be opened. Do not build yet: Do not start operate and share with access controls until these checks pass. ### Phase 6 · Operate and share with access controls (product-builder only) Build: Product-builder only: make an owner-operated n8n workflow instance with persistent credentials and tested recovery operable for its stated audience before allowing remote access. - Use upstream authentication, replace default credentials, restrict the editor/admin surface and inventory public ingestion/webhook paths. Review upstream edition and license boundaries before offering this as a service. - Put Caddy HTTPS in front of the upstream app, keep database and management ports private and configure public URLs from the chosen domain. For n8n, rehearse upstream PostgreSQL migration/import and recovery before claiming production readiness; disable any unused AI sandbox services. - Add a scheduled encrypted off-host backup using this procedure: Stop the pilot service and back up its complete persistent volume including SQLite and encryption material; retain versioned workflow exports as a secondary aid. Monitor health, disk space, failed jobs and backup age. Stop the service to test an alert; rehearse recovery with outbound effects disabled and record recovery time. Rotate any exposed credentials and require reconciliation before resuming queues. - Trap: Product mode is additional engineering, not a switch that makes a local prototype production-ready. Done when: An unauthenticated visitor cannot read private records, download private files or mutate the admin surface. A viewer cannot mutate data by making a direct request, and guessed ids cannot cross ownership boundaries. Stopping the service triggers the configured alert and the latest off-host backup restores the fixture in isolation. Do not build yet: Do not add new providers or vendor-scale features until the release gates are recorded. ### Out of scope (and why) - Workflow JSON alone is not a backup of credentials or execution data; changing to PostgreSQL does not copy old SQLite data. - This is an owner-operated n8n workflow instance with persistent credentials and tested recovery; full n8n Cloud feature parity, vendor hosting and support are not included. - managed hosting: retain the paid product if this capability is essential; it is outside this bounded build. - backups: retain the paid product if this capability is essential; it is outside this bounded build. - scaling: retain the paid product if this capability is essential; it is outside this bounded build. - email support: retain the paid product if this capability is essential; it is outside this bounded build. - reduced ops burden: retain the paid product if this capability is essential; it is outside this bounded build. - team/admin features: retain the paid product if this capability is essential; it is outside this bounded build. ### README must contain - Exact install, configure, initialize, start, test and recovery commands for a clean folder. - The schema, fixture, acceptance results, private data locations and export format. - Every prerequisite and secret source, actual running costs and deliberately excluded capabilities. - An honest distinction between tests actually run and checks still awaiting real credentials or deployment. - Dependency documentation reviewed 2026-09-05: https://docs.n8n.io/deploy/host-n8n/install-options/install-with-docker ; https://docs.n8n.io/deploy/host-n8n/install-options/install-using-docker-compose. Recheck before upgrading; freeze the versions actually tested. ===== ARCHITECTURE.md ===== # Architecture · n8n Cloud ## Stack | Part | Choice | Why | | --- | --- | --- | | Application | Upstream n8n container | Reuse the maintained application; the work is deployment and operations. | | Storage | Persistent upstream SQLite pilot volume | Use the upstream schema and keep data across container replacement. | | Deployment | Docker Compose; Caddy for product HTTPS | Explicit volumes, ports and configuration can be reviewed and recreated. | ## Modules Each module has one owner concern and a documented way to replace it. | Module | Owns | How to replace it | | --- | --- | --- | | Data and identity | Use the upstream n8n schema. For the local pilot retain the entire /home/node/.n8n volume, including its SQLite database and encryption material; keep workflow exports and pinned image digest. Product mode must rehearse the documented PostgreSQL migration/export path rather than simply changing database settings. | Follow upstream migration procedures and verify a restored fixture before switching stores. | | Persistent local instance | Deploy the official n8n image using Compose with a persistent /home/node/.n8n mount and a loopback mapping for port 5678. | Keep the acceptance contract: Restarting the container retains the owner account and a saved workflow. Replace only this module after replaying its fixture; preserve ids and existing records. | | Useful workflow proof | Build the Manual Trigger and Edit Fields proof, inspect output, then add a Schedule Trigger with the intended timezone. | Keep the acceptance contract: The manual workflow produces the exact hello field. Replace only this module after replaying its fixture; preserve ids and existing records. | | Recovery and upgrade | Stop the local SQLite instance for a consistent complete volume backup and store encryption material securely alongside it. | Keep the acceptance contract: The restored proof workflow runs and any test credential remains decryptable. Replace only this module after replaying its fixture; preserve ids and existing records. | | Operations | Stop the pilot service and back up its complete persistent volume including SQLite and encryption material; retain versioned workflow exports as a secondary aid. | Change host or backup destination only after an isolated restore and authorization check. | ## Configuration Every runtime setting is an environment variable documented in `.env.example`, validated at startup, with a safe local default wherever one exists. - `APP_IMAGE` · required · Copy the exact application image reference selected from upstream into compose.yaml via this variable. - `SITE_URL` · required · The loopback URL selected in compose.yaml; replace with your HTTPS origin only after completing product deployment. - `GENERIC_TIMEZONE` · required · Set the intended workflow timezone in the n8n service; record it beside the schedule proof. - `TZ` · required · Container system timezone; keep it consistent with the intended pilot timezone. ## Production baseline - Security: least privilege, input validation at every boundary, secret redaction in logs, rate limits on abuse-prone paths, no invented security primitives. - Data: explicit schema and migrations, transactional writes where integrity matters, backup and restore procedures that have been exercised. - Integrations: adapters around third-party providers, idempotent webhook or job processing, bounded retries, timeouts. - Observability: structured logs with request or operation ids, an error-tracking hook, and health and readiness checks where a server exists. - Quality: unit tests for domain rules, integration tests at module boundaries, one end-to-end test of the critical path. ## Decision records For each dependency in the stack table, keep a short note: why it was chosen, its failure mode, and how it is replaced. Do not add infrastructure until a requirement in `PRODUCT.md` justifies it. ===== AGENTS.md ===== # Agent instructions · n8n Cloud product build - Read `PRODUCT.md` and `ARCHITECTURE.md` before changing code. The stack is fixed: Upstream n8n container, Persistent upstream SQLite pilot volume, Docker Compose; Caddy for product HTTPS. - Implement milestone by milestone from `MILESTONES.md`; keep each change reviewable and leave the application runnable at every commit. - Treat authentication, payments, encryption, imports, webhooks and destructive actions as high-risk boundaries when present. - Never invent cryptography or silently weaken a requirement to make a check pass. - Put every external service behind an interface with a deterministic fake for tests. - Add migrations and rollback or recovery notes for every persistent data change. - Log useful operational context without credentials, tokens, passwords or personal data. - Update documentation and run every check before completing a milestone. ## Known traps - A valid Compose file proves configuration syntax only, not application health. - Follow upstream settings for the selected release; do not copy deprecated task-runner flags from old examples. - An enabled schedule is an actual side effect; test only a harmless local workflow. - Workflow JSON alone is not a backup of credentials or execution data; changing to PostgreSQL does not copy old SQLite data. - Export without an import or restore rehearsal is not verified portability. - Product mode is additional engineering, not a switch that makes a local prototype production-ready. ===== MILESTONES.md ===== # Delivery milestones · n8n Cloud Estimated effort: **multi-day** for the indie phases; the production-only milestones add the trust and operability layer. ## M1 · Deployment inventory and safe pilot Prepare the pinned upstream deployment for an owner-operated n8n workflow instance with persistent credentials and tested recovery. ### Steps 1. Create the deployment files Read the linked upstream installation guide and create compose.yaml, .env.example, versions.txt and OPERATIONS.md. Map APP_IMAGE and only each service's required environment variables explicitly. Keep database ports internal and map the pilot application port to 127.0.0.1. Files: `compose.yaml`, `.env.example`, `versions.txt` 2. Identify every persistent asset Use the upstream n8n schema. For the local pilot retain the entire /home/node/.n8n volume, including its SQLite database and encryption material; keep workflow exports and pinned image digest. Product mode must rehearse the documented PostgreSQL migration/export path rather than simply changing database settings. Name each volume and its mount path in OPERATIONS.md; never use ephemeral container storage for the only copy. Create .env manually from .env.example and replace placeholders before starting. Files: `OPERATIONS.md`, `.gitignore` ```sh docker compose config --quiet ``` 3. Prepare the proof and recovery folder Create a private fixtures/ folder containing: A Manual Trigger to Edit Fields workflow producing hello plus a Schedule Trigger proof using no external account. Create a separate backup destination and an isolated restore-project name; do not reuse live volumes in restore exercises. Files: `fixtures/README.md`, `OPERATIONS.md` ### Done when - [ ] docker compose config --quiet succeeds with no unresolved required variables. - [ ] The documented volume list includes every persistent asset and no secret is committed. ### Watch out - A valid Compose file proves configuration syntax only, not application health. ## M2 · Persistent local instance Persistent local instance for n8n Cloud: Deploy the official n8n image using Compose with a persistent /home/node/.n8n mount and a loopback mapping for port 5678. ### Steps 1. Deploy the official n8n image using Compose with a persistent /home/node/.n8n mount and a loopback mapping for port 5678. Deploy the official n8n image using Compose with a persistent /home/node/.n8n mount and a loopback mapping for port 5678. Files: `compose.yaml`, `OPERATIONS.md` 2. Create the owner account and retain the generated encryption material with restricted backups; disable optional AI/cloud features for this pilot. Create the owner account and retain the generated encryption material with restricted backups; disable optional AI/cloud features for this pilot. Files: `OPERATIONS.md` 3. Exercise the acceptance fixture Use A Manual Trigger to Edit Fields workflow producing hello plus a Schedule Trigger proof using no external account. Check: Restarting the container retains the owner account and a saved workflow. Then check: The editor is unreachable through a non-loopback host interface. Record commands, observed results and the date in OPERATIONS.md. Files: `OPERATIONS.md` ### Done when - [ ] Restarting the container retains the owner account and a saved workflow. - [ ] The editor is unreachable through a non-loopback host interface. ### Watch out - Follow upstream settings for the selected release; do not copy deprecated task-runner flags from old examples. ## M3 · Useful workflow proof Useful workflow proof for n8n Cloud: Build the Manual Trigger and Edit Fields proof, inspect output, then add a Schedule Trigger with the intended timezone. ### Steps 1. Build the Manual Trigger and Edit Fields proof, inspect output, then add a Schedule Trigger with the intended timezone. Build the Manual Trigger and Edit Fields proof, inspect output, then add a Schedule Trigger with the intended timezone. Files: `compose.yaml`, `OPERATIONS.md` 2. Export the workflow JSON and record its expected output; keep credentials in the n8n credential store, never in exported node parameters. Export the workflow JSON and record its expected output; keep credentials in the n8n credential store, never in exported node parameters. Files: `OPERATIONS.md` 3. Exercise the acceptance fixture Use A Manual Trigger to Edit Fields workflow producing hello plus a Schedule Trigger proof using no external account. Check: The manual workflow produces the exact hello field. Then check: The scheduled proof runs at the documented timezone and appears in execution history. Record commands, observed results and the date in OPERATIONS.md. Files: `OPERATIONS.md` ### Done when - [ ] The manual workflow produces the exact hello field. - [ ] The scheduled proof runs at the documented timezone and appears in execution history. ### Watch out - An enabled schedule is an actual side effect; test only a harmless local workflow. ## M4 · Recovery and upgrade Recovery and upgrade for n8n Cloud: Stop the local SQLite instance for a consistent complete volume backup and store encryption material securely alongside it. ### Steps 1. Stop the local SQLite instance for a consistent complete volume backup and store encryption material securely alongside it. Stop the local SQLite instance for a consistent complete volume backup and store encryption material securely alongside it. Files: `compose.yaml`, `OPERATIONS.md` 2. Restore into a new isolated volume with schedules disabled, import or inspect the proof workflow and test before selecting a new image. Restore into a new isolated volume with schedules disabled, import or inspect the proof workflow and test before selecting a new image. Files: `OPERATIONS.md` 3. Exercise the acceptance fixture Use A Manual Trigger to Edit Fields workflow producing hello plus a Schedule Trigger proof using no external account. Check: The restored proof workflow runs and any test credential remains decryptable. Then check: The backup manifest includes the encryption material, image version and restore date. Record commands, observed results and the date in OPERATIONS.md. Files: `OPERATIONS.md` ### Done when - [ ] The restored proof workflow runs and any test credential remains decryptable. - [ ] The backup manifest includes the encryption material, image version and restore date. ### Watch out - Workflow JSON alone is not a backup of credentials or execution data; changing to PostgreSQL does not copy old SQLite data. ## M5 · Portable delivery and clean-start proof Finish the n8n Cloud replacement with a documented first-run path and a recoverable export. ### Steps 1. Write the user-facing runbook Document prerequisites, every configuration variable, data locations and the three domain workflows: Persistent local instance; Useful workflow proof; Recovery and upgrade. Include the exclusions, actual costs and source check date 2026-09-05. Commands shown earlier that reference project files are files the builder must implement before running them. Files: `README.md`, `.env.example` 2. Create and rehearse a recoverable backup Stop the pilot service and back up its complete persistent volume including SQLite and encryption material; retain versioned workflow exports as a secondary aid. Restore into a separate empty directory or isolated deployment, with all outbound actions and schedules disabled. Recreate this proof: A Manual Trigger to Edit Fields workflow producing hello plus a Schedule Trigger proof using no external account. Compare ids/counts and open the result before recording the restore date. Never test a restore over the only live copy. Files: `OPERATIONS.md`, `backup/README.md` 3. Reproduce the first-run experience Use a new folder and only README instructions to reach the fixture outcome. Verify upstream login, persistence, proof output and restore. Record exactly what passed; do not mark unrun checks complete. Files: `README.md`, `verification.md` ```sh docker compose ps ``` ### Done when - [ ] A new folder reaches the documented fixture outcome using only README instructions. - [ ] A backup restored in isolation preserves the proof data and can be opened. ### Watch out - Export without an import or restore rehearsal is not verified portability. ## M6 · Operate and share with access controls (production only) Product-builder only: make an owner-operated n8n workflow instance with persistent credentials and tested recovery operable for its stated audience before allowing remote access. ### Steps 1. Establish owner access before exposure Use upstream authentication, replace default credentials, restrict the editor/admin surface and inventory public ingestion/webhook paths. Review upstream edition and license boundaries before offering this as a service. Files: `ARCHITECTURE.md`, `OPERATIONS.md` 2. Deploy a monitored service Put Caddy HTTPS in front of the upstream app, keep database and management ports private and configure public URLs from the chosen domain. For n8n, rehearse upstream PostgreSQL migration/import and recovery before claiming production readiness; disable any unused AI sandbox services. Files: `Caddyfile`, `OPERATIONS.md` 3. Rehearse loss and recovery Add a scheduled encrypted off-host backup using this procedure: Stop the pilot service and back up its complete persistent volume including SQLite and encryption material; retain versioned workflow exports as a secondary aid. Monitor health, disk space, failed jobs and backup age. Stop the service to test an alert; rehearse recovery with outbound effects disabled and record recovery time. Rotate any exposed credentials and require reconciliation before resuming queues. Files: `OPERATIONS.md`, `release-checklist.md` ### Done when - [ ] An unauthenticated visitor cannot read private records, download private files or mutate the admin surface. - [ ] A viewer cannot mutate data by making a direct request, and guessed ids cannot cross ownership boundaries. - [ ] Stopping the service triggers the configured alert and the latest off-host backup restores the fixture in isolation. ### Watch out - Product mode is additional engineering, not a switch that makes a local prototype production-ready. ===== OPERATIONS.md ===== # Operations · n8n Cloud ## Backup Stop the pilot service and back up its complete persistent volume including SQLite and encryption material; retain versioned workflow exports as a secondary aid. ## Restore Restore into a separate empty directory or isolated deployment, with all outbound actions and schedules disabled. Recreate this proof: A Manual Trigger to Edit Fields workflow producing hello plus a Schedule Trigger proof using no external account. Compare ids/counts and open the result before recording the restore date. Never test a restore over the only live copy. Do a restore drill before the first real user, and write the date here when it passes. ## Monitoring Check HTTP availability, free disk, backup age and domain failures for Persistent local instance, Useful workflow proof, Recovery and upgrade. Alert without logging private payloads. ## Incident checklist Pause outbound jobs and public intake as appropriate, preserve redacted diagnostics, restore an isolated verified backup, rotate affected credentials and reconcile uncertain effects before reopening. 1. Contain the issue without destroying evidence or user data. 2. Record the timeline and affected scope. 3. Rotate exposed secrets and revoke compromised sessions or credentials. 4. Restore from a verified backup when needed. 5. Document the root cause, the remediation and the regression test. ## Release gate - [ ] Restarting the container retains the owner account and a saved workflow. - [ ] The manual workflow produces the exact hello field. - [ ] The restored proof workflow runs and any test credential remains decryptable. - [ ] A private-data authorization check passes using a second identity. - [ ] An off-host restore drill has a date, observed result and recovery time in OPERATIONS.md. - [ ] README names the excluded vendor capabilities and actual provider/hosting costs. ## Launch constraint Do not market omitted n8n Cloud capabilities as implemented. The non-goals in `PRODUCT.md` remain user-visible limitations until they are deliberately delivered. ===== .env.example ===== # Copy to .env and fill in. Never commit .env; this file documents it. # Required. Copy the exact application image reference selected from upstream into compose.yaml via this variable. APP_IMAGE=replace-with-tested-image-and-digest # Required. The loopback URL selected in compose.yaml; replace with your HTTPS origin only after completing product deployment. SITE_URL=http://localhost:5678 # Required. Set the intended workflow timezone in the n8n service; record it beside the schedule proof. GENERIC_TIMEZONE=UTC # Required. Container system timezone; keep it consistent with the intended pilot timezone. TZ=UTC
README.md
# n8n Cloud · indie build Build an owner-operated n8n workflow instance with persistent credentials and tested recovery. Estimated effort: **multi-day**. Work `BUILD_PLAN.md` top to bottom · every phase ends in a check that has to pass before the next one starts. ## Stack | Part | Choice | Why | | --- | --- | --- | | Application | Upstream n8n container | Reuse the maintained application; the work is deployment and operations. | | Storage | Persistent upstream SQLite pilot volume | Use the upstream schema and keep data across container replacement. | | Deployment | Docker Compose; Caddy for product HTTPS | Explicit volumes, ports and configuration can be reviewed and recreated. | ## Before you start Have every one of these ready. The plan assumes them from step one. - [ ] **Docker Engine and Compose v2** · Docker Engine has no hosting fee; Desktop licensing depends on your use, and a rented host is billed separately. - Why: The upstream application runs in containers. - Get it: Install Docker Engine and the Compose plugin on Linux using the official instructions. On Windows use Docker Desktop with WSL2, then work inside a Linux project folder. - Verify: docker compose version prints a v2 version and docker info reaches the daemon. - [ ] **Choose and record the upstream release** · Software/edition terms and optional paid features are defined by the upstream project. - Why: The guide must match the software you actually deploy. - Get it: Open https://docs.n8n.io/deploy/host-n8n/install-options/install-with-docker, choose a stable release compatible with its database requirements, record its tag and resolved digest in versions.txt, and use those values in compose.yaml. Avoid unattended latest-tag updates. - Verify: versions.txt names both application and database versions or states that the pilot uses embedded SQLite. - [ ] **n8n Cloud acceptance sample** · No paid service required for this local step. - Why: This fixture makes the first end-to-end check reproducible. - Get it: Create synthetic sample data before implementation: A Manual Trigger to Edit Fields workflow producing hello plus a Schedule Trigger proof using no external account. Save it under fixtures/ with the expected results in fixtures/README.md; use no real credentials or customer records. - Verify: The fixture files and expected outcomes exist and can be inspected without a vendor account. - [ ] **Confirm the bounded replacement** · No paid service required for this local step. - Why: The full commercial product is larger than this guide. - Get it: The deliverable is an owner-operated n8n workflow instance with persistent credentials and tested recovery. Read every exclusion below. Indie mode runs locally; any public or shared use requires the product access and deployment gates first. - Verify: You can name the primary workflow and the vendor features this version deliberately leaves out. ## Quick start ```sh docker compose config --quiet ``` Then copy `.env.example` to `.env` and fill in the values it documents. ## Honest limits This build deliberately does not replace: - Workflow JSON alone is not a backup of credentials or execution data; changing to PostgreSQL does not copy old SQLite data. - This is an owner-operated n8n workflow instance with persistent credentials and tested recovery; full n8n Cloud feature parity, vendor hosting and support are not included. - managed hosting - backups - scaling - email support - reduced ops burden - team/admin features If one of those is essential to you, that is the reason to keep paying for n8n Cloud, and the README should say so rather than pretend.
BRIEF.md
# Build brief · n8n Cloud The one-shot brief this plan expands. `BUILD_PLAN.md` (or `MILESTONES.md`) is the same sequence broken into steps and checks; where the two disagree, the plan wins. Build me an owner-operated n8n workflow instance with persistent credentials and tested recovery as a bounded replacement for n8n Cloud. Build it in phases in the order below. Do not write the whole product in one pass. Finish the current phase, run its Done when checks, fix failures, then continue. Indie mode completes Phases 1-5. Phase 6 is required before shared or public deployment. ### Stack (fixed, do not substitute) - Application: Upstream n8n container. Reuse the maintained application; the work is deployment and operations. - Storage: Persistent upstream SQLite pilot volume. Use the upstream schema and keep data across container replacement. - Deployment: Docker Compose; Caddy for product HTTPS. Explicit volumes, ports and configuration can be reviewed and recreated. ### Data model (create this before Phase 1) - Use the upstream n8n schema. For the local pilot retain the entire /home/node/.n8n volume, including its SQLite database and encryption material - keep workflow exports and pinned image digest. Product mode must rehearse the documented PostgreSQL migration/export path rather than simply changing database settings. - Use stable ids and explicit relationships; add auxiliary tables named by the phases before those phases use them. - Acceptance fixture: A Manual Trigger to Edit Fields workflow producing hello plus a Schedule Trigger proof using no external account. ### Prerequisites and configuration - Docker Engine and Compose v2: Install Docker Engine and the Compose plugin on Linux using the official instructions. On Windows use Docker Desktop with WSL2, then work inside a Linux project folder. Verify: docker compose version prints a v2 version and docker info reaches the daemon. Cost: Docker Engine has no hosting fee; Desktop licensing depends on your use, and a rented host is billed separately. - Choose and record the upstream release: Open https://docs.n8n.io/deploy/host-n8n/install-options/install-with-docker, choose a stable release compatible with its database requirements, record its tag and resolved digest in versions.txt, and use those values in compose.yaml. Avoid unattended latest-tag updates. Verify: versions.txt names both application and database versions or states that the pilot uses embedded SQLite. Cost: Software/edition terms and optional paid features are defined by the upstream project. - n8n Cloud acceptance sample: Create synthetic sample data before implementation: A Manual Trigger to Edit Fields workflow producing hello plus a Schedule Trigger proof using no external account. Save it under fixtures/ with the expected results in fixtures/README.md; use no real credentials or customer records. Verify: The fixture files and expected outcomes exist and can be inspected without a vendor account. Cost: No paid service required for this local step. - Confirm the bounded replacement: The deliverable is an owner-operated n8n workflow instance with persistent credentials and tested recovery. Read every exclusion below. Indie mode runs locally; any public or shared use requires the product access and deployment gates first. Verify: You can name the primary workflow and the vendor features this version deliberately leaves out. Cost: No paid service required for this local step. - Configuration: APP_IMAGE, SITE_URL, GENERIC_TIMEZONE, TZ. Ship .env.example, replace placeholders and exclude secrets from git. ### Phase 1 · Deployment inventory and safe pilot Build: Prepare the pinned upstream deployment for an owner-operated n8n workflow instance with persistent credentials and tested recovery. - Read the linked upstream installation guide and create compose.yaml, .env.example, versions.txt and OPERATIONS.md. Map APP_IMAGE and only each service's required environment variables explicitly. Keep database ports internal and map the pilot application port to 127.0.0.1. - Use the upstream n8n schema. For the local pilot retain the entire /home/node/.n8n volume, including its SQLite database and encryption material; keep workflow exports and pinned image digest. Product mode must rehearse the documented PostgreSQL migration/export path rather than simply changing database settings. Name each volume and its mount path in OPERATIONS.md; never use ephemeral container storage for the only copy. Create .env manually from .env.example and replace placeholders before starting. Commands, after creating the named files: `docker compose config --quiet`. - Create a private fixtures/ folder containing: A Manual Trigger to Edit Fields workflow producing hello plus a Schedule Trigger proof using no external account. Create a separate backup destination and an isolated restore-project name; do not reuse live volumes in restore exercises. - Trap: A valid Compose file proves configuration syntax only, not application health. Done when: docker compose config --quiet succeeds with no unresolved required variables. The documented volume list includes every persistent asset and no secret is committed. Do not build yet: Do not start persistent local instance until these checks pass. ### Phase 2 · Persistent local instance Build: Persistent local instance for n8n Cloud: Deploy the official n8n image using Compose with a persistent /home/node/.n8n mount and a loopback mapping for port 5678. - Deploy the official n8n image using Compose with a persistent /home/node/.n8n mount and a loopback mapping for port 5678. - Create the owner account and retain the generated encryption material with restricted backups; disable optional AI/cloud features for this pilot. - Use A Manual Trigger to Edit Fields workflow producing hello plus a Schedule Trigger proof using no external account. Check: Restarting the container retains the owner account and a saved workflow. Then check: The editor is unreachable through a non-loopback host interface. Record commands, observed results and the date in OPERATIONS.md. - Trap: Follow upstream settings for the selected release; do not copy deprecated task-runner flags from old examples. Done when: Restarting the container retains the owner account and a saved workflow. The editor is unreachable through a non-loopback host interface. Do not build yet: Do not start useful workflow proof until these checks pass. ### Phase 3 · Useful workflow proof Build: Useful workflow proof for n8n Cloud: Build the Manual Trigger and Edit Fields proof, inspect output, then add a Schedule Trigger with the intended timezone. - Build the Manual Trigger and Edit Fields proof, inspect output, then add a Schedule Trigger with the intended timezone. - Export the workflow JSON and record its expected output; keep credentials in the n8n credential store, never in exported node parameters. - Use A Manual Trigger to Edit Fields workflow producing hello plus a Schedule Trigger proof using no external account. Check: The manual workflow produces the exact hello field. Then check: The scheduled proof runs at the documented timezone and appears in execution history. Record commands, observed results and the date in OPERATIONS.md. - Trap: An enabled schedule is an actual side effect; test only a harmless local workflow. Done when: The manual workflow produces the exact hello field. The scheduled proof runs at the documented timezone and appears in execution history. Do not build yet: Do not start recovery and upgrade until these checks pass. ### Phase 4 · Recovery and upgrade Build: Recovery and upgrade for n8n Cloud: Stop the local SQLite instance for a consistent complete volume backup and store encryption material securely alongside it. - Stop the local SQLite instance for a consistent complete volume backup and store encryption material securely alongside it. - Restore into a new isolated volume with schedules disabled, import or inspect the proof workflow and test before selecting a new image. - Use A Manual Trigger to Edit Fields workflow producing hello plus a Schedule Trigger proof using no external account. Check: The restored proof workflow runs and any test credential remains decryptable. Then check: The backup manifest includes the encryption material, image version and restore date. Record commands, observed results and the date in OPERATIONS.md. - Trap: Workflow JSON alone is not a backup of credentials or execution data; changing to PostgreSQL does not copy old SQLite data. Done when: The restored proof workflow runs and any test credential remains decryptable. The backup manifest includes the encryption material, image version and restore date. Do not build yet: Do not start portable delivery and clean-start proof until these checks pass. ### Phase 5 · Portable delivery and clean-start proof Build: Finish the n8n Cloud replacement with a documented first-run path and a recoverable export. - Document prerequisites, every configuration variable, data locations and the three domain workflows: Persistent local instance; Useful workflow proof; Recovery and upgrade. Include the exclusions, actual costs and source check date 2026-09-05. Commands shown earlier that reference project files are files the builder must implement before running them. - Stop the pilot service and back up its complete persistent volume including SQLite and encryption material; retain versioned workflow exports as a secondary aid. Restore into a separate empty directory or isolated deployment, with all outbound actions and schedules disabled. Recreate this proof: A Manual Trigger to Edit Fields workflow producing hello plus a Schedule Trigger proof using no external account. Compare ids/counts and open the result before recording the restore date. Never test a restore over the only live copy. - Use a new folder and only README instructions to reach the fixture outcome. Verify upstream login, persistence, proof output and restore. Record exactly what passed; do not mark unrun checks complete. Commands, after creating the named files: `docker compose ps`. - Trap: Export without an import or restore rehearsal is not verified portability. Done when: A new folder reaches the documented fixture outcome using only README instructions. A backup restored in isolation preserves the proof data and can be opened. Do not build yet: Do not start operate and share with access controls until these checks pass. ### Phase 6 · Operate and share with access controls (product-builder only) Build: Product-builder only: make an owner-operated n8n workflow instance with persistent credentials and tested recovery operable for its stated audience before allowing remote access. - Use upstream authentication, replace default credentials, restrict the editor/admin surface and inventory public ingestion/webhook paths. Review upstream edition and license boundaries before offering this as a service. - Put Caddy HTTPS in front of the upstream app, keep database and management ports private and configure public URLs from the chosen domain. For n8n, rehearse upstream PostgreSQL migration/import and recovery before claiming production readiness; disable any unused AI sandbox services. - Add a scheduled encrypted off-host backup using this procedure: Stop the pilot service and back up its complete persistent volume including SQLite and encryption material; retain versioned workflow exports as a secondary aid. Monitor health, disk space, failed jobs and backup age. Stop the service to test an alert; rehearse recovery with outbound effects disabled and record recovery time. Rotate any exposed credentials and require reconciliation before resuming queues. - Trap: Product mode is additional engineering, not a switch that makes a local prototype production-ready. Done when: An unauthenticated visitor cannot read private records, download private files or mutate the admin surface. A viewer cannot mutate data by making a direct request, and guessed ids cannot cross ownership boundaries. Stopping the service triggers the configured alert and the latest off-host backup restores the fixture in isolation. Do not build yet: Do not add new providers or vendor-scale features until the release gates are recorded. ### Out of scope (and why) - Workflow JSON alone is not a backup of credentials or execution data; changing to PostgreSQL does not copy old SQLite data. - This is an owner-operated n8n workflow instance with persistent credentials and tested recovery; full n8n Cloud feature parity, vendor hosting and support are not included. - managed hosting: retain the paid product if this capability is essential; it is outside this bounded build. - backups: retain the paid product if this capability is essential; it is outside this bounded build. - scaling: retain the paid product if this capability is essential; it is outside this bounded build. - email support: retain the paid product if this capability is essential; it is outside this bounded build. - reduced ops burden: retain the paid product if this capability is essential; it is outside this bounded build. - team/admin features: retain the paid product if this capability is essential; it is outside this bounded build. ### README must contain - Exact install, configure, initialize, start, test and recovery commands for a clean folder. - The schema, fixture, acceptance results, private data locations and export format. - Every prerequisite and secret source, actual running costs and deliberately excluded capabilities. - An honest distinction between tests actually run and checks still awaiting real credentials or deployment. - Dependency documentation reviewed 2026-09-05: https://docs.n8n.io/deploy/host-n8n/install-options/install-with-docker ; https://docs.n8n.io/deploy/host-n8n/install-options/install-using-docker-compose. Recheck before upgrading; freeze the versions actually tested.
AGENTS.md
# Agent instructions · n8n Cloud indie build - Read `README.md` and `BUILD_PLAN.md` before writing code. The stack is fixed: Upstream n8n container, Persistent upstream SQLite pilot volume, Docker Compose; Caddy for product HTTPS. Do not substitute. - Work one phase at a time, in order. Do not start a phase until every "Done when" item of the previous one passes. - Prefer the fewest moving parts that satisfy the step. No frameworks, services or dependencies the plan does not name. - Secrets live in `.env`, never in source or logs. Keep `.env.example` current when a variable is introduced. - Do not invent cryptography, security guarantees, APIs or compliance claims. - Add a focused test for every destructive, security-sensitive or data-loss path the plan names. - Run the project checks before declaring a phase complete, and record any deliberate shortcut in the README under "Tradeoffs". ## Known traps - A valid Compose file proves configuration syntax only, not application health. - Follow upstream settings for the selected release; do not copy deprecated task-runner flags from old examples. - An enabled schedule is an actual side effect; test only a harmless local workflow. - Workflow JSON alone is not a backup of credentials or execution data; changing to PostgreSQL does not copy old SQLite data. - Export without an import or restore rehearsal is not verified portability.
BUILD_PLAN.md
# Build plan · n8n Cloud Build an owner-operated n8n workflow instance with persistent credentials and tested recovery. Phases are in dependency order. Each ends in a "Done when" list; treat an unticked item as a blocker, not a note. ## Phase 1 · Deployment inventory and safe pilot Prepare the pinned upstream deployment for an owner-operated n8n workflow instance with persistent credentials and tested recovery. ### Steps 1. Create the deployment files Read the linked upstream installation guide and create compose.yaml, .env.example, versions.txt and OPERATIONS.md. Map APP_IMAGE and only each service's required environment variables explicitly. Keep database ports internal and map the pilot application port to 127.0.0.1. Files: `compose.yaml`, `.env.example`, `versions.txt` 2. Identify every persistent asset Use the upstream n8n schema. For the local pilot retain the entire /home/node/.n8n volume, including its SQLite database and encryption material; keep workflow exports and pinned image digest. Product mode must rehearse the documented PostgreSQL migration/export path rather than simply changing database settings. Name each volume and its mount path in OPERATIONS.md; never use ephemeral container storage for the only copy. Create .env manually from .env.example and replace placeholders before starting. Files: `OPERATIONS.md`, `.gitignore` ```sh docker compose config --quiet ``` 3. Prepare the proof and recovery folder Create a private fixtures/ folder containing: A Manual Trigger to Edit Fields workflow producing hello plus a Schedule Trigger proof using no external account. Create a separate backup destination and an isolated restore-project name; do not reuse live volumes in restore exercises. Files: `fixtures/README.md`, `OPERATIONS.md` ### Done when - [ ] docker compose config --quiet succeeds with no unresolved required variables. - [ ] The documented volume list includes every persistent asset and no secret is committed. ### Watch out - A valid Compose file proves configuration syntax only, not application health. ## Phase 2 · Persistent local instance Persistent local instance for n8n Cloud: Deploy the official n8n image using Compose with a persistent /home/node/.n8n mount and a loopback mapping for port 5678. ### Steps 1. Deploy the official n8n image using Compose with a persistent /home/node/.n8n mount and a loopback mapping for port 5678. Deploy the official n8n image using Compose with a persistent /home/node/.n8n mount and a loopback mapping for port 5678. Files: `compose.yaml`, `OPERATIONS.md` 2. Create the owner account and retain the generated encryption material with restricted backups; disable optional AI/cloud features for this pilot. Create the owner account and retain the generated encryption material with restricted backups; disable optional AI/cloud features for this pilot. Files: `OPERATIONS.md` 3. Exercise the acceptance fixture Use A Manual Trigger to Edit Fields workflow producing hello plus a Schedule Trigger proof using no external account. Check: Restarting the container retains the owner account and a saved workflow. Then check: The editor is unreachable through a non-loopback host interface. Record commands, observed results and the date in OPERATIONS.md. Files: `OPERATIONS.md` ### Done when - [ ] Restarting the container retains the owner account and a saved workflow. - [ ] The editor is unreachable through a non-loopback host interface. ### Watch out - Follow upstream settings for the selected release; do not copy deprecated task-runner flags from old examples. ## Phase 3 · Useful workflow proof Useful workflow proof for n8n Cloud: Build the Manual Trigger and Edit Fields proof, inspect output, then add a Schedule Trigger with the intended timezone. ### Steps 1. Build the Manual Trigger and Edit Fields proof, inspect output, then add a Schedule Trigger with the intended timezone. Build the Manual Trigger and Edit Fields proof, inspect output, then add a Schedule Trigger with the intended timezone. Files: `compose.yaml`, `OPERATIONS.md` 2. Export the workflow JSON and record its expected output; keep credentials in the n8n credential store, never in exported node parameters. Export the workflow JSON and record its expected output; keep credentials in the n8n credential store, never in exported node parameters. Files: `OPERATIONS.md` 3. Exercise the acceptance fixture Use A Manual Trigger to Edit Fields workflow producing hello plus a Schedule Trigger proof using no external account. Check: The manual workflow produces the exact hello field. Then check: The scheduled proof runs at the documented timezone and appears in execution history. Record commands, observed results and the date in OPERATIONS.md. Files: `OPERATIONS.md` ### Done when - [ ] The manual workflow produces the exact hello field. - [ ] The scheduled proof runs at the documented timezone and appears in execution history. ### Watch out - An enabled schedule is an actual side effect; test only a harmless local workflow. ## Phase 4 · Recovery and upgrade Recovery and upgrade for n8n Cloud: Stop the local SQLite instance for a consistent complete volume backup and store encryption material securely alongside it. ### Steps 1. Stop the local SQLite instance for a consistent complete volume backup and store encryption material securely alongside it. Stop the local SQLite instance for a consistent complete volume backup and store encryption material securely alongside it. Files: `compose.yaml`, `OPERATIONS.md` 2. Restore into a new isolated volume with schedules disabled, import or inspect the proof workflow and test before selecting a new image. Restore into a new isolated volume with schedules disabled, import or inspect the proof workflow and test before selecting a new image. Files: `OPERATIONS.md` 3. Exercise the acceptance fixture Use A Manual Trigger to Edit Fields workflow producing hello plus a Schedule Trigger proof using no external account. Check: The restored proof workflow runs and any test credential remains decryptable. Then check: The backup manifest includes the encryption material, image version and restore date. Record commands, observed results and the date in OPERATIONS.md. Files: `OPERATIONS.md` ### Done when - [ ] The restored proof workflow runs and any test credential remains decryptable. - [ ] The backup manifest includes the encryption material, image version and restore date. ### Watch out - Workflow JSON alone is not a backup of credentials or execution data; changing to PostgreSQL does not copy old SQLite data. ## Phase 5 · Portable delivery and clean-start proof Finish the n8n Cloud replacement with a documented first-run path and a recoverable export. ### Steps 1. Write the user-facing runbook Document prerequisites, every configuration variable, data locations and the three domain workflows: Persistent local instance; Useful workflow proof; Recovery and upgrade. Include the exclusions, actual costs and source check date 2026-09-05. Commands shown earlier that reference project files are files the builder must implement before running them. Files: `README.md`, `.env.example` 2. Create and rehearse a recoverable backup Stop the pilot service and back up its complete persistent volume including SQLite and encryption material; retain versioned workflow exports as a secondary aid. Restore into a separate empty directory or isolated deployment, with all outbound actions and schedules disabled. Recreate this proof: A Manual Trigger to Edit Fields workflow producing hello plus a Schedule Trigger proof using no external account. Compare ids/counts and open the result before recording the restore date. Never test a restore over the only live copy. Files: `OPERATIONS.md`, `backup/README.md` 3. Reproduce the first-run experience Use a new folder and only README instructions to reach the fixture outcome. Verify upstream login, persistence, proof output and restore. Record exactly what passed; do not mark unrun checks complete. Files: `README.md`, `verification.md` ```sh docker compose ps ``` ### Done when - [ ] A new folder reaches the documented fixture outcome using only README instructions. - [ ] A backup restored in isolation preserves the proof data and can be opened. ### Watch out - Export without an import or restore rehearsal is not verified portability. ## Not in this build - Workflow JSON alone is not a backup of credentials or execution data; changing to PostgreSQL does not copy old SQLite data. - This is an owner-operated n8n workflow instance with persistent credentials and tested recovery; full n8n Cloud feature parity, vendor hosting and support are not included. - managed hosting - backups - scaling - email support - reduced ops burden - team/admin features ## After v1, if you want it - Extend recovery and upgrade only after the fixture and recovery checks pass. - Before adding another integration, document its credentials, limits, cost and failure behavior with primary-source links.
.env.example
# Copy to .env and fill in. Never commit .env; this file documents it. # Required. Copy the exact application image reference selected from upstream into compose.yaml via this variable. APP_IMAGE=replace-with-tested-image-and-digest # Required. The loopback URL selected in compose.yaml; replace with your HTTPS origin only after completing product deployment. SITE_URL=http://localhost:5678 # Required. Set the intended workflow timezone in the n8n service; record it beside the schedule proof. GENERIC_TIMEZONE=UTC # Required. Container system timezone; keep it consistent with the intended pilot timezone. TZ=UTC
PRODUCT.md
# n8n Cloud · product brief ## Problem Because n8n itself is open source, the core cloud subscription can be replaced by self-hosting if you can own hosting, updates, and backups. ## Product outcome An operated version of an owner-operated n8n workflow instance with persistent credentials and tested recovery, with authorized access, restore evidence and honest scope limits. ## Target user A builder who needs a maintainable product foundation, not a one-off demo. ## Required capabilities - VPS or Docker host - domain/HTTPS - database/storage - backups - API credentials - update routine ## Explicit non-goals for v1 - Workflow JSON alone is not a backup of credentials or execution data; changing to PostgreSQL does not copy old SQLite data. - This is an owner-operated n8n workflow instance with persistent credentials and tested recovery; full n8n Cloud feature parity, vendor hosting and support are not included. - managed hosting - backups - scaling - email support - reduced ops burden - team/admin features ## Success criteria - Restarting the container retains the owner account and a saved workflow. - The manual workflow produces the exact hello field. - The restored proof workflow runs and any test credential remains decryptable. - A private-data authorization check passes using a second identity. - An off-host restore drill has a date, observed result and recovery time in OPERATIONS.md. - README names the excluded vendor capabilities and actual provider/hosting costs.
BRIEF.md
# Build brief · n8n Cloud The one-shot brief this plan expands. `BUILD_PLAN.md` (or `MILESTONES.md`) is the same sequence broken into steps and checks; where the two disagree, the plan wins. Build me an owner-operated n8n workflow instance with persistent credentials and tested recovery as a bounded replacement for n8n Cloud. Build it in phases in the order below. Do not write the whole product in one pass. Finish the current phase, run its Done when checks, fix failures, then continue. Indie mode completes Phases 1-5. Phase 6 is required before shared or public deployment. ### Stack (fixed, do not substitute) - Application: Upstream n8n container. Reuse the maintained application; the work is deployment and operations. - Storage: Persistent upstream SQLite pilot volume. Use the upstream schema and keep data across container replacement. - Deployment: Docker Compose; Caddy for product HTTPS. Explicit volumes, ports and configuration can be reviewed and recreated. ### Data model (create this before Phase 1) - Use the upstream n8n schema. For the local pilot retain the entire /home/node/.n8n volume, including its SQLite database and encryption material - keep workflow exports and pinned image digest. Product mode must rehearse the documented PostgreSQL migration/export path rather than simply changing database settings. - Use stable ids and explicit relationships; add auxiliary tables named by the phases before those phases use them. - Acceptance fixture: A Manual Trigger to Edit Fields workflow producing hello plus a Schedule Trigger proof using no external account. ### Prerequisites and configuration - Docker Engine and Compose v2: Install Docker Engine and the Compose plugin on Linux using the official instructions. On Windows use Docker Desktop with WSL2, then work inside a Linux project folder. Verify: docker compose version prints a v2 version and docker info reaches the daemon. Cost: Docker Engine has no hosting fee; Desktop licensing depends on your use, and a rented host is billed separately. - Choose and record the upstream release: Open https://docs.n8n.io/deploy/host-n8n/install-options/install-with-docker, choose a stable release compatible with its database requirements, record its tag and resolved digest in versions.txt, and use those values in compose.yaml. Avoid unattended latest-tag updates. Verify: versions.txt names both application and database versions or states that the pilot uses embedded SQLite. Cost: Software/edition terms and optional paid features are defined by the upstream project. - n8n Cloud acceptance sample: Create synthetic sample data before implementation: A Manual Trigger to Edit Fields workflow producing hello plus a Schedule Trigger proof using no external account. Save it under fixtures/ with the expected results in fixtures/README.md; use no real credentials or customer records. Verify: The fixture files and expected outcomes exist and can be inspected without a vendor account. Cost: No paid service required for this local step. - Confirm the bounded replacement: The deliverable is an owner-operated n8n workflow instance with persistent credentials and tested recovery. Read every exclusion below. Indie mode runs locally; any public or shared use requires the product access and deployment gates first. Verify: You can name the primary workflow and the vendor features this version deliberately leaves out. Cost: No paid service required for this local step. - Configuration: APP_IMAGE, SITE_URL, GENERIC_TIMEZONE, TZ. Ship .env.example, replace placeholders and exclude secrets from git. ### Phase 1 · Deployment inventory and safe pilot Build: Prepare the pinned upstream deployment for an owner-operated n8n workflow instance with persistent credentials and tested recovery. - Read the linked upstream installation guide and create compose.yaml, .env.example, versions.txt and OPERATIONS.md. Map APP_IMAGE and only each service's required environment variables explicitly. Keep database ports internal and map the pilot application port to 127.0.0.1. - Use the upstream n8n schema. For the local pilot retain the entire /home/node/.n8n volume, including its SQLite database and encryption material; keep workflow exports and pinned image digest. Product mode must rehearse the documented PostgreSQL migration/export path rather than simply changing database settings. Name each volume and its mount path in OPERATIONS.md; never use ephemeral container storage for the only copy. Create .env manually from .env.example and replace placeholders before starting. Commands, after creating the named files: `docker compose config --quiet`. - Create a private fixtures/ folder containing: A Manual Trigger to Edit Fields workflow producing hello plus a Schedule Trigger proof using no external account. Create a separate backup destination and an isolated restore-project name; do not reuse live volumes in restore exercises. - Trap: A valid Compose file proves configuration syntax only, not application health. Done when: docker compose config --quiet succeeds with no unresolved required variables. The documented volume list includes every persistent asset and no secret is committed. Do not build yet: Do not start persistent local instance until these checks pass. ### Phase 2 · Persistent local instance Build: Persistent local instance for n8n Cloud: Deploy the official n8n image using Compose with a persistent /home/node/.n8n mount and a loopback mapping for port 5678. - Deploy the official n8n image using Compose with a persistent /home/node/.n8n mount and a loopback mapping for port 5678. - Create the owner account and retain the generated encryption material with restricted backups; disable optional AI/cloud features for this pilot. - Use A Manual Trigger to Edit Fields workflow producing hello plus a Schedule Trigger proof using no external account. Check: Restarting the container retains the owner account and a saved workflow. Then check: The editor is unreachable through a non-loopback host interface. Record commands, observed results and the date in OPERATIONS.md. - Trap: Follow upstream settings for the selected release; do not copy deprecated task-runner flags from old examples. Done when: Restarting the container retains the owner account and a saved workflow. The editor is unreachable through a non-loopback host interface. Do not build yet: Do not start useful workflow proof until these checks pass. ### Phase 3 · Useful workflow proof Build: Useful workflow proof for n8n Cloud: Build the Manual Trigger and Edit Fields proof, inspect output, then add a Schedule Trigger with the intended timezone. - Build the Manual Trigger and Edit Fields proof, inspect output, then add a Schedule Trigger with the intended timezone. - Export the workflow JSON and record its expected output; keep credentials in the n8n credential store, never in exported node parameters. - Use A Manual Trigger to Edit Fields workflow producing hello plus a Schedule Trigger proof using no external account. Check: The manual workflow produces the exact hello field. Then check: The scheduled proof runs at the documented timezone and appears in execution history. Record commands, observed results and the date in OPERATIONS.md. - Trap: An enabled schedule is an actual side effect; test only a harmless local workflow. Done when: The manual workflow produces the exact hello field. The scheduled proof runs at the documented timezone and appears in execution history. Do not build yet: Do not start recovery and upgrade until these checks pass. ### Phase 4 · Recovery and upgrade Build: Recovery and upgrade for n8n Cloud: Stop the local SQLite instance for a consistent complete volume backup and store encryption material securely alongside it. - Stop the local SQLite instance for a consistent complete volume backup and store encryption material securely alongside it. - Restore into a new isolated volume with schedules disabled, import or inspect the proof workflow and test before selecting a new image. - Use A Manual Trigger to Edit Fields workflow producing hello plus a Schedule Trigger proof using no external account. Check: The restored proof workflow runs and any test credential remains decryptable. Then check: The backup manifest includes the encryption material, image version and restore date. Record commands, observed results and the date in OPERATIONS.md. - Trap: Workflow JSON alone is not a backup of credentials or execution data; changing to PostgreSQL does not copy old SQLite data. Done when: The restored proof workflow runs and any test credential remains decryptable. The backup manifest includes the encryption material, image version and restore date. Do not build yet: Do not start portable delivery and clean-start proof until these checks pass. ### Phase 5 · Portable delivery and clean-start proof Build: Finish the n8n Cloud replacement with a documented first-run path and a recoverable export. - Document prerequisites, every configuration variable, data locations and the three domain workflows: Persistent local instance; Useful workflow proof; Recovery and upgrade. Include the exclusions, actual costs and source check date 2026-09-05. Commands shown earlier that reference project files are files the builder must implement before running them. - Stop the pilot service and back up its complete persistent volume including SQLite and encryption material; retain versioned workflow exports as a secondary aid. Restore into a separate empty directory or isolated deployment, with all outbound actions and schedules disabled. Recreate this proof: A Manual Trigger to Edit Fields workflow producing hello plus a Schedule Trigger proof using no external account. Compare ids/counts and open the result before recording the restore date. Never test a restore over the only live copy. - Use a new folder and only README instructions to reach the fixture outcome. Verify upstream login, persistence, proof output and restore. Record exactly what passed; do not mark unrun checks complete. Commands, after creating the named files: `docker compose ps`. - Trap: Export without an import or restore rehearsal is not verified portability. Done when: A new folder reaches the documented fixture outcome using only README instructions. A backup restored in isolation preserves the proof data and can be opened. Do not build yet: Do not start operate and share with access controls until these checks pass. ### Phase 6 · Operate and share with access controls (product-builder only) Build: Product-builder only: make an owner-operated n8n workflow instance with persistent credentials and tested recovery operable for its stated audience before allowing remote access. - Use upstream authentication, replace default credentials, restrict the editor/admin surface and inventory public ingestion/webhook paths. Review upstream edition and license boundaries before offering this as a service. - Put Caddy HTTPS in front of the upstream app, keep database and management ports private and configure public URLs from the chosen domain. For n8n, rehearse upstream PostgreSQL migration/import and recovery before claiming production readiness; disable any unused AI sandbox services. - Add a scheduled encrypted off-host backup using this procedure: Stop the pilot service and back up its complete persistent volume including SQLite and encryption material; retain versioned workflow exports as a secondary aid. Monitor health, disk space, failed jobs and backup age. Stop the service to test an alert; rehearse recovery with outbound effects disabled and record recovery time. Rotate any exposed credentials and require reconciliation before resuming queues. - Trap: Product mode is additional engineering, not a switch that makes a local prototype production-ready. Done when: An unauthenticated visitor cannot read private records, download private files or mutate the admin surface. A viewer cannot mutate data by making a direct request, and guessed ids cannot cross ownership boundaries. Stopping the service triggers the configured alert and the latest off-host backup restores the fixture in isolation. Do not build yet: Do not add new providers or vendor-scale features until the release gates are recorded. ### Out of scope (and why) - Workflow JSON alone is not a backup of credentials or execution data; changing to PostgreSQL does not copy old SQLite data. - This is an owner-operated n8n workflow instance with persistent credentials and tested recovery; full n8n Cloud feature parity, vendor hosting and support are not included. - managed hosting: retain the paid product if this capability is essential; it is outside this bounded build. - backups: retain the paid product if this capability is essential; it is outside this bounded build. - scaling: retain the paid product if this capability is essential; it is outside this bounded build. - email support: retain the paid product if this capability is essential; it is outside this bounded build. - reduced ops burden: retain the paid product if this capability is essential; it is outside this bounded build. - team/admin features: retain the paid product if this capability is essential; it is outside this bounded build. ### README must contain - Exact install, configure, initialize, start, test and recovery commands for a clean folder. - The schema, fixture, acceptance results, private data locations and export format. - Every prerequisite and secret source, actual running costs and deliberately excluded capabilities. - An honest distinction between tests actually run and checks still awaiting real credentials or deployment. - Dependency documentation reviewed 2026-09-05: https://docs.n8n.io/deploy/host-n8n/install-options/install-with-docker ; https://docs.n8n.io/deploy/host-n8n/install-options/install-using-docker-compose. Recheck before upgrading; freeze the versions actually tested.
ARCHITECTURE.md
# Architecture · n8n Cloud ## Stack | Part | Choice | Why | | --- | --- | --- | | Application | Upstream n8n container | Reuse the maintained application; the work is deployment and operations. | | Storage | Persistent upstream SQLite pilot volume | Use the upstream schema and keep data across container replacement. | | Deployment | Docker Compose; Caddy for product HTTPS | Explicit volumes, ports and configuration can be reviewed and recreated. | ## Modules Each module has one owner concern and a documented way to replace it. | Module | Owns | How to replace it | | --- | --- | --- | | Data and identity | Use the upstream n8n schema. For the local pilot retain the entire /home/node/.n8n volume, including its SQLite database and encryption material; keep workflow exports and pinned image digest. Product mode must rehearse the documented PostgreSQL migration/export path rather than simply changing database settings. | Follow upstream migration procedures and verify a restored fixture before switching stores. | | Persistent local instance | Deploy the official n8n image using Compose with a persistent /home/node/.n8n mount and a loopback mapping for port 5678. | Keep the acceptance contract: Restarting the container retains the owner account and a saved workflow. Replace only this module after replaying its fixture; preserve ids and existing records. | | Useful workflow proof | Build the Manual Trigger and Edit Fields proof, inspect output, then add a Schedule Trigger with the intended timezone. | Keep the acceptance contract: The manual workflow produces the exact hello field. Replace only this module after replaying its fixture; preserve ids and existing records. | | Recovery and upgrade | Stop the local SQLite instance for a consistent complete volume backup and store encryption material securely alongside it. | Keep the acceptance contract: The restored proof workflow runs and any test credential remains decryptable. Replace only this module after replaying its fixture; preserve ids and existing records. | | Operations | Stop the pilot service and back up its complete persistent volume including SQLite and encryption material; retain versioned workflow exports as a secondary aid. | Change host or backup destination only after an isolated restore and authorization check. | ## Configuration Every runtime setting is an environment variable documented in `.env.example`, validated at startup, with a safe local default wherever one exists. - `APP_IMAGE` · required · Copy the exact application image reference selected from upstream into compose.yaml via this variable. - `SITE_URL` · required · The loopback URL selected in compose.yaml; replace with your HTTPS origin only after completing product deployment. - `GENERIC_TIMEZONE` · required · Set the intended workflow timezone in the n8n service; record it beside the schedule proof. - `TZ` · required · Container system timezone; keep it consistent with the intended pilot timezone. ## Production baseline - Security: least privilege, input validation at every boundary, secret redaction in logs, rate limits on abuse-prone paths, no invented security primitives. - Data: explicit schema and migrations, transactional writes where integrity matters, backup and restore procedures that have been exercised. - Integrations: adapters around third-party providers, idempotent webhook or job processing, bounded retries, timeouts. - Observability: structured logs with request or operation ids, an error-tracking hook, and health and readiness checks where a server exists. - Quality: unit tests for domain rules, integration tests at module boundaries, one end-to-end test of the critical path. ## Decision records For each dependency in the stack table, keep a short note: why it was chosen, its failure mode, and how it is replaced. Do not add infrastructure until a requirement in `PRODUCT.md` justifies it.
AGENTS.md
# Agent instructions · n8n Cloud product build - Read `PRODUCT.md` and `ARCHITECTURE.md` before changing code. The stack is fixed: Upstream n8n container, Persistent upstream SQLite pilot volume, Docker Compose; Caddy for product HTTPS. - Implement milestone by milestone from `MILESTONES.md`; keep each change reviewable and leave the application runnable at every commit. - Treat authentication, payments, encryption, imports, webhooks and destructive actions as high-risk boundaries when present. - Never invent cryptography or silently weaken a requirement to make a check pass. - Put every external service behind an interface with a deterministic fake for tests. - Add migrations and rollback or recovery notes for every persistent data change. - Log useful operational context without credentials, tokens, passwords or personal data. - Update documentation and run every check before completing a milestone. ## Known traps - A valid Compose file proves configuration syntax only, not application health. - Follow upstream settings for the selected release; do not copy deprecated task-runner flags from old examples. - An enabled schedule is an actual side effect; test only a harmless local workflow. - Workflow JSON alone is not a backup of credentials or execution data; changing to PostgreSQL does not copy old SQLite data. - Export without an import or restore rehearsal is not verified portability. - Product mode is additional engineering, not a switch that makes a local prototype production-ready.
MILESTONES.md
# Delivery milestones · n8n Cloud Estimated effort: **multi-day** for the indie phases; the production-only milestones add the trust and operability layer. ## M1 · Deployment inventory and safe pilot Prepare the pinned upstream deployment for an owner-operated n8n workflow instance with persistent credentials and tested recovery. ### Steps 1. Create the deployment files Read the linked upstream installation guide and create compose.yaml, .env.example, versions.txt and OPERATIONS.md. Map APP_IMAGE and only each service's required environment variables explicitly. Keep database ports internal and map the pilot application port to 127.0.0.1. Files: `compose.yaml`, `.env.example`, `versions.txt` 2. Identify every persistent asset Use the upstream n8n schema. For the local pilot retain the entire /home/node/.n8n volume, including its SQLite database and encryption material; keep workflow exports and pinned image digest. Product mode must rehearse the documented PostgreSQL migration/export path rather than simply changing database settings. Name each volume and its mount path in OPERATIONS.md; never use ephemeral container storage for the only copy. Create .env manually from .env.example and replace placeholders before starting. Files: `OPERATIONS.md`, `.gitignore` ```sh docker compose config --quiet ``` 3. Prepare the proof and recovery folder Create a private fixtures/ folder containing: A Manual Trigger to Edit Fields workflow producing hello plus a Schedule Trigger proof using no external account. Create a separate backup destination and an isolated restore-project name; do not reuse live volumes in restore exercises. Files: `fixtures/README.md`, `OPERATIONS.md` ### Done when - [ ] docker compose config --quiet succeeds with no unresolved required variables. - [ ] The documented volume list includes every persistent asset and no secret is committed. ### Watch out - A valid Compose file proves configuration syntax only, not application health. ## M2 · Persistent local instance Persistent local instance for n8n Cloud: Deploy the official n8n image using Compose with a persistent /home/node/.n8n mount and a loopback mapping for port 5678. ### Steps 1. Deploy the official n8n image using Compose with a persistent /home/node/.n8n mount and a loopback mapping for port 5678. Deploy the official n8n image using Compose with a persistent /home/node/.n8n mount and a loopback mapping for port 5678. Files: `compose.yaml`, `OPERATIONS.md` 2. Create the owner account and retain the generated encryption material with restricted backups; disable optional AI/cloud features for this pilot. Create the owner account and retain the generated encryption material with restricted backups; disable optional AI/cloud features for this pilot. Files: `OPERATIONS.md` 3. Exercise the acceptance fixture Use A Manual Trigger to Edit Fields workflow producing hello plus a Schedule Trigger proof using no external account. Check: Restarting the container retains the owner account and a saved workflow. Then check: The editor is unreachable through a non-loopback host interface. Record commands, observed results and the date in OPERATIONS.md. Files: `OPERATIONS.md` ### Done when - [ ] Restarting the container retains the owner account and a saved workflow. - [ ] The editor is unreachable through a non-loopback host interface. ### Watch out - Follow upstream settings for the selected release; do not copy deprecated task-runner flags from old examples. ## M3 · Useful workflow proof Useful workflow proof for n8n Cloud: Build the Manual Trigger and Edit Fields proof, inspect output, then add a Schedule Trigger with the intended timezone. ### Steps 1. Build the Manual Trigger and Edit Fields proof, inspect output, then add a Schedule Trigger with the intended timezone. Build the Manual Trigger and Edit Fields proof, inspect output, then add a Schedule Trigger with the intended timezone. Files: `compose.yaml`, `OPERATIONS.md` 2. Export the workflow JSON and record its expected output; keep credentials in the n8n credential store, never in exported node parameters. Export the workflow JSON and record its expected output; keep credentials in the n8n credential store, never in exported node parameters. Files: `OPERATIONS.md` 3. Exercise the acceptance fixture Use A Manual Trigger to Edit Fields workflow producing hello plus a Schedule Trigger proof using no external account. Check: The manual workflow produces the exact hello field. Then check: The scheduled proof runs at the documented timezone and appears in execution history. Record commands, observed results and the date in OPERATIONS.md. Files: `OPERATIONS.md` ### Done when - [ ] The manual workflow produces the exact hello field. - [ ] The scheduled proof runs at the documented timezone and appears in execution history. ### Watch out - An enabled schedule is an actual side effect; test only a harmless local workflow. ## M4 · Recovery and upgrade Recovery and upgrade for n8n Cloud: Stop the local SQLite instance for a consistent complete volume backup and store encryption material securely alongside it. ### Steps 1. Stop the local SQLite instance for a consistent complete volume backup and store encryption material securely alongside it. Stop the local SQLite instance for a consistent complete volume backup and store encryption material securely alongside it. Files: `compose.yaml`, `OPERATIONS.md` 2. Restore into a new isolated volume with schedules disabled, import or inspect the proof workflow and test before selecting a new image. Restore into a new isolated volume with schedules disabled, import or inspect the proof workflow and test before selecting a new image. Files: `OPERATIONS.md` 3. Exercise the acceptance fixture Use A Manual Trigger to Edit Fields workflow producing hello plus a Schedule Trigger proof using no external account. Check: The restored proof workflow runs and any test credential remains decryptable. Then check: The backup manifest includes the encryption material, image version and restore date. Record commands, observed results and the date in OPERATIONS.md. Files: `OPERATIONS.md` ### Done when - [ ] The restored proof workflow runs and any test credential remains decryptable. - [ ] The backup manifest includes the encryption material, image version and restore date. ### Watch out - Workflow JSON alone is not a backup of credentials or execution data; changing to PostgreSQL does not copy old SQLite data. ## M5 · Portable delivery and clean-start proof Finish the n8n Cloud replacement with a documented first-run path and a recoverable export. ### Steps 1. Write the user-facing runbook Document prerequisites, every configuration variable, data locations and the three domain workflows: Persistent local instance; Useful workflow proof; Recovery and upgrade. Include the exclusions, actual costs and source check date 2026-09-05. Commands shown earlier that reference project files are files the builder must implement before running them. Files: `README.md`, `.env.example` 2. Create and rehearse a recoverable backup Stop the pilot service and back up its complete persistent volume including SQLite and encryption material; retain versioned workflow exports as a secondary aid. Restore into a separate empty directory or isolated deployment, with all outbound actions and schedules disabled. Recreate this proof: A Manual Trigger to Edit Fields workflow producing hello plus a Schedule Trigger proof using no external account. Compare ids/counts and open the result before recording the restore date. Never test a restore over the only live copy. Files: `OPERATIONS.md`, `backup/README.md` 3. Reproduce the first-run experience Use a new folder and only README instructions to reach the fixture outcome. Verify upstream login, persistence, proof output and restore. Record exactly what passed; do not mark unrun checks complete. Files: `README.md`, `verification.md` ```sh docker compose ps ``` ### Done when - [ ] A new folder reaches the documented fixture outcome using only README instructions. - [ ] A backup restored in isolation preserves the proof data and can be opened. ### Watch out - Export without an import or restore rehearsal is not verified portability. ## M6 · Operate and share with access controls (production only) Product-builder only: make an owner-operated n8n workflow instance with persistent credentials and tested recovery operable for its stated audience before allowing remote access. ### Steps 1. Establish owner access before exposure Use upstream authentication, replace default credentials, restrict the editor/admin surface and inventory public ingestion/webhook paths. Review upstream edition and license boundaries before offering this as a service. Files: `ARCHITECTURE.md`, `OPERATIONS.md` 2. Deploy a monitored service Put Caddy HTTPS in front of the upstream app, keep database and management ports private and configure public URLs from the chosen domain. For n8n, rehearse upstream PostgreSQL migration/import and recovery before claiming production readiness; disable any unused AI sandbox services. Files: `Caddyfile`, `OPERATIONS.md` 3. Rehearse loss and recovery Add a scheduled encrypted off-host backup using this procedure: Stop the pilot service and back up its complete persistent volume including SQLite and encryption material; retain versioned workflow exports as a secondary aid. Monitor health, disk space, failed jobs and backup age. Stop the service to test an alert; rehearse recovery with outbound effects disabled and record recovery time. Rotate any exposed credentials and require reconciliation before resuming queues. Files: `OPERATIONS.md`, `release-checklist.md` ### Done when - [ ] An unauthenticated visitor cannot read private records, download private files or mutate the admin surface. - [ ] A viewer cannot mutate data by making a direct request, and guessed ids cannot cross ownership boundaries. - [ ] Stopping the service triggers the configured alert and the latest off-host backup restores the fixture in isolation. ### Watch out - Product mode is additional engineering, not a switch that makes a local prototype production-ready.
OPERATIONS.md
# Operations · n8n Cloud ## Backup Stop the pilot service and back up its complete persistent volume including SQLite and encryption material; retain versioned workflow exports as a secondary aid. ## Restore Restore into a separate empty directory or isolated deployment, with all outbound actions and schedules disabled. Recreate this proof: A Manual Trigger to Edit Fields workflow producing hello plus a Schedule Trigger proof using no external account. Compare ids/counts and open the result before recording the restore date. Never test a restore over the only live copy. Do a restore drill before the first real user, and write the date here when it passes. ## Monitoring Check HTTP availability, free disk, backup age and domain failures for Persistent local instance, Useful workflow proof, Recovery and upgrade. Alert without logging private payloads. ## Incident checklist Pause outbound jobs and public intake as appropriate, preserve redacted diagnostics, restore an isolated verified backup, rotate affected credentials and reconcile uncertain effects before reopening. 1. Contain the issue without destroying evidence or user data. 2. Record the timeline and affected scope. 3. Rotate exposed secrets and revoke compromised sessions or credentials. 4. Restore from a verified backup when needed. 5. Document the root cause, the remediation and the regression test. ## Release gate - [ ] Restarting the container retains the owner account and a saved workflow. - [ ] The manual workflow produces the exact hello field. - [ ] The restored proof workflow runs and any test credential remains decryptable. - [ ] A private-data authorization check passes using a second identity. - [ ] An off-host restore drill has a date, observed result and recovery time in OPERATIONS.md. - [ ] README names the excluded vendor capabilities and actual provider/hosting costs. ## Launch constraint Do not market omitted n8n Cloud capabilities as implemented. The non-goals in `PRODUCT.md` remain user-visible limitations until they are deliberately delivered.
.env.example
# Copy to .env and fill in. Never commit .env; this file documents it. # Required. Copy the exact application image reference selected from upstream into compose.yaml via this variable. APP_IMAGE=replace-with-tested-image-and-digest # Required. The loopback URL selected in compose.yaml; replace with your HTTPS origin only after completing product deployment. SITE_URL=http://localhost:5678 # Required. Set the intended workflow timezone in the n8n service; record it beside the schedule proof. GENERIC_TIMEZONE=UTC # Required. Container system timezone; keep it consistent with the intended pilot timezone. TZ=UTC
$ choose a build depth, inspect the files, then open the complete pack in your agent
They pay to avoid maintaining an automation server that their business workflows depend on.
xmanaged hosting
xbackups
xscaling
xemail support
xreduced ops burden
xteam/admin features
share on X ↗"I just replaced n8n Cloud ($27.73/mo) with one prompt"
Don't feel like building it? These folks already made it free.
Activepieces Community EditionA genuinely open-source workflow runner with a simpler one-container path.open source↗
AutomatischA smaller AGPL automation server for people who do not need n8n's entire ecosystem.open source↗
n8n Community EditionThe same workflow engine without the cloud bill; you inherit updates, backups, and uptime.free↗all 3 free alternatives to n8n Cloud →· no votes, no pay-to-list · just what's real
n8n Cloud pricing
| plan | monthly | annual (per mo) | what you get |
|---|---|---|---|
| community edition (self-hosted) | $0/workspace | $0/workspace | Unlimited workflows, steps and users in the software; hosting, database and operations are user-supplied. |
| starter (cloud) | $27.73/workspace | $23.11/workspace | 2,500 executions/month, 1 project, 5 concurrent executions, 2,300 AI credits/month, 7-day logs and 2.5 GB stored execution data. |
| pro (cloud) | $69.33/workspace | $57.77/workspace | 10,000 executions/month, 3 projects, 20 concurrent executions, up to 13,700 AI credits/month, 30-day logs and 25 GB stored execution data. |
| business (self-hosted) | — | $770.72/workspace | 40,000 executions/month, 6 projects and 30-day insights; self-hosting required. |
| enterprise | custom | — | Custom executions, unlimited projects, 200+ concurrency and up to 365-day insights. |
free tierno free n8n Cloud plan; Community Edition is free to self-host with unlimited workflows/users, but infrastructure is not included
billingStarter/Pro monthly + annual; Business published annual price; 14-day Business trial and no-card Starter/Pro trial; VAT/tax may apply
hidden costsAn execution is one complete workflow run regardless of steps. AI credits reset and expire monthly, cannot be carried over or purchased separately. Business overage is €4,000 (about $4,622.00) per additional 300,000 executions; no prorated refunds.
verified 2026-08-11 · source ↗
Is n8n Cloud free?
No free cloud plan, just a trial; self-hosting the open source core is free. Paid is Starter (Cloud) at $27.73/mo (checked 2026-08-11).
Vibecode n8n Cloud
Yes. A competent AI coding agent (Claude Code, Codex, Cursor) can build a usable personal n8n Cloud replacement in one session with the prompt on this page. It runs on your own machine or server with no subscription.
How much does n8n Cloud cost?
n8n Cloud costs about $27.73/month (Starter (Cloud), checked 2026-08-11), which is $332.76 per year. That's what you save by replacing it with one prompt.
What do I lose by replacing n8n Cloud?
Honestly: managed hosting; backups; scaling; email support; reduced ops burden; team/admin features. If any of those are load-bearing for you, keep paying.
Is there an open-source alternative to n8n Cloud?
Yes: Activepieces Community Edition (A genuinely open-source workflow runner with a simpler one-container path.) Automatisch (A smaller AGPL automation server for people who do not need n8n's entire ecosystem.) n8n Community Edition (The same workflow engine without the cloud bill; you inherit updates, backups, and uptime.) All 3 curated free alternatives are at vibecodeit.com/n8n-cloud/alternatives. The prompt is for when you want it exactly your way.