From 31010d5fc98174a0f2db106c84f8417721e0be9e Mon Sep 17 00:00:00 2001 From: Ricardo Stoklosa Date: Tue, 26 May 2026 15:08:22 -0300 Subject: [PATCH 01/15] feat: generate per-doc markdown files via docusaurus-plugin-llms Bump docusaurus-plugin-llms to 0.4.0 and enable generateMarkdownFiles so each doc page is exposed as a .md sibling. llms.txt links now point to those .md URLs (default addMdExtension behavior), which lets TagoDeploy and other consumers fetch the raw markdown for rendering. Preserves title and description front matter on generated files. --- docusaurus.config.ts | 2 ++ package-lock.json | 12 ++++++++---- package.json | 2 +- 3 files changed, 11 insertions(+), 5 deletions(-) diff --git a/docusaurus.config.ts b/docusaurus.config.ts index c9a61032..c2a8913d 100644 --- a/docusaurus.config.ts +++ b/docusaurus.config.ts @@ -110,6 +110,8 @@ const config: Config = { { generateLLMsTxt: true, generateLLMsFullTxt: true, + generateMarkdownFiles: true, + keepFrontMatter: ["title", "description"], docsDir: "docs", title: "TagoIO Docs", description: "Documentation for TagoIO IoT platform, TagoDeploy, TagoCore, TagoTiP, and the TagoIO API.", diff --git a/package-lock.json b/package-lock.json index 4c7f61eb..1748f3c9 100644 --- a/package-lock.json +++ b/package-lock.json @@ -30,7 +30,7 @@ "aws-cdk": "^2.1105.0", "aws-cdk-lib": "2.241.0", "constructs": "^10.0.0", - "docusaurus-plugin-llms": "^0.3.0", + "docusaurus-plugin-llms": "^0.4.0", "oxfmt": "^0.37.0", "oxlint": "^1.52.0", "source-map-support": "^0.5.21", @@ -12018,9 +12018,9 @@ } }, "node_modules/docusaurus-plugin-llms": { - "version": "0.3.0", - "resolved": "https://registry.npmjs.org/docusaurus-plugin-llms/-/docusaurus-plugin-llms-0.3.0.tgz", - "integrity": "sha512-JuADAJA2fjTv1U4XQUoIu1LyjISDzxFhRK5HbCZiHum4HlmdPwyx8NBXsi+LfdUyjK9acbZgazGsHPhdwEZs0g==", + "version": "0.4.0", + "resolved": "https://registry.npmjs.org/docusaurus-plugin-llms/-/docusaurus-plugin-llms-0.4.0.tgz", + "integrity": "sha512-jYlj2HJ5+gu7oJZuJ83Hk8KlB65YlZZ/7UpHXiL7Qr+qpNBkVocmt2Molc6F3HNr5RqcfhWD/98CvgyNztg/ow==", "dev": true, "license": "MIT", "dependencies": { @@ -12031,6 +12031,10 @@ "engines": { "node": ">=18.0" }, + "funding": { + "type": "github", + "url": "https://github.com/sponsors/rachfop" + }, "peerDependencies": { "@docusaurus/core": "^3.0.0" } diff --git a/package.json b/package.json index 6da27b32..e17213be 100644 --- a/package.json +++ b/package.json @@ -50,7 +50,7 @@ "aws-cdk": "^2.1105.0", "aws-cdk-lib": "2.241.0", "constructs": "^10.0.0", - "docusaurus-plugin-llms": "^0.3.0", + "docusaurus-plugin-llms": "^0.4.0", "oxfmt": "^0.37.0", "oxlint": "^1.52.0", "source-map-support": "^0.5.21", From 57e6692fbf4f682d8b2942924bfd202130874ce2 Mon Sep 17 00:00:00 2001 From: Ricardo Stoklosa Date: Fri, 29 May 2026 14:21:36 -0300 Subject: [PATCH 02/15] refactor: drop keepFrontMatter from llms plugin config --- docusaurus.config.ts | 1 - 1 file changed, 1 deletion(-) diff --git a/docusaurus.config.ts b/docusaurus.config.ts index a79a8b4e..20acd3a6 100644 --- a/docusaurus.config.ts +++ b/docusaurus.config.ts @@ -111,7 +111,6 @@ const config: Config = { generateLLMsTxt: true, generateLLMsFullTxt: true, generateMarkdownFiles: true, - keepFrontMatter: ["title", "description"], docsDir: "docs", title: "TagoIO Docs", description: "Documentation for TagoIO IoT platform, TagoDeploy, TagoCore, TagoTiP, and the TagoIO API.", From 7d7a11520c007fa56b9f5c024a4b1921bd54efbe Mon Sep 17 00:00:00 2001 From: Ricardo Stoklosa Date: Fri, 29 May 2026 14:36:18 -0300 Subject: [PATCH 03/15] revert: restore keepFrontMatter in llms plugin config --- docusaurus.config.ts | 1 + 1 file changed, 1 insertion(+) diff --git a/docusaurus.config.ts b/docusaurus.config.ts index 20acd3a6..a79a8b4e 100644 --- a/docusaurus.config.ts +++ b/docusaurus.config.ts @@ -111,6 +111,7 @@ const config: Config = { generateLLMsTxt: true, generateLLMsFullTxt: true, generateMarkdownFiles: true, + keepFrontMatter: ["title", "description"], docsDir: "docs", title: "TagoIO Docs", description: "Documentation for TagoIO IoT platform, TagoDeploy, TagoCore, TagoTiP, and the TagoIO API.", From ba311dd3662396af94fb323b18abe7e9fe1bf0b9 Mon Sep 17 00:00:00 2001 From: Ricardo Stoklosa Date: Fri, 29 May 2026 15:33:26 -0300 Subject: [PATCH 04/15] docs: add tagodeploy docs refresh design spec --- ...26-05-29-tagodeploy-docs-refresh-design.md | 131 ++++++++++++++++++ 1 file changed, 131 insertions(+) create mode 100644 docs/superpowers/specs/2026-05-29-tagodeploy-docs-refresh-design.md diff --git a/docs/superpowers/specs/2026-05-29-tagodeploy-docs-refresh-design.md b/docs/superpowers/specs/2026-05-29-tagodeploy-docs-refresh-design.md new file mode 100644 index 00000000..59f52a58 --- /dev/null +++ b/docs/superpowers/specs/2026-05-29-tagodeploy-docs-refresh-design.md @@ -0,0 +1,131 @@ +# TagoDeploy Docs Refresh — Design + +Date: 2026-05-29 + +## Problem + +The TagoDeploy product migrated from an HTMX/Alpine.js frontend to a React SPA and went +through a rebrand. The `tagodeploy` documentation in this Docusaurus site was written against +the old UI, so its terminology, screenshots, field names, and flows are outdated. + +Separately, the SPA (`tago-io/deploy`) added an in-app docs panel that fetches markdown from +`docs.tago.io` by slug. Its `packages/web/src/docs/registry.ts` references 30 slugs. 23 exist +upstream, 7 do not and currently rely on bundled local-fallback drafts. 8 further docs exist +upstream but the SPA never links them (orphans). + +## Goals + +1. Audit and fix the 23 existing SPA-linked docs against the running SPA. +2. Create the 7 missing docs by promoting the SPA local-fallback drafts upstream, then verifying. +3. Audit the 8 orphan docs and wire them into the SPA where matching UI exists. +4. Land docs changes as a PR in the docs repo; land SPA cleanup as a separate PR. + +## Non-Goals + +- Redesigning the docs information architecture beyond what the audit requires. +- Mass screenshot replacement (only 9 image refs exist; touch only if clearly wrong). +- Touching non-tagodeploy docs (tagocore, tagoio, api, tagotip). + +## Source of Truth + +- Running SPA: `http://localhost:5510` (docker compose, web container healthy). +- Seed account: `fully-loaded@seed.local` / `Tagodev14!` (all 11 webservice middlewares + mqtt + + docker, all optional services). Fallback: `loaded@seed.local`. +- API container is currently unhealthy; if a page fails to load, restart/inspect before assuming + a doc gap. + +## Slug Inventory + +### Existing, SPA-linked (23) — audit + fix + +`project/overview`, `project/accounts`, `project/limits`, `project/domains`, `project/backups`, +`project/bills/billing`, `project/configuration/integrations`, `project/analysis-runtime`, +`project/api`, `project/main-database`, `project/in-memory-database`, `project/system/version`, +`project/features/editing-features`, `project/deployments/history`, `project/deployments/logs`, +`project/management/collaborators`, `project/mqtt`, `project/mqtt/certificates`, +`project/mqtt/clients`, `project/mqtt/groups`, `project/mqtt/group-rules`, +`project/mqtt/pipelines`, `project/container/overview`. + +### Missing (7) — promote-then-verify from SPA local drafts + +| Slug | Draft source in deploy repo | +|---|---| +| `project/management/tokens` | `packages/web/src/docs/local/tagodeploy/project/management/tokens.md` | +| `project/mqtt/connections` | `.../local/tagodeploy/project/mqtt/connections.md` | +| `project/mqtt/instances` | `.../local/tagodeploy/project/mqtt/instances.md` | +| `project/container/instances` | `.../local/tagodeploy/project/container/instances.md` | +| `project/webservice/overview` | `.../local/tagodeploy/project/webservice/overview.md` | +| `project/webservice/settings` | `.../local/tagodeploy/project/webservice/settings.md` | +| `project/webservice/instances` | `.../local/tagodeploy/project/webservice/instances.md` | + +### Orphans (8+) — audit + wire-up + +`project/mqtt/acl-permissions`, `project/mqtt/credentials`, `project/mqtt/topic-mappings`, +`project/container/docker-image`, `project/container/environment-variables`, +`project/container/logs`, `project/container/network`, `project/container/runtime`, +`project/system/open-connectors`, `services/overview`, `services/middlewares`, +`services/middlewares/managing-middleware`, `tagodeploy` (index), `tagodeploy/new-project`. + +For each orphan: if the matching UI exists in the SPA, fix the doc and add a `DocsButton` +(register the slug in `registry.ts`). If the feature is gone (htmx-only), flag for deletion in +the PR description rather than silently removing. + +## Architecture (3 phases) + +### Phase 1 — SPA Survey (single browser, me) + +Walk every project route that maps to a doc with playwright, logged in as the seed account. +For each page capture: route, page headings, every form field (label, type, default, validation +text), buttons and primary actions, list/empty states, and product terminology. + +Output: `specs/spa-survey.md` in the docs worktree. This is the ground-truth artifact every +Phase 2 agent reads. No doc edits happen in this phase. + +### Phase 2 — Doc work (parallel subagents, no browser) + +One subagent per cluster. Each receives: its doc file list, `specs/spa-survey.md`, and the +`tagoio:writing-style` + `tagoio:tagobrand` conventions. Each agent audits/fixes existing docs, +promotes+verifies new docs (preserving the `slug:` frontmatter the registry expects), and audits +its orphans against the survey. + +| Cluster | Docs | +|---|---| +| Project core | overview, accounts, limits, domains, backups, billing, collaborators, tokens (new) | +| Services | analysis-runtime, api, main-database, in-memory-database | +| Deployments + system | deployments/history, deployments/logs, system/version, features/editing-features, configuration/integrations, system/open-connectors* | +| MQTT | mqtt, certificates, clients, groups, group-rules, pipelines, connections (new), instances (new), acl-permissions*, credentials*, topic-mappings* | +| Container | overview, instances (new), docker-image*, environment-variables*, logs*, network*, runtime* | +| Webservice | overview (new), settings (new), instances (new) | +| Top-level | index, new-project, services/overview*, services/middlewares*, managing-middleware* | + +`*` orphan, new = promote-from-draft. Clusters are independent: each owns disjoint files, +communicates only through the survey artifact, no shared mutable state. + +### Phase 3 — Verify + wire-up + cleanup + +- Spot-check a sample of fixed docs against the live SPA with playwright. +- Build docs (`pnpm build`) to catch broken links / frontmatter / sidebar errors. +- Wire orphan `DocsButton`s into the SPA where Phase 2 confirmed the UI exists; add slugs to + `registry.ts`. +- Remove the 7 promoted local fallbacks and their `TODO(docs):` lines from `registry.ts`. + +## Outputs + +- **Docs PR** — docs repo branch `docs/tagodeploy-spa-refresh`: all content edits, 7 new docs, + orphan fixes, `_category_.json` updates if nav changes, the spec + survey artifacts. +- **Deploy PR** — deploy repo branch: wire orphan DocsButtons, remove 7 local fallbacks + + `TODO(docs)` lines in `registry.ts`. Sequenced after the docs PR (depends on upstream existing). + +## Error Handling / Risks + +- Page fails to load -> check API container health before recording a gap. +- Draft contradicts live SPA -> SPA wins; rewrite the draft section. +- Orphan UI ambiguous (can't find the screen) -> flag in PR, do not wire, do not delete. +- Build failure -> fix frontmatter/links before opening the PR. + +## Testing + +- `pnpm build` passes (Docusaurus link + sidebar validation). +- Manual playwright spot-check: open each new doc's slug via the SPA docs panel against a local + docs build or confirm slug matches registry. +- PR description lists pages surveyed, docs changed/created, orphans wired vs flagged. From c5b7434e12d73af9a53a04769c3bfce0bb527d8b Mon Sep 17 00:00:00 2001 From: Ricardo Stoklosa Date: Fri, 29 May 2026 15:35:05 -0300 Subject: [PATCH 05/15] docs: add tagodeploy docs refresh implementation plan --- .../2026-05-29-tagodeploy-docs-refresh.md | 279 ++++++++++++++++++ 1 file changed, 279 insertions(+) create mode 100644 docs/superpowers/plans/2026-05-29-tagodeploy-docs-refresh.md diff --git a/docs/superpowers/plans/2026-05-29-tagodeploy-docs-refresh.md b/docs/superpowers/plans/2026-05-29-tagodeploy-docs-refresh.md new file mode 100644 index 00000000..72dbad5e --- /dev/null +++ b/docs/superpowers/plans/2026-05-29-tagodeploy-docs-refresh.md @@ -0,0 +1,279 @@ +# TagoDeploy Docs Refresh Implementation Plan + +> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking. + +**Goal:** Audit and fix the 23 existing SPA-linked tagodeploy docs against the running React SPA, create the 7 missing docs from the SPA local-fallback drafts, audit and wire up the 8 orphan docs, then land a docs PR and a separate SPA cleanup PR. + +**Architecture:** Three phases. Phase 1 captures ground-truth of every relevant SPA screen into `specs/spa-survey.md` via a single playwright browser. Phase 2 fans out one subagent per doc cluster to fix/create docs against that survey (no browser contention). Phase 3 verifies with `pnpm build`, wires orphan DocsButtons into the SPA, and removes the promoted local fallbacks. + +**Tech Stack:** Docusaurus (docs site), React SPA (`tago-io/deploy`, `packages/web`), playwright MCP, docker compose local stack. + +**Key paths:** +- Docs repo (this worktree): `/Users/ricardostoklosa/.superset/worktrees/docs/tago-deploy-v2` +- Deploy repo: `/Users/ricardostoklosa/.superset/worktrees/deploy/feat/docs-panel-forms` +- SPA: `http://localhost:5510`, login `fully-loaded@seed.local` / `Tagodev14!` +- Registry: `/packages/web/src/docs/registry.ts` +- Local drafts: `/packages/web/src/docs/local/tagodeploy/**` + +**Conventions:** Apply `tagoio:writing-style` (no em dashes, no emojis, no banned words) and `tagoio:tagobrand` to all prose. Frontmatter must match existing docs: `title`, `description`, `keywords`, `tags`, `slug`. The `slug:` value MUST equal the registry slug exactly. + +--- + +## Phase 1 — SPA Survey + +### Task 1: Confirm stack health and log in + +**Files:** +- Create: `specs/spa-survey.md` + +- [ ] **Step 1: Verify web + api reachable** + +Run: `curl -s -o /dev/null -w "%{http_code}\n" http://localhost:5510/` +Expected: `200`. If api unhealthy, run `docker compose restart api` from the deploy repo and wait for healthy. + +- [ ] **Step 2: Log into the SPA** + +Use playwright: navigate `http://localhost:5510`, sign in with `fully-loaded@seed.local` / `Tagodev14!`. Confirm a project list renders. + +- [ ] **Step 3: Create the survey skeleton** + +Create `specs/spa-survey.md` with one `## ` heading per slug in the inventory below (30 linked + orphans). Leave each section empty for now. + +- [ ] **Step 4: Commit** + +```bash +git add specs/spa-survey.md +git commit -m "docs: scaffold spa survey artifact" +``` + +### Task 2: Survey project core + services screens + +**Files:** +- Modify: `specs/spa-survey.md` + +- [ ] **Step 1: Walk each screen with playwright** + +For the `fully-loaded` project, open and record each of: project overview, accounts, limits, domains, backups, billing, collaborators, tokens, analysis-runtime, api, main-database, in-memory-database. + +- [ ] **Step 2: Capture per screen** + +Under each `## ` write: route path, page headings, every form field (label, input type, default, validation/help text), buttons and primary actions, list/empty states, exact product terminology. + +- [ ] **Step 3: Commit** + +```bash +git add specs/spa-survey.md +git commit -m "docs: survey project core and services screens" +``` + +### Task 3: Survey deployments, system, MQTT, container, webservice screens + +**Files:** +- Modify: `specs/spa-survey.md` + +- [ ] **Step 1: Walk each screen** + +Record: deployments history, deployments logs, system/version, features editing, integrations, open-connectors; mqtt overview, certificates, clients, groups, group-rules, pipelines, connections, instances, acl-permissions, credentials, topic-mappings; container overview, instances, docker-image, environment-variables, logs, network, runtime; webservice overview, settings, instances; services overview, middlewares, managing-middleware; project index, new-project flow. + +- [ ] **Step 2: Capture same fields as Task 2.** For any orphan screen that does not exist in the SPA, write `STATUS: NOT FOUND IN SPA` under its heading. + +- [ ] **Step 3: Commit** + +```bash +git add specs/spa-survey.md +git commit -m "docs: survey mqtt, container, webservice, and orphan screens" +``` + +--- + +## Phase 2 — Doc Work (one subagent per cluster) + +Each cluster task is dispatched to a fresh subagent. The subagent reads `specs/spa-survey.md`, the listed doc files, the matching local drafts (for new docs), and applies the writing-style + tagobrand skills. It does NOT use the browser. + +Shared rules for every Phase 2 task: +- Existing doc: rewrite outdated terminology, field names, flows to match the survey. Keep the `slug:` line unchanged. +- New doc (promote): copy the draft body, add full frontmatter (`title`, `description`, `keywords`, `tags`, `slug` = registry slug), reconcile every statement against the survey, fix mismatches. +- Orphan: if survey says NOT FOUND, do not edit content; instead append the slug to a running list in `specs/orphans-to-flag.md` with a one-line reason. If found, fix it and append the slug to `specs/orphans-to-wire.md`. + +### Task 4: Project core cluster + +**Files:** +- Modify: `docs/tagodeploy/project/index.md` (overview), `docs/tagodeploy/project/configuration/accounts.md`, `docs/tagodeploy/project/configuration/limits.md`, `docs/tagodeploy/project/management/domains.md`, `docs/tagodeploy/project/management/backups.md`, `docs/tagodeploy/project/management/billing.md`, `docs/tagodeploy/project/management/collaborators.md` +- Create: `docs/tagodeploy/project/management/tokens.md` (slug `/tagodeploy/project/management/tokens`, draft `/.../local/tagodeploy/project/management/tokens.md`) + +- [ ] **Step 1:** Dispatch subagent with shared rules + this file list. Verify each `slug:` matches the registry. +- [ ] **Step 2:** Confirm new `tokens.md` has full frontmatter and lives under `project/management/`. +- [ ] **Step 3: Commit** + +```bash +git add docs/tagodeploy/project +git commit -m "docs(tagodeploy): refresh project core docs and add tokens" +``` + +### Task 5: Services cluster + +**Files:** +- Modify: `docs/tagodeploy/project/project-services/analysis-runtime.md`, `.../api.md`, `.../main-database.md`, `.../in-memory-database.md` + +- [ ] **Step 1:** Dispatch subagent with shared rules + file list. +- [ ] **Step 2:** Verify slugs unchanged. +- [ ] **Step 3: Commit** + +```bash +git add docs/tagodeploy/project/project-services +git commit -m "docs(tagodeploy): refresh project services docs" +``` + +### Task 6: Deployments + system cluster + +**Files:** +- Modify: `docs/tagodeploy/project/management/deployments/history.md`, `.../deployments/logs.md`, `docs/tagodeploy/project/configuration/system/version.md`, `docs/tagodeploy/project/management/features.md`, `docs/tagodeploy/project/configuration/integrations.md`, `docs/tagodeploy/project/configuration/system/open-connectors.md` (orphan) + +- [ ] **Step 1:** Dispatch subagent. `open-connectors` follows orphan rule. +- [ ] **Step 2: Commit** + +```bash +git add docs/tagodeploy/project +git commit -m "docs(tagodeploy): refresh deployments, system, and integrations docs" +``` + +### Task 7: MQTT cluster + +**Files:** +- Modify: `docs/tagodeploy/services/mqtt/index.md` (overview), `.../certificates.md`, `.../clients.md`, `.../groups.md`, `.../group-rules.md`, `.../pipelines.md`, `.../acl-permissions.md` (orphan), `.../credentials.md` (orphan), `.../topic-mappings.md` (orphan) +- Create: `docs/tagodeploy/services/mqtt/connections.md` (slug `/tagodeploy/project/mqtt/connections`), `docs/tagodeploy/services/mqtt/instances.md` (slug `/tagodeploy/project/mqtt/instances`); drafts under `/.../local/tagodeploy/project/mqtt/` + +- [ ] **Step 1:** Dispatch subagent with shared rules + file list. New docs get full frontmatter and matching slugs. +- [ ] **Step 2:** Verify `connections.md` and `instances.md` exist with correct slugs. +- [ ] **Step 3: Commit** + +```bash +git add docs/tagodeploy/services/mqtt +git commit -m "docs(tagodeploy): refresh mqtt docs and add connections and instances" +``` + +### Task 8: Container cluster + +**Files:** +- Modify: `docs/tagodeploy/services/container/overview.md`, `.../docker-image.md` (orphan), `.../environment-variables.md` (orphan), `.../logs.md` (orphan), `.../network.md` (orphan), `.../runtime.md` (orphan) +- Create: `docs/tagodeploy/services/container/instances.md` (slug `/tagodeploy/project/container/instances`); draft `/.../local/tagodeploy/project/container/instances.md` + +- [ ] **Step 1:** Dispatch subagent with shared rules + file list. +- [ ] **Step 2:** Verify `instances.md` slug. +- [ ] **Step 3: Commit** + +```bash +git add docs/tagodeploy/services/container +git commit -m "docs(tagodeploy): refresh container docs and add instances" +``` + +### Task 9: Webservice cluster (all new) + +**Files:** +- Create: `docs/tagodeploy/services/webservice/_category_.json`, `docs/tagodeploy/services/webservice/overview.md` (slug `/tagodeploy/project/webservice/overview`), `.../settings.md` (slug `/tagodeploy/project/webservice/settings`), `.../instances.md` (slug `/tagodeploy/project/webservice/instances`); drafts under `/.../local/tagodeploy/project/webservice/` + +- [ ] **Step 1: Create the category file** + +```json +{ + "label": "Web Service", + "position": 3, + "collapsed": true +} +``` + +- [ ] **Step 2:** Dispatch subagent to promote the 3 drafts with full frontmatter + matching slugs, verified against the survey. +- [ ] **Step 3: Commit** + +```bash +git add docs/tagodeploy/services/webservice +git commit -m "docs(tagodeploy): add webservice overview, settings, and instances" +``` + +### Task 10: Top-level cluster + +**Files:** +- Modify: `docs/tagodeploy/getting-started/index.md`, `docs/tagodeploy/getting-started/new-project.md`, `docs/tagodeploy/services/index.md` (overview, orphan), `docs/tagodeploy/services/middlewares/index.md` (orphan), `docs/tagodeploy/services/middlewares/managing-middleware.md` (orphan) + +- [ ] **Step 1:** Dispatch subagent with shared rules + file list. +- [ ] **Step 2: Commit** + +```bash +git add docs/tagodeploy/getting-started docs/tagodeploy/services/index.md docs/tagodeploy/services/middlewares +git commit -m "docs(tagodeploy): refresh getting-started and services overview docs" +``` + +--- + +## Phase 3 — Verify, Wire-Up, Cleanup + +### Task 11: Build the docs site + +**Files:** none + +- [ ] **Step 1: Run the build** + +Run: `cd /Users/ricardostoklosa/.superset/worktrees/docs/tago-deploy-v2 && pnpm build` +Expected: build succeeds, no broken-link or frontmatter errors. Fix any reported issue in the offending doc and re-run. + +- [ ] **Step 2: Commit any fixes** + +```bash +git add -A +git commit -m "docs(tagodeploy): fix build errors from refresh" +``` + +### Task 12: Playwright spot-check of new/changed docs + +**Files:** none + +- [ ] **Step 1:** With `pnpm start` (or the build preview) running, open 3-4 representative slugs (one new webservice doc, one fixed mqtt doc, tokens, container instances) and confirm they render with correct content and headings. +- [ ] **Step 2:** Record the checked pages in the PR notes draft. + +### Task 13: Open the docs PR + +**Files:** none + +- [ ] **Step 1:** Push branch `docs/tagodeploy-spa-refresh`. Open PR using `tagoio:github` + `tagoio:pr-and-issue-descriptions` conventions. Body lists: pages surveyed, docs changed, 7 docs created, orphans wired vs flagged (from `specs/orphans-to-wire.md` / `specs/orphans-to-flag.md`), and the Risk (CIA) line. + +### Task 14: SPA wire-up + fallback cleanup (deploy repo, separate PR) + +**Files (deploy repo):** +- Modify: `packages/web/src/docs/registry.ts` +- Modify: components rendering the orphan screens (add `DocsButton slug={...}`) per `specs/orphans-to-wire.md` +- Delete: the 7 promoted files under `packages/web/src/docs/local/tagodeploy/**` + +- [ ] **Step 1: Create a branch in the deploy repo** + +```bash +cd /Users/ricardostoklosa/.superset/worktrees/deploy/feat/docs-panel-forms +git checkout -b docs/tagodeploy-registry-cleanup +``` + +- [ ] **Step 2: Remove the 7 `TODO(docs):` lines** in `registry.ts` for tokens, mqtt connections, mqtt instances, container instances, webservice overview/settings/instances (the slug entries stay). + +- [ ] **Step 3: Delete the 7 promoted local fallback files** under `packages/web/src/docs/local/tagodeploy/`. + +- [ ] **Step 4: Add registry entries + `DocsButton`s** for each wired orphan in `specs/orphans-to-wire.md`. + +- [ ] **Step 5: Verify the SPA builds** + +Run: `pnpm --filter web build` (or repo equivalent). Expected: pass. + +- [ ] **Step 6: Commit + open PR** + +```bash +git add -A +git commit -m "feat(web): wire orphan docs and drop promoted local fallbacks" +``` + +Open PR referencing the docs PR (cleanup depends on upstream docs existing on docs.tago.io). + +--- + +## Self-Review Notes + +- Spec coverage: goals 1-4 map to Tasks 4-10 (audit/create), 12 (verify), 13-14 (PRs and wire-up). Survey (1-3) feeds all content tasks. +- Slug consistency: every new doc lists its registry slug inline; matches `registry.ts` exactly. +- Orphan handling: routed through `specs/orphans-to-wire.md` / `specs/orphans-to-flag.md`, consumed by Tasks 13-14. +- Doc prose is intentionally not pre-written: it depends on the Phase 1 survey of live UI. From 9d58e1bb2df61c5c01ecba77024f0123990149c0 Mon Sep 17 00:00:00 2001 From: Ricardo Stoklosa Date: Fri, 29 May 2026 15:37:43 -0300 Subject: [PATCH 06/15] docs: scaffold spa survey artifact with overview capture --- specs/spa-survey.md | 90 +++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 90 insertions(+) create mode 100644 specs/spa-survey.md diff --git a/specs/spa-survey.md b/specs/spa-survey.md new file mode 100644 index 00000000..5282516a --- /dev/null +++ b/specs/spa-survey.md @@ -0,0 +1,90 @@ +# SPA Survey — TagoDeploy + +Ground-truth capture of the running React SPA, used by the docs-refresh Phase 2 agents. + +- App: `http://web.docs-panel-forms.orb.local/` +- Logged in via internal admin `http://api.docs-panel-forms.orb.local:8092/accounts` -> "Sign in as". +- Survey project: **Fully Loaded Project**, id `bb0000000000000000000004`, region us-east-1. +- Resource ids: docker `dd000000000000000000001c`, mqtt broker `dd000000000000000000001b`, + webservices `dd0000000000000000000010`-`dd000000000000000000001a` (AWS IoT, Chirpstack, + Everynet, Generic HTTPS, Loriot, MachineQ, Myriota, Senet, Sigfox, Tektelic, TTN). + +## Navigation structure (observed) + +Top nav: **Project** | **Apps** | command palette (Cmd+K) | project switcher | account menu. + +Project breadcrumb tabs: **Management** | **TagoIO & API** | one entry per webservice/docker/mqtt resource. + +Management sidebar: Overview, Collaborators, Deployments, Domains, Logs, Tokens, Bills. + +Each page header carries a "Read the docs ->" button (the in-app docs panel). + +Resource routes: +- `/projects/{id}/management/{overview|collaborators|deployments|domains|logs|tokens|bills}` +- `/projects/{id}/tago-io/features` +- `/projects/{id}/webservice/{wsId}/overview` +- `/projects/{id}/docker/{dockerId}/overview` +- `/projects/{id}/mqtt/{mqttId}/overview` + +--- + +## /tagodeploy/project/overview + +Route: `/projects/{id}/management/overview`. Header: "Project Overview". Subtitle: "Project status, +resource usage, and recent activity at a glance." Has Read-the-docs button. + +Content: +- Project card: avatar (FL), name, status badge ("Deploying"), Version (date e.g. 2026-02-25), + Created (date), Region (us-east-1). +- Domains panel: list of `https://{service}.{id}.tagoio.net` rows (TagoIO API, TagoIO Admin, + TagoIO SSE, ...), each with Copy URL; "View all 16 domains ->" link to domains page. +- Month-to-Date Spend card: dollar amount, "% vs. last month's pace", daily spend chart, month toggle. +- History section. +- "CPU Utilization - TagoIO" chart: series API / Main Database / In-Memory Database; time ranges + 1h/6h/12h/1d/3d/7d/30d; "No data available" empty state. +- "CPU & Memory Utilization - MQTT" chart: CPU / Memory series; same time ranges. +- Logs section: empty state "No logs yet / Logs from your project will appear here." +- Floating "pending deployment / Review & Deploy" button (deploy queue). + + + +## /tagodeploy/project/accounts +## /tagodeploy/project/limits +## /tagodeploy/project/domains +## /tagodeploy/project/backups +## /tagodeploy/project/bills/billing +## /tagodeploy/project/configuration/integrations +## /tagodeploy/project/analysis-runtime +## /tagodeploy/project/api +## /tagodeploy/project/main-database +## /tagodeploy/project/in-memory-database +## /tagodeploy/project/management/collaborators +## /tagodeploy/project/management/tokens +## /tagodeploy/project/deployments/history +## /tagodeploy/project/deployments/logs +## /tagodeploy/project/system/version +## /tagodeploy/project/features/editing-features +## /tagodeploy/project/system/open-connectors +## /tagodeploy/project/mqtt (overview) +## /tagodeploy/project/mqtt/certificates +## /tagodeploy/project/mqtt/clients +## /tagodeploy/project/mqtt/groups +## /tagodeploy/project/mqtt/group-rules +## /tagodeploy/project/mqtt/pipelines +## /tagodeploy/project/mqtt/connections +## /tagodeploy/project/mqtt/instances +## /tagodeploy/project/mqtt/acl-permissions +## /tagodeploy/project/mqtt/credentials +## /tagodeploy/project/mqtt/topic-mappings +## /tagodeploy/project/container/overview +## /tagodeploy/project/container/instances +## /tagodeploy/project/container/docker-image +## /tagodeploy/project/container/environment-variables +## /tagodeploy/project/container/logs +## /tagodeploy/project/container/network +## /tagodeploy/project/container/runtime +## /tagodeploy/project/webservice/overview +## /tagodeploy/project/webservice/settings +## /tagodeploy/project/webservice/instances +## services overview / middlewares / managing-middleware +## project index / new-project From d347e86bd18ca044ce0ecc7fc387243a50731670 Mon Sep 17 00:00:00 2001 From: Ricardo Stoklosa Date: Fri, 29 May 2026 15:52:55 -0300 Subject: [PATCH 07/15] docs: complete spa survey of all tagodeploy screens --- specs/spa-survey.md | 410 ++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 410 insertions(+) diff --git a/specs/spa-survey.md b/specs/spa-survey.md index 5282516a..50df3248 100644 --- a/specs/spa-survey.md +++ b/specs/spa-survey.md @@ -49,42 +49,452 @@ Content: ## /tagodeploy/project/accounts + +Found in the SPA under TagoIO & API. Route: `/projects/{id}/tago-io/accounts` (sidebar "Accounts & Profiles"). +Page header (h1): "Accounts". Card h2: "Account Management". Subtitle: "Browse the accounts in this project +and the profiles each one owns." Has "Read the docs →" button. Primary action: "New Account". +Controls: search box (placeholder "Search accounts..."), "Expand All", "Collapse All". +Empty state: "No accounts" / "No accounts found for this project." +New Account dialog (title "New Account", "Create a new account for your project."): fields "Name" +(placeholder "Full name"), "Email" (placeholder "email@example.com"), "Password" (password), "Company" +(placeholder "Company name"), "Country" (combobox "Select a country"). Buttons: "Cancel", "Confirm". ## /tagodeploy/project/limits + +Found in the SPA under TagoIO & API. Route: `/projects/{id}/tago-io/limits` (sidebar "Limits"). +Page header (h1): "Limits". Card h2: "Limits". Subtitle: "Configure resource quotas and rate limits for +this profile." Has "Read the docs →" button. Action: "Save". +Selectors: "ACCOUNT" (combobox "Select account"), "PROFILE" (combobox "Select profile"). After a profile +is chosen, a "Search limits..." box and limit groups appear (observed "10 Groups" of limits). ## /tagodeploy/project/domains + +Route: `/projects/{id}/management/domains`. Page header (h1): "Domains". Card title (h2): "View & Manage +Domains". Subtitle: "Custom and default domains for your project's services." Has "Read the docs →" button. +Primary action: "New Domain". + +Two sections: +- "Custom Domains" (h3): "External domains to use your own branding for project services." Empty state: + "No custom domains yet" / "Add a custom domain to use your own branding." +- "Default Domains" (h3): "Standard domains automatically assigned to your project for immediate access." + Table columns (sortable): **URL**, **Application**, **Endpoint**. Rows include TagoIO API/Admin/SSE + plus one per webservice/docker (Endpoint "API"), and the MQTT broker (`mqtts://...`, Endpoint "API"). + +New Domain dialog (title "New Domain"): 3-step wizard "Add domain progress" -> **1 Form**, **2 Review**, +**3 Records**. Step 1 fields: "Subdomain" (text, placeholder `e.g. api, portal, iot`), "Domain" (text, +placeholder `e.g. mycompany.com`), "Target" (combobox, default "Select a target service"). Buttons: +"Cancel", "Next". ## /tagodeploy/project/backups + +Route: `/projects/{id}/tago-io/backups` (sidebar "Backups" under TagoIO & API). Page header (h1) / card h2: +"Backups". Subtitle: "Snapshots of this project's database, created on a schedule." Has "Read the docs →" +button. Empty state: "No backups yet" / "Backup snapshots will appear here once they are created." +No create/add-backup action observed - backups are created on a schedule (configured via Main Database +"Daily backup schedule" / "Backup retention period"); this page only lists existing snapshots. ## /tagodeploy/project/bills/billing + +Route: `/projects/{id}/management/bills`. Page header (h1): "Bills" (also card h2 "Bills"). Subtitle: +"Monthly cost breakdown, charges, and payment status." Has "Read the docs →" button. + +Filters: "Filter by app" combobox (default "All apps"); "Period" combobox (default "May 2026", value `2026-05`). + +KPI cards: "Month-to-date" ($1,379.03, "-7.3% vs last month"); "Avg / Day" ($47.55, "Based on 29 days"); +"Last Month" ($1,487.00, "April 2026"). + +"Bill Summary" (h3): total amount; rows "Status" (Current cycle), "Payment" (—), "Due" (Jun 5, 2026, +labeled "Estimated"). + +"Cost History" (h3, "Breakdown by service"): toggle switches per service, all checked: Network, Files, +Platform License, Infrastructure, Main DB, Queue, Analysis, In-Memory DB, API, Apps. Stacked chart. + +"Daily Spend" (h3, "May 2026"): range toggle 7d / 14d / MTD. "By Service" (h3, "Top 5 services by cost") +bar chart. + +"Charges by Service" (h3): list of service rows with amounts (Apps, Platform License, API, Network, Main DB, +Infrastructure, In-Memory DB, Analysis, Files, Queue) and a "Total" row ($2,083.64). +Terminology note: service/cost categories are Network, Files, Platform License, Infrastructure, Main DB, +Queue, Analysis, In-Memory DB, API, Apps. ## /tagodeploy/project/configuration/integrations + +Found in the SPA under TagoIO & API. Route: `/projects/{id}/tago-io/integrations` (sidebar "Integrations"). +Page header (h1): "Integrations". Card h2: "Integrations Management". Subtitle: "Connect email and SMS +providers for outbound notifications." Has "Read the docs →" button. Action: "Save". +NOTE: this is email/SMS provider config, NOT open-connectors. +- "Email Settings": toggle "Enable emails" ("Allow the system to send transactional and notification + emails."); fields FROM ADDRESS (text), PROVIDER (combobox, default "SendGrid", value `sendgrid`), + API KEY (text, placeholder "Enter API key"). +- "SMS Settings": toggle "Enable SMS" ("Allow the system to send SMS notifications and alerts."); fields + FROM (text, placeholder "Phone number"), PROVIDER (combobox, default "Twilio", value `twilio`), + ACCOUNT SID (text, placeholder "Enter Account SID"), AUTHORIZATION TOKEN (text, placeholder "Enter Auth Token"). ## /tagodeploy/project/analysis-runtime + +Route: `/projects/{id}/tago-io/analysis-runtime` (sidebar "Analysis Runtime"). Page header (h1): +"Analysis Runtime". Card h2: "Analysis Runtime". Subtitle: "Set memory for the Node.js and Python scripts +that run your analyses." Has "Read the docs →" button. Action: "Save". +Two config groups: +- "Node.js Runtime" ("Memory allocation for Node.js analysis scripts."): field "Memory (MB)" (number, default 512). +- "Python Runtime" ("Memory allocation for Python analysis scripts."): field "Memory (MB)" (number, default 512). +"Monitoring" section: range toggle 1h/6h/12h/1d/3d/7d/30d; charts "Invocations" (COUNT), "Duration" (MS); +empty state "No data available". + ## /tagodeploy/project/api + +Found in the SPA under TagoIO & API. Route: `/projects/{id}/tago-io/api` (sidebar group "SERVICES" -> "API"). +Page header (h1): "API". Card h2: "API Service". Subtitle: "Set the machine size and autoscaling for +incoming API requests." Has "Read the docs →" button. Action: "Save". +"Instance settings" ("Configure machine type, scaling, and cooldown parameters."): +- "Machine" (combobox, default "1 vCPU / 2GB RAM", value `1vcpu_2gb`). +- "Minimum instances" (combobox/number, default 1). +- "Maximum instances" (combobox/number, default 1). +- "Scale on CPU utilization" (number, default 60). +- "Cooldown for scaling up" (number, default 200). +- "Cooldown for scaling down" (number, default 300). +"Monitoring": range toggle 1h/6h/12h/1d/3d/7d/30d; charts "CPU Utilization" (%), "Memory Utilization" (%); +empty "No data available". + +Sidebar nav for TagoIO & API: top group Features, Limits, Accounts & Profiles, Integrations, Backups, +System; group "SERVICES": API, Main Database, In-Memory Database, Analysis Runtime. + ## /tagodeploy/project/main-database + +Route: `/projects/{id}/tago-io/main-db` (sidebar "Main Database"). Page header (h1): "Main Database". +Card h2: "Main Database". Subtitle: "Configure your project's primary database." Has "Read the docs →" +button. Action: "Save". +"Database settings" section ("Configure machine type, read replicas, and backup parameters."): +- "Machine" (combobox, default "2 vCPU / 4GB RAM", value `2vcpu_4gb`). +- "Additional reader instances" (combobox, default 0). +- "Backup retention period (days)" (number input, default 7). +- "Daily backup schedule" (time input, default 04:30, labeled UTC). +"Monitoring": range toggle 1h/6h/12h/1d/3d/7d/30d; charts "CPU Utilization" (%), "Freeable Memory" (BYTES), +"Database Connections" (COUNT), "Read IOPS", "Write IOPS", "Network Throughput" (B/S); empty "No data available". + ## /tagodeploy/project/in-memory-database + +Route: `/projects/{id}/tago-io/in-memory-db` (sidebar "In-Memory Database"). Page header (h1): +"In-Memory Database". Card h2: "In-Memory Database". Subtitle: "Set the cache machine size and read +replicas." Has "Read the docs →" button. Action: "Save". +"Cache settings" section ("Configure machine type and read replicas."): +- "Machine" (combobox, default "2 vCPU / 1GB RAM", value `2vcpu_1gb`). +- "Additional reader replicas" (combobox, default 0). +"Monitoring": range toggle 1h/6h/12h/1d/3d/7d/30d; charts "CPU Utilization" (%), "Freeable Memory" (BYTES), +"Cache Hits" (COUNT), "Network Inbound" (B/S), "Network Outbound" (B/S); empty "No data available". ## /tagodeploy/project/management/collaborators + +Route: `/projects/{id}/management/collaborators` (query `?search=&page=1`). Page header (h1): "Collaborators". +Card title (h2): "Edit Project Collaborators". Subtitle: "People who can view and change this project's +resources." Has "Read the docs →" button. Primary action button: "Invite". +Empty state: "No collaborators yet" / "Invite team members to collaborate on this project." + +Invite dialog (title "Invite Collaborator", subtitle "Add a team member to this project"): +- Field "Email address" (text input, placeholder `user@example.com`). +- Field "Role" (combobox, default "Select a role"); options: **Admin**, **Contractor**. +- Buttons: "Cancel", "Send Invite". ## /tagodeploy/project/management/tokens + +Route: `/projects/{id}/management/tokens`. Page header (h1): "Tokens". Card title (h2): "Project API Tokens". +Subtitle: "Grant scripts and services programmatic access to this project." Has "Read the docs →" button. +Primary action button: "New Token". +Empty state: "No tokens yet" / "Create an API token to enable programmatic access to this project." + +New Token dialog (title "New Token"): no input fields. Body text: "This token will have full access to the +project and can be used with the API." Buttons: "Cancel", "Create". (Token presumably revealed after Create.) ## /tagodeploy/project/deployments/history + +Route: `/projects/{id}/management/deployments`. Page header (h1): "Deployments". Card title (h2): +"Manage Deployments". Subtitle: "Complete history of every deployment in this project." Has +"Read the docs →" button. +Controls: search box (placeholder "Search a deployment..."); status combobox (default "All"); "Select Date +Range" button. +List section titled "History" (with a refresh icon button). Table columns not rendered (empty). +Empty state: "No deployments yet" / "Deployment history will appear here once deployments are made." + ## /tagodeploy/project/deployments/logs + +Route: `/projects/{id}/management/logs`. Page header (h1): "Logs". Card title (h2): "View Logs". Subtitle: +"Runtime output from services running in this project." Has "Read the docs →" button. +Controls: search box (placeholder "Search logs..."); "Type" filter button; "Date" filter button; "Refresh" +button; "Live" toggle button. +Empty state: "No logs yet" / "Logs from your project will appear here." ## /tagodeploy/project/system/version + +Found on the System page. Route: `/projects/{id}/tago-io/system` (sidebar "System"). Page header (h1): +"System". This page hosts two sections: Version Timeline and Open Connectors. +Version Timeline card h2: "Version Timeline". Subtitle: "Pick the platform version this project runs." +Has "Read the docs →" button. Action: "Refresh". +- "Newer Versions" (count badge, e.g. 2): rows by date, e.g. 2026-05-25 tagged "Latest" with action + "Update"; 2026-04-21 action "Update". +- "Current Version": 2026-02-25 tagged "Current". +- "Older Versions" (count, e.g. 5): rows e.g. 2025-12-18, 2025-11-25, 2025-11-17, 2025-09-24, 2025-08-18, + each with action "Rollback". +Terminology: actions are Update (newer), Current, Rollback (older); tags "Latest"/"Current". ## /tagodeploy/project/features/editing-features + +Route: `/projects/{id}/tago-io/features` (the "TagoIO & API" breadcrumb tab lands here; sidebar "Features"; +URL gets `?view=simplified` appended). Page header (h1): "Features". +NOTE: on the survey project the page `
` rendered EMPTY (no field content) across reloads, so the +feature-toggle controls could not be captured here. The `?view=simplified` query suggests a +simplified/advanced view switch exists. The sidebar confirms this is the entry point of the TagoIO & API +section. STATUS: page reachable, but feature-toggle UI did not render for this seed (likely empty feature +set or load issue). ## /tagodeploy/project/system/open-connectors + +Found on the System page. Route: `/projects/{id}/tago-io/system` (sidebar "System"), second section below +Version Timeline. Section title "Open Connectors". Body: "External connectors routing data into your +TagoIO instance. Learn more about open connectors." (the "Learn more about open connectors" is a link). +Empty state: "No connectors synced yet". Action: "Sync connectors". +This is the open-connectors area (no separate `/configuration/integrations` route for it). ## /tagodeploy/project/mqtt (overview) + +Route: `/projects/{id}/mqtt/{mqttId}/overview`. Page header (h1): "Overview". Card h2: "Overview". +Subtitle: "Broker name, connection URL, and service controls." Has "Read the docs →" button. Action: +"Save" (disabled until changes). +MQTT sub-nav (sidebar): Overview, Instances, Settings, Clients, Groups, Groups Rules, Connections, +Pipelines, Certificates. (No ACL-permissions, Credentials, or Topic-mappings sub-pages exist.) +Sections: +- "Service Information" ("Name, URL, and product details for this service."): fields "Display Name" + (text, value "My MQTT Broker"), "Addon" (text, value "MQTT Broker"), "Service URL" (read-only, + `https://{mqttId}.{projectId}.tagoio.net`, with copy button). +- "Danger Zone" (collapsible, "Irreversible actions for this service"). ## /tagodeploy/project/mqtt/certificates + +Route: `/projects/{id}/mqtt/{mqttId}/certificates`. Page header (h1) / card h2: "Certificates". Subtitle: +"Provide TLS certificates to encrypt broker traffic and verify clients." Has "Read the docs →" button. +Action: "Save" (disabled until changes). Form (no dialog): +- Toggle "Enable Custom Certificate" ("Enable custom certificate") - on by default in this seed. +- Toggle "Enable MTLS" ("Enable mtls (require custom certificate)"). +- Textareas: "CA Certificate", "Server Certificate", "Server Key" (each with a copy/expand button). ## /tagodeploy/project/mqtt/clients + +Route: `/projects/{id}/mqtt/{mqttId}/clients` (query `?search=&page=1`). Page header (h1): "Clients". +Card h2: "Clients". Subtitle: "Credentials that devices use to authenticate with the broker." Has +"Read the docs →" button. Primary action: "New Client". Search box (placeholder "Search clients..."). +Table columns: **Client Name** (sortable), **Authentication**, **Actions** (per-row "Open menu"). +Authentication values seen: "Certificate", "Credentials". Footer: "Showing 1-5 of 5 clients" with pager. +New Client dialog (title "New Client", subtitle "Configure the credentials for your new client."): +- "Name" (text, placeholder "Client name"). +- "Authentication" (with info tooltip). Option block "Credentials" ("Enable authentication with username + and password. Can be paired with Certificate"): fields "Username" (placeholder "Enter username"), + "Password" (placeholder "Enter password"). +Buttons: "Cancel", "Create client". ## /tagodeploy/project/mqtt/groups + +Route: `/projects/{id}/mqtt/{mqttId}/groups`. Page header (h1): "Groups". Card h2: "Groups". Subtitle: +"Bundle ACL permissions that allow or deny access to topics." Has "Read the docs →" button. Primary +action: "New Group". Search box (placeholder "Search groups..."). +Table columns: **Name**, **Description**, **ACL Permissions** (e.g. "3 permissions"), actions column. +New Group dialog (title "New Group", subtitle "Group Details"): +- "Name" (text, placeholder "group name"). +- "Description" (text, placeholder "description of the group's purpose"). +- "ACL Permissions" (h4). Empty state: "No permissions configured" / "Add permissions to control + subscription and publishing access to topics." Button "Add permission". +- Each permission row has columns **Permission** (combobox, default "Allow", value `allow`), **Action** + (combobox, default "Subscribe", value `subscribe`), **Topic** (text, placeholder "topic"), and a remove + button. Button "New permission" adds more rows. +Buttons: "Cancel", "Create group". ## /tagodeploy/project/mqtt/group-rules + +Route: `/projects/{id}/mqtt/{mqttId}/group-rules`. Page header (h1) / card h2: "Group Rules". Subtitle: +"Assign clients to groups automatically based on matching conditions." Has "Read the docs →" button. +Actions: "Save" (disabled until changes), "New rule". +Inline editable rows (no dialog) with columns: +- **Match By** (combobox; options seen: "Certificate Fingerprint" `certificate_fingerprint`, + "MQTT Client ID" `mqtt_client_id`, "Client" `client_id`). +- **Value** (text input; placeholder varies: "SHA256:..." for fingerprint, "value to match" for client id; + for "Client" match-by it becomes a combobox to pick a client). +- **Groups** (multi-select chips; pick one or more group names like device-telemetry, device-commands, + service-full-access). +- Per-row remove button. +Footer: "3 rules configured". ## /tagodeploy/project/mqtt/pipelines + +Route: `/projects/{id}/mqtt/{mqttId}/pipelines`. Page header (h1) / card h2: "Pipelines". Subtitle: +"Forward incoming MQTT messages to external services." Has "Read the docs →" button. Primary action: +"New pipeline". Search box (placeholder "Search pipelines..."). +Table columns: **NAME** (sortable), **DESCRIPTION**, **STATUS** (e.g. "Active"), actions column. +Footer: "Showing 1-2 of 2 pipelines" with Previous/Next page buttons. +New Pipeline dialog (title "New Pipeline", subtitle "Configure the pipeline endpoint and authentication. +The API URL is automatically generated from your project settings."): +- "NAME" (text, placeholder "Pipeline name"). +- "DESCRIPTION" (text, placeholder "Describe this pipeline"). +- "API URL" (text, default "https://api.tagoio.net"). +- "NETWORK TOKEN" (text). +- "AUTHORIZATION TOKEN" (text). +Buttons: "Cancel", "Create pipeline". +NOTE: the "Topic Mappings" UI lives in a second section ON this same Pipelines page (see topic-mappings). ## /tagodeploy/project/mqtt/connections + +Route: `/projects/{id}/mqtt/{mqttId}/connections` (query `?search=&page=1`). Page header (h1) / card h2: +"Connections". Subtitle: "Live view of devices currently connected to the broker." Has "Read the docs →" +button. Read-only (no create action). Search box (placeholder "Search by client ID..."). +Table columns: **MQTT Client ID**, **IP Address**, **Protocol** (e.g. MQTT), **Keep-Alive** (e.g. 30s), +**Connected At** (sortable, UTC timestamp), **Group** (group id). Footer: "Showing 1–3 of 3 connections". ## /tagodeploy/project/mqtt/instances + +Route: `/projects/{id}/mqtt/{mqttId}/instances`. Page header (h1): "Overview". Card h2: "Instance Details". +Subtitle: "Set the machine size and autoscaling range for this service." Has "Read the docs →" button. +Action: "Save" (disabled until changes). +"Instance settings" ("Machine size, scaling range, and autoscaling thresholds."): +- "Machine" (combobox, default "1 vCPU / 2GB RAM", value `1vcpu_2gb`). +- "Minimum Instances" (combobox, default 1). +- "Maximum Instances" (combobox, default 2). +- "Scale on CPU Utilization" (number, default 60). +- "Cooldown for Scaling Up" (number, default 200). +- "Cooldown for Scaling Down" (number, default 300). +"Monitoring": range toggle 1h/6h/12h/1d/3d/7d/30d; charts "CPU Utilization (%)", "Memory Utilization (%)"; +empty "No data available". ## /tagodeploy/project/mqtt/acl-permissions + +STATUS: NOT FOUND. No dedicated sub-page. "ACL permissions" exist only as a concept inside Groups: each +group bundles ACL permission rows (Permission Allow/Deny, Action Subscribe/Publish, Topic). See +`/tagodeploy/project/mqtt/groups`. + ## /tagodeploy/project/mqtt/credentials + +STATUS: NOT FOUND. No dedicated sub-page. "Credentials" is one of the client Authentication types +(username/password) configured in the New Client dialog. See `/tagodeploy/project/mqtt/clients`. + +(Note: the MQTT sub-nav also has a "Settings" sub-page at `/mqtt/{mqttId}/settings`, not in this heading +list and not surveyed.) ## /tagodeploy/project/mqtt/topic-mappings + +No dedicated route. Rendered as a second section on the Pipelines page +(`/projects/{id}/mqtt/{mqttId}/pipelines`). Section h2: "Topic Mappings". Subtitle: "Route MQTT topics to +specific pipelines." Actions: "Save" (disabled until changes), "New mapping". +Inline editable table (no dialog) columns: **TOPIC** (text input, placeholder "/topic", e.g. +`devices/+/telemetry`), **PIPELINE** (combobox selecting a pipeline by name), per-row remove button. ## /tagodeploy/project/container/overview + +Resource type label: "Custom Docker" (breadcrumb "My Custom Docker"). Route: +`/projects/{id}/docker/{dockerId}/overview`. Page header (h1): "Overview". Card h2: "Overview". Subtitle: +"Service name, URL, and product for this container." Has "Read the docs →" button. Action: "Save" +(disabled until changes). +Container sub-nav (sidebar): Overview, Instances, Settings only. (No separate docker-image, +environment-variables, logs, network, or runtime sub-pages; see those headings below.) +Sections: +- "Service Information" ("Name, URL, and product details for this service."): "Display Name" (text, + "My Custom Docker"), "Addon" (text, "Custom Docker"), "Service URL" (read-only + `https://{dockerId}.{projectId}.tagoio.net`, copy button). +- "Danger Zone" (collapsible, "Irreversible actions for this service"). ## /tagodeploy/project/container/instances + +Route: `/projects/{id}/docker/{dockerId}/instances`. Page header (h1): "Overview". Card h2: +"Instance Details". Subtitle: "Set the machine size and autoscaling range for this service." Has +"Read the docs →" button. Action: "Save" (disabled until changes). +"Instance settings" ("Machine size, scaling range, and autoscaling thresholds."): identical fields to the +MQTT instances page - "Machine" (combobox, default "1 vCPU / 2GB RAM", `1vcpu_2gb`), "Minimum Instances" +(default 1), "Maximum Instances" (default 2), "Scale on CPU Utilization" (default 60), "Cooldown for +Scaling Up" (default 200), "Cooldown for Scaling Down" (default 300). +"Monitoring": range toggle 1h/6h/12h/1d/3d/7d/30d; charts "CPU Utilization (%)", "Memory Utilization (%)"; +empty "No data available". ## /tagodeploy/project/container/docker-image + +No dedicated route. Lives as collapsible sections on the container Settings page +(`/projects/{id}/docker/{dockerId}/settings`). Page header (h1) / card h2: "Docker Settings". Subtitle: +"How this container is built, configured, and run." Has "Read the docs →" button. Action: "Save" +(disabled until changes). Settings page collapsible sections in order: Docker Image, Registry +Authentication, Environment Variables, Network, Runtime. +- "Docker Image" ("Configure the Docker image for your container deployment."): "Image Name" (text, + placeholder "The name of the Docker image to use."), "Image Tag" (text, placeholder "The tag of the + Docker image to use."). +- "Registry Authentication" ("Credentials for private Docker registries."): "Registry Username" (text, + placeholder "Username for the Docker registry."), "Registry Access Password" (password, placeholder + "Access password for the Docker registry.", with reveal toggle). + ## /tagodeploy/project/container/environment-variables + +No dedicated route. "Environment Variables" collapsible section on the container Settings page. Body: +"Environment variables passed to your container." Empty state: "No environment variables configured". +Button "Add variable" (adds key/value rows). ## /tagodeploy/project/container/logs + +STATUS: NOT FOUND. The container resource has no Logs sub-page (sub-nav is only Overview, Instances, +Settings). Project-wide runtime logs live at the Management > Logs page (`/management/logs`). + ## /tagodeploy/project/container/network + +No dedicated route. "Network" collapsible section on the container Settings page. Body: "Network protocol +and port mappings for the load balancer." Fields: +- "Network protocol" (combobox, default "TCP", value `tcp`). +- "Port mappings": empty state "No port mappings configured"; button "Add port" (adds port-mapping rows). + ## /tagodeploy/project/container/runtime + +No dedicated route. "Runtime" collapsible section on the container Settings page. Body: "Override the +default work directory and command." Fields: "Work Directory" (text, placeholder "Working directory for +the container."), "Command" (text, placeholder "Command to run in the container."). ## /tagodeploy/project/webservice/overview + +Route: `/projects/{id}/webservice/{wsId}/overview`. Surveyed on Chirpstack (dd...0011, breadcrumb +"My Chirpstack"). Page header (h1): "Overview". Card h2: "Overview". Subtitle: "Service name, endpoint URL, +and quick actions." Has "Read the docs →" button. Action: "Save" (disabled until changes). +Webservice sub-nav (sidebar): Overview, Instances, Settings. +TERMINOLOGY: a webservice's "Addon" reads "Middleware {Type}" (e.g. "Middleware Chirpstack"); webservices +are surfaced to users as middlewares. +Sections: +- "Service Information" ("Name, URL, and product details for this service."): "Display Name" (text, + "My Chirpstack"), "Addon" (text, "Middleware Chirpstack"), "Service URL" (read-only + `https://{wsId}.{projectId}.tagoio.net`, copy button). +- "Danger Zone" (collapsible, "Irreversible actions for this service"). ## /tagodeploy/project/webservice/settings + +Route: `/projects/{id}/webservice/{wsId}/settings`. Page header (h1) / card h2: "Webservice Settings". +Subtitle: "Network, API endpoint, and credential settings for the service." Has "Read the docs →" button. +Action: "Save" (disabled until changes). +"Configuration" section ("Credentials and endpoints used by this middleware."): +- "Network Token": a network combobox (placeholder "Select a network") with a "Refresh networks" button, + plus a toggle "Use custom token (advanced)" that reveals a manual token text field. +- "TagoIO Api URL" (text, default `https://api.{projectId}.tagoio.net`). + ## /tagodeploy/project/webservice/instances + +Route: `/projects/{id}/webservice/{wsId}/instances`. Page header (h1): "Overview". Card h2: +"Instance Details". Subtitle: "Set the machine size and autoscaling range for this service." Has +"Read the docs →" button. Action: "Save" (disabled until changes). Same instance-settings form as MQTT and +container instances pages: "Machine" (default "1 vCPU / 2GB RAM", `1vcpu_2gb`), "Minimum Instances" (1), +"Maximum Instances" (2), "Scale on CPU Utilization" (60), "Cooldown for Scaling Up" (200), "Cooldown for +Scaling Down" (300). "Monitoring": range toggle 1h/6h/12h/1d/3d/7d/30d; charts "CPU Utilization (%)", +"Memory Utilization (%)"; empty "No data available". ## services overview / middlewares / managing-middleware + +Entry point is the **App Catalog** at `/apps` (top-nav "Apps"). There is NO add-service "+" on the project +breadcrumb resource list or in the command palette (palette is navigation-only). Services are added from +the catalog. +App Catalog (h1 "App Catalog"): left rail filters — CATEGORIES: Any Type, Platform, Middleware, MQTT, +Others; NETWORKS: AWS, Chirpstack, Everynet, Loriot, MachineQ, Myriota, Senet, Sigfox. Search box +("What are you looking for?"). Sections "Featured" and "Recently Added". +Catalog items (each card has a category badge): +- "TagoIO Platform" (Platform). +- Middlewares (the webservice connector types): AWS IoT, Chirpstack, Everynet, Generic HTTPS, Loriot, + MachineQ, Myriota, Senet, Sigfox, Tektelic, TTN. +- "Broker" (MQTT). +TERMINOLOGY: webservice connectors are surfaced as "Middleware"; in-project label is "Middleware {Type}". + +Add flow (click a catalog card -> detail dialog -> "Next"): +- Detail dialog (e.g. "Chirpstack"): CATEGORY (Middleware), ABOUT (Created / Updated dates), "Overview" + description, "Features:" bullet list. Buttons "Back", "Next". +- Install dialog (title "Middleware {Type}"): "Installation" radio group — **In a project** ("Easy + integration within your TagoIO project", subtitle "Adding to Project") vs **New Project** ("Use with a + TagoIO project or with a separate application", subtitle "Creating a New Project"). + - In a project: fields "Project" (combobox "Select a project"), "Region" (combobox "Select a region"), + "Version" (combobox, default "v4.0 (Latest)"). Action button "Add to Project". + - New Project: same minus the Project field (Region + Version). Action button "Review and Install". + - "Settings": "Name" (text, default "My Middleware {Type}"), "Network Token" (text, placeholder + "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"), "TagoIO Api URL" (text, placeholder "https://..."). + - "Specifications" (read-only): service "Middleware api", TYPE "api", INSTANCES "1 - 5". + Buttons: "Back" + the contextual install action. ## project index / new-project + +PROJECT LISTING: via the top-nav project switcher (button showing avatar + project name + region). The +dropdown has a "Projects" group; each row shows avatar, name, a "Current" badge for the active project, +and "{region} · {role}" (e.g. "us-east-1 · Owner"). A "New project" button sits at the bottom of the +dropdown. There is no standalone /projects index page; `/apps` is the App Catalog (see services section). + +NEW PROJECT FLOW: "New project" (and the catalog's "TagoIO Platform" card) opens the TagoIO Platform +install dialog, which is what provisions a project. +- Detail dialog "TagoIO Platform": CATEGORY (Platform), ABOUT (Created / Updated dates), "Overview" + description. Buttons "Back", "Next". +- Install dialog (title "TagoIO Platform", subtitle "Creating TagoIO Platform Project"): + - "Installation" radio group: "In a project" is DISABLED ("Coming soon"); "New Project" is selected by + default for the Platform. + - "Region" (combobox, "Select a region"). + - "Version" (combobox, default "2026-05-25 (Latest)"). + - "Settings" -> "Name" (text, default "My TagoIO Platform"). + Buttons: "Back", "Next" (then proceeds to review/install). From 8ef2d9135e116a7ad7f52aa5146fb2db739b89b1 Mon Sep 17 00:00:00 2001 From: Ricardo Stoklosa Date: Fri, 29 May 2026 16:01:21 -0300 Subject: [PATCH 08/15] docs(tagodeploy): refresh project core docs and add tokens --- .../project/configuration/accounts.md | 100 ++++++------- .../project/configuration/limits.md | 75 +++++----- docs/tagodeploy/project/index.md | 72 ++++++---- docs/tagodeploy/project/management/backups.md | 106 ++++++-------- docs/tagodeploy/project/management/billing.md | 136 +++++++----------- .../project/management/collaborators.md | 34 +++-- docs/tagodeploy/project/management/domains.md | 96 +++++-------- docs/tagodeploy/project/management/tokens.md | 43 ++++++ 8 files changed, 309 insertions(+), 353 deletions(-) create mode 100644 docs/tagodeploy/project/management/tokens.md diff --git a/docs/tagodeploy/project/configuration/accounts.md b/docs/tagodeploy/project/configuration/accounts.md index 4d7c8ef9..a3700ad9 100644 --- a/docs/tagodeploy/project/configuration/accounts.md +++ b/docs/tagodeploy/project/configuration/accounts.md @@ -1,82 +1,62 @@ --- title: "TagoIO Admin Accounts" -description: "Manage developer accounts for TagoIO Admin: create, edit, deactivate, and understand profile sharing." +description: "Manage developer accounts for the TagoIO Admin console: create, edit, and delete accounts." keywords: [tagodeploy, iot, accounts, admin, user management] tags: ["tagodeploy", "accounts"] slug: /tagodeploy/project/accounts --- -The Accounts section provides a centralized interface for managing all developer -accounts within your project's TagoIO Admin console. Through this interface, -TagoDeploy administrators can view, create, modify, and remove developer -accounts, as well as monitor account status, login activity, and creation dates. -Each account represents an individual user who has been granted administrative -privileges within the TagoIO Admin environment, with no limit on the number of -accounts that can be added to a project. +# Accounts + +The **Accounts** page manages developer accounts in your project's TagoIO Admin +console. You find it in the TagoIO & API section, under "Accounts & Profiles" +in the sidebar, at `/projects/{id}/tago-io/accounts`. From here you can browse +the accounts in the project and the profiles each one owns, and you can create +new accounts. + +Each account represents an individual user with access to the TagoIO Admin +environment. There is no limit on the number of accounts you can add to a +project. To learn more about what TagoIO developers can access through the Admin console, visit the [TagoIO Help Center](https://help.tago.io/portal/en/kb/articles/211-editing-accounts-details). -When a new account is added, the user receives full permissions to manage their -assigned profile within the TagoIO Admin console. Note that developer accounts -are separate from TagoDeploy accounts. Access to the TagoDeploy console is -managed independently, to grant access, you must add collaborators to your -project. +Developer accounts are separate from TagoDeploy accounts. Access to the +TagoDeploy console is managed independently. To grant TagoDeploy access, add +collaborators to your project. See +[Collaborators](/docs/tagodeploy/project/management/collaborators.md). If a user needs to change their password, they should click the "Forgot -password" button on the sign-in page of the TagoIO Admin console. This initiates -the password reset process, allowing users to securely update their credentials. - -For any additional questions regarding the TagoIO Admin console, it is -recommended to consult the -[TagoIO Help Center](https://help.tago.io/portal/en/kb/tagoio). The Help Center -provides comprehensive documentation and troubleshooting guidance for all -aspects of the TagoIO Admin console, making it a valuable resource for resolving -common problems and learning more about available features. - -## Managing Accounts +password" button on the sign-in page of the TagoIO Admin console. This starts +the password reset process so they can update their credentials. -### Creating a New Account +## Browsing accounts -To create a new user account: +The page lists each account along with the profiles it owns. Use the search box +to filter accounts by name, and use Expand All or Collapse All to show or hide +the profiles under each account. When a project has no accounts, the page shows +"No accounts found for this project." -1. Click the "Create" button in the top-right corner of the accounts section -2. Fill in the required account information in the "New account" form. -3. Click "Confirm" to create the account, or "Cancel" to discard the changes -4. The new account will be added to the accounts list and the user can access - the project +## Creating a new account -### Editing an Account +1. Click **New Account**. +2. In the "New Account" dialog, fill in the fields: + - **Name**: the user's full name. + - **Email**: the account email address. + - **Password**: the initial password. + - **Company**: the company name. + - **Country**: select a country. +3. Click **Confirm** to create the account, or **Cancel** to discard. -To modify an existing account: +The new account is added to the list, and the user can access the project's +TagoIO Admin console. -1. Locate the account in the accounts list -2. Click on the three-dot menu next to the account -3. Select "Edit" or the appropriate modification option -4. Update the account information or access as needed +## Profile sharing -### Account Management Options - -Using the three-dot menu, you can perform various account management actions: - -- **Edit Account**: Modify account information and settings -- **Deactivate/Activate**: Change the account's active status -- **Delete Account**: Delete the account from the project - -## Profile Sharing - -Each new account is provisioned with a unique profile that defines the user’s -access scope and available resources. To enable multiple users to share access -to a specific profile, you should use the +Each new account is provisioned with its own profile, which defines the user's +access scope and available resources. To let several users share access to a +single profile, use the [TagoIO Teams](https://help.tago.io/portal/en/kb/articles/106-sharing-your-profile) -feature. This approach allows for collaborative access while maintaining -appropriate access controls and audit trails. - -## Account Information - -The accounts list presents detailed information for each administrator, -including the display name, associated email address, account status, last login -timestamp, and the date the account was created. This comprehensive overview -helps administrators maintain control over access and monitor user activity -within the TagoIO Admin console. +feature. This keeps collaborative access under appropriate controls and audit +trails. diff --git a/docs/tagodeploy/project/configuration/limits.md b/docs/tagodeploy/project/configuration/limits.md index 17298fd2..e72efd8c 100644 --- a/docs/tagodeploy/project/configuration/limits.md +++ b/docs/tagodeploy/project/configuration/limits.md @@ -1,45 +1,44 @@ --- title: "Resource Limits" -description: "Configure and understand project resource limits, their impact on scaling, and best practices." +description: "Configure resource quotas and rate limits for a profile, and understand their impact on scaling." keywords: [tagodeploy, iot, limits, scaling, resources] tags: ["tagodeploy"] slug: /tagodeploy/project/limits --- -Limits define the maximum consumption thresholds for specific resources -allocated to your TagoIO project profiles. These constraints are essential for -managing resource allocation, maintaining system stability, and ensuring fair -usage across all tenants within your infrastructure. By enforcing limits, the -platform protects against excessive usage that could otherwise degrade service -quality for other users or overwhelm backend components. - -It is important to recognize that increasing resource limits such as raising the -number of requests your API can handle per minute, or expanding the maximum data -volume per request directly impacts the operational requirements of your API -service. Higher limits may necessitate additional computational resources, -either through vertical scaling (increasing CPU and memory per instance) or -horizontal scaling (adding more API instances). For detailed guidance on scaling -strategies and their implications, refer to the -[API Documentation](/docs/tagodeploy//project/project-services/api.md). - -Before increasing Request limits, it is highly recommended to ensure that all -Analysis scripts within the profile are thoroughly optimized. Optimization -efforts should include refactoring Analysis code to eliminate unnecessary API -calls and implementing parallel queue systems to reduce strain on the API. -Addressing inefficiencies at the script level can significantly reduce peak -resource consumption, reducing the need for additional computational resources. - -## Modifying Resource Limits - -To update resource limits for a specific profile, follow these steps: - -1. Select the relevant profile from your project dashboard. -2. Choose the edit option associated with the resource limit you wish to modify. -3. Enter the new desired limit value, taking into account the potential impact - on system performance and infrastructure requirements. -4. Confirm and apply the changes to enforce the updated limit. - -**Important:** After increasing limits, closely monitor API performance and -system metrics to ensure that your infrastructure continues to meet the demands -of your workloads. Adjust scaling configurations as needed to maintain optimal -availability and responsiveness. +# Limits + +The **Limits** page configures resource quotas and rate limits for a profile. +You find it in the TagoIO & API section, under "Limits" in the sidebar, at +`/projects/{id}/tago-io/limits`. + +Limits define the maximum consumption thresholds for the resources allocated to +a profile. They keep resource use under control, maintain system stability, and +keep usage fair across tenants on shared infrastructure. By enforcing limits, +the platform protects against usage that could degrade service quality for other +users or overwhelm backend components. + +Raising a limit, such as the number of API requests per minute or the maximum +data volume per request, directly affects the operational requirements of your +API service. Higher limits may call for additional resources, either through +vertical scaling (more CPU and memory per instance) or horizontal scaling (more +API instances). For guidance on scaling, see the +[API service](/docs/tagodeploy/project/project-services/api.md) page. + +Before raising request limits, make sure the profile's Analysis scripts are +optimized. Refactor Analysis code to remove unnecessary API calls and use +parallel queues to reduce strain on the API. Fixing inefficiencies at the script +level can cut peak resource use and reduce the need for extra resources. + +## Editing limits + +1. Select an **Account** from the combobox. +2. Select a **Profile** from the combobox. +3. Once a profile is chosen, the limit groups appear. Use the "Search limits" + box to find a specific limit, then enter the new value, taking into account + the impact on system performance and infrastructure. +4. Click **Save** to apply the changes. + +**Important:** After raising limits, monitor API performance and system metrics +to confirm your infrastructure keeps up with the workload. Adjust scaling +settings as needed to maintain availability and responsiveness. diff --git a/docs/tagodeploy/project/index.md b/docs/tagodeploy/project/index.md index 5dc854a7..2b555447 100644 --- a/docs/tagodeploy/project/index.md +++ b/docs/tagodeploy/project/index.md @@ -1,41 +1,57 @@ --- -title: "Projects" -description: "Overview of the Projects page: view details, access consoles, and manage projects in TagoDeploy." -keywords: [tagodeploy, iot, project, management] +title: "Project Overview" +description: "Read the Project Overview page: project status, resource usage, spend, and recent activity." +keywords: [tagodeploy, iot, project, overview, management] tags: ["tagodeploy"] slug: /tagodeploy/project/overview --- -# Projects +# Project Overview -The **Projects** page is your central hub for managing all of your projects. -From here, you can quickly view key details such as project region, status, and -API endpoint, as well as access essential project management features. +The **Overview** page is the first page in a project's Management section. It +shows project status, resource usage, spend, and recent activity at a glance. +Open it from the Management sidebar at +`/projects/{id}/management/overview`. -## What Can You Do on the Projects Page? +## Project status -The Projects page provides a streamlined overview and quick actions for every -project: +The project card shows the project avatar, name, and a status badge (for +example, "Deploying"). It also lists: -- **View Project Details**: Instantly see the region, current status, and API - endpoint for each project. -- **Access Project Console**: Click the platform button to be redirected to the - project's admin console. -- **Manage Projects**: Use the manage button to go directly to the project's - management page, where you can update settings, resources, and more. -- **Quick Actions**: Utilize the dropdown menu for fast access to your project's - main features without extra navigation. +- **Version**: the platform version the project runs, shown as a date. +- **Created**: the date the project was created. +- **Region**: the region the project runs in, for example `us-east-1`. -## Creating New Projects +## Domains -You can easily create new projects directly from the Projects page. This allows -you to: +The Domains panel lists the project's service URLs, such as TagoIO API, TagoIO +Admin, and TagoIO SSE, each in the form +`https://{service}.{id}.tagoio.net`. Every row has a Copy URL action. Use the +"View all domains" link to open the full +[Domains](/docs/tagodeploy/project/management/domains.md) page. -1. **Start New Initiatives**: Launch new projects as your needs grow. -2. **Configure Regions and Settings**: Specify important parameters such as - region and initial configurations during project creation. -3. **Immediate Access**: Newly created projects appear instantly in your project - list, ready for further setup and integration. +## Spend -By centralizing all project management tasks, the Projects page helps you stay -organized, efficient, and in control of your development workflow. +The Month-to-Date Spend card shows the current dollar amount, a comparison +against last month's pace, and a daily spend chart with a month toggle. For the +full cost breakdown, open the +[Bills](/docs/tagodeploy/project/management/billing.md) page. + +## Monitoring + +Two charts track resource usage: + +- **CPU Utilization - TagoIO**: series for API, Main Database, and In-Memory + Database. +- **CPU & Memory Utilization - MQTT**: CPU and Memory series. + +Both charts support time ranges of 1h, 6h, 12h, 1d, 3d, 7d, and 30d. When no +metrics exist yet, the chart shows "No data available". + +## Recent activity + +The History and Logs sections show recent project activity. Until a project +produces output, the Logs section shows an empty state. + +When you have pending changes, a floating "Review & Deploy" button appears so +you can review and apply the queued deployment. diff --git a/docs/tagodeploy/project/management/backups.md b/docs/tagodeploy/project/management/backups.md index 5f7a53b4..12109a51 100644 --- a/docs/tagodeploy/project/management/backups.md +++ b/docs/tagodeploy/project/management/backups.md @@ -1,87 +1,63 @@ --- title: "Backups" -description: "View, configure, and restore project backups; understand contents, exclusions, and limitations." +description: "View scheduled database snapshots for a project and understand contents, exclusions, and restore behavior." keywords: [tagodeploy, iot, backups, disaster recovery, data protection] tags: ["tagodeploy"] slug: /tagodeploy/project/backups --- -This section provides project owners with the ability to view and manage all -recent project backups. Each backup entry displays essential metadata, including -the backup date and storage size. When initiating a restoration, the system -provisions a new, isolated project instance that is initialized from the -selected backup checkpoint. The platform does not support in-place overwriting -of an existing project’s database with backup data. +# Backups -Backup management capabilities—including configuration, creation, and -restoration—are restricted to project owners. Collaborators do not have access -to any backup management features. +The **Backups** page lists the snapshots of your project's database. You find it +in the TagoIO & API section, under "Backups" in the sidebar, at +`/projects/{id}/tago-io/backups`. The page is read-only: backups are created on +a schedule, not by hand, so there is no create action here. When the project has +no snapshots yet, the page shows "Backup snapshots will appear here once they are +created." -**Note**: Standard project creation fees apply when a new project instance is -generated as part of the backup restoration process. Restored project instances -will continue to incur costs for as long as they remain active. +Backup management is restricted to project owners. Collaborators cannot access +backup features. -## What are Backups? +## How backups are scheduled -Backups are automated snapshots of your project data that provide data -protection and recovery capabilities. They ensure that your project information -is preserved and can be restored in case of data loss. +Backups are created automatically on a daily schedule. The schedule and how long +snapshots are kept are configured on the +[Main Database](/docs/tagodeploy/project/project-services/main-database.md) page, +using the "Daily backup schedule" and "Backup retention period" settings. -Backups are created automatically every day to ensure consistent data -protection. The backup schedule can be configured in the -[Main Database](/docs/tagodeploy/project/project-services/main-database.md) -page. +## What is excluded from backups -## Backup Information +The following data is not included in backups: -The backup list displays the following information for each backup: +- **Analysis**: Analysis console logs and code. +- **Files**: uploaded files and file attachments. -- **Backup Date**: When the backup was created -- **Backup Size**: The storage space occupied by the backup +## Restore behavior -## What's Excluded from Backups +Restoring a snapshot provisions a new, isolated project instance initialized +from that snapshot. The platform does not overwrite an existing project's +database in place. -The following data types are not included in backups: +**Note:** Standard project creation fees apply when a new project instance is +created from a backup. Restored instances continue to incur costs for as long as +they stay active. -- **Analysis**: Analysis console logs, and code. -- **Files**: Uploaded files and file attachments +Once a backup project is running, project owners can move data into a target +project by: -## Restoring from Backup - -To create a new project from an existing backup: - -1. Locate the desired backup in the backup list -2. Click on the three-dot menu next to the backup -3. Select "New project from backup" -4. Follow the prompts to create a new project with the backup data +- Manually transferring data between the backup project and the target project. +- Running analysis scripts or the + [TagoIO API](/docs/api/sidebar/tagoio-api-intro) to automate the migration. +- Using the [TagoIO CLI](https://github.com/tago-io/tago-cli) for bulk transfer. -### Backup Restoration Process +### Restore limitations -Project owners can restore data from a backup project to an existing project -using several methods: +When data is restored from a backup, the platform does not preserve variable +unique IDs. The system assigns a new unique identifier to each variable during +ingestion, so a variable's ID in the restored project differs from its ID in the +backup. -- Manually transferring data between the backup project and the target project. -- Executing analysis scripts or the - [TagoIO API](/docs/api/sidebar/tagoio-api-intro) to automate data migration - between projects. -- Utilizing the [TagoIO CLI](https://github.com/tago-io/tago-cli) to facilitate - bulk data transfer from the backup project to the active project. - -The system retains the seven most recent backups, which are available for -restoration at any time. - -### Backup Limitations - -When restoring data from a backup, the platform does not preserve variable -unique IDs. During the data ingestion process, the system generates a new unique -identifier for each variable, regardless of its previous state. As a result, the -unique ID assigned to a variable in the backup will differ from the ID assigned -to the same variable in the current project environment. - -Similarly, the platform does not restore resource tokens from backup data. Each -time a resource is created, the system generates a new token associated with -that resource. Consequently, the token value for a resource in the backup will -not correspond to the token value for the same resource after restoration in the -current project. This approach maintains the integrity and security of resource -access but requires that any integrations or automation referencing resource -tokens be updated post-restore. +The platform also does not restore resource tokens. Each time a resource is +created, the system generates a new token for it, so a resource's token after a +restore differs from its token in the backup. Update any integrations or +automation that reference resource tokens after a restore. diff --git a/docs/tagodeploy/project/management/billing.md b/docs/tagodeploy/project/management/billing.md index df945501..d1421830 100644 --- a/docs/tagodeploy/project/management/billing.md +++ b/docs/tagodeploy/project/management/billing.md @@ -1,110 +1,72 @@ --- -title: "Billing Overview" -description: "Understand TagoIO billing model, cost structure, service-level analysis, and optimization strategies." +title: "Bills" +description: "Read the Bills page: monthly cost breakdown, charges by service, payment status, and spend trends." keywords: [tagodeploy, iot, billing, cost management, pricing] tags: ["tagodeploy", "billing"] slug: /tagodeploy/project/bills/billing --- -# TagoIO Billing and Cost Management Documentation +# Bills -The TagoIO billing system provides comprehensive cost visibility and management -capabilities for enterprise IoT deployments. Understanding your billing -structure is critical for budget planning, cost optimization, and operational -decision-making. This documentation explains how TagoIO's post-paid model works, -what drives your costs, and how to effectively manage your spending across -complex IoT infrastructure deployments. +The **Bills** page shows the monthly cost breakdown, charges, and payment status +for a project. Open it from the Management sidebar at +`/projects/{id}/management/bills`. Use the "Filter by app" and "Period" +comboboxes at the top to scope what the page shows. -## Understanding TagoIO's Billing Model +TagoIO uses a post-paid consumption model with a flat monthly platform license. +You are charged for actual resource use, so costs track your device activity, +data volumes, and processing as they change. -TagoIO operates on a post-paid consumption model that combines usage-based -pricing with a flat monthly platform fee. This approach gives you the -flexibility to scale your IoT infrastructure dynamically while maintaining -predictable baseline costs. You're charged hourly for actual resource -consumption, which means you pay only for what you use when you use it. +## KPI cards -The billing model reflects the reality of IoT deployments where device activity, -data volumes, and processing requirements can vary significantly based on -seasonal patterns, business cycles, or operational events. Rather than forcing -you into rigid capacity tiers, TagoIO's model adapts to your actual usage -patterns. +Three cards summarize current spend: -## Cost Structure and Service Components +- **Month-to-date**: spend so far this period and the change against last month. +- **Avg / Day**: the daily average, based on the number of days in the period. +- **Last Month**: the previous month's total. -Your TagoIO bill consists of multiple service categories, each reflecting -different aspects of your IoT infrastructure. The billing dashboard breaks these -down into clear categories so you can understand exactly where your money is -going. +## Bill summary -### Platform and Infrastructure Services +The Bill Summary shows the period total along with **Status** (the current +cycle), **Payment**, and **Due** (the estimated due date). -The **Recurring Platform License** represents your base subscription fee for -access to TagoIO's core platform capabilities. This flat fee covers platform -maintenance, security updates, and baseline support services. Think of this as -your "seat at the table" – it's what keeps your account active and gives you -access to all platform features. +## Cost history -**Recurring Infrastructure** charges cover the underlying compute, storage, and -networking resources that power your IoT applications. These costs scale with -your usage patterns and include the virtual machines, container orchestration, -and network bandwidth required to process your device data and serve your -applications. +The Cost History chart breaks daily spend down by service in a stacked chart. +Each service has a toggle so you can show or hide it. The services are: -## Reading Your Cost History +- **Network** +- **Files** +- **Platform License** +- **Infrastructure** +- **Main DB** +- **Queue** +- **Analysis** +- **In-Memory DB** +- **API** +- **Apps** -The cost history chart provides crucial insights into your spending patterns and -helps identify trends that impact your budget planning. The stacked bar chart -shows daily costs broken down by service category, making it easy to spot -unusual spikes or gradual increases in specific areas. +The Platform License is your flat subscription fee for access to the platform. +It stays constant across periods. Infrastructure and Main DB usually show the +most variation, since they track application usage directly. Spikes there often +line up with increased device activity, data ingestion bursts, or new +deployments. -The **TagoIO Flat Fee** component should remain constant across billing periods. +## Daily spend and top services -The infrastructure and database components typically show the most variation, as -they directly reflect your application usage patterns. Sudden spikes in these -areas often correlate with increased device activity, data ingestion bursts, or -new application deployments. +The Daily Spend chart covers the selected period with a 7d, 14d, or MTD range +toggle. The By Service chart ranks the top services by cost. -## Service-Level Cost Analysis +## Charges by service -The "Charges by Service" breakdown is where you'll spend most of your time -optimizing costs. This granular view shows exactly how much each service -component contributes to your total bill. +The Charges by Service section lists each service with its amount for the period +and a Total row. Use it to see exactly how much each service contributes to the +bill. If a service is growing faster than your business metrics, it can point to +inefficient resource allocation. For example, high API and Analysis costs +together can indicate room to batch operations or add caching. -**Container Service** often represents the largest variable cost component -because it scales directly with your application workload. If this number is -growing faster than your business metrics, it might indicate inefficient -resource allocation or the need for optimization. +## Billing periods -**Database** costs should correlate with your data growth and retention -policies. Unexpected increases here might indicate inefficient queries, -excessive data retention, or the need to archive older data to less expensive -storage tiers. - -**Computing Service** charges reflect the intensity of your data processing -workflows. Optimization opportunities here include batching operations, -optimizing algorithms, or moving infrequent processing to scheduled jobs rather -than real-time execution. - -## Billing Period Management - -TagoIO bills monthly, with each billing period running from the first to the -last day of the month. The estimated bill summary shows projected costs based on -current usage patterns, but remember that actual costs may vary based on usage -changes throughout the month. - -The billing system aggregates charges from multiple service providers – -primarily Amazon Web Services for infrastructure components and TagoIO for -platform-specific services. This separation helps you understand which costs are -infrastructure-related versus platform feature usage. - -## Cost Optimization Strategies - -Understanding your bill is the first step toward optimizing costs. Look for -patterns in your usage that might indicate optimization opportunities. For -example, consistent high database costs might justify investing in query -optimization or data archiving strategies. - -Consider the relationship between different service costs. High API usage -combined with high computing costs might indicate opportunities to batch -operations or implement caching strategies. Similarly, high container costs with -low database usage might suggest over-provisioned compute resources. +TagoIO bills monthly, with each period running from the first to the last day of +the month. The bill summary is an estimate based on current usage, so the final +amount can change as usage shifts through the month. diff --git a/docs/tagodeploy/project/management/collaborators.md b/docs/tagodeploy/project/management/collaborators.md index f46320fe..ff1f89af 100644 --- a/docs/tagodeploy/project/management/collaborators.md +++ b/docs/tagodeploy/project/management/collaborators.md @@ -1,33 +1,43 @@ --- title: "Collaborators" -description: "Add and manage collaborators to your project." +description: "Invite and manage the people who can view and change a project's resources." keywords: [tagodeploy, iot, collaborators, team, permissions] tags: ["tagodeploy"] slug: /tagodeploy/project/management/collaborators --- -Collaborators are users who can access and work on your TagoDeploy Project. They -can view and edit project resources but cannot delete the project. Collaborators -are different from Admin Portal developers, which you manage separately under -[TagoIO Admin Accounts](/docs/tagodeploy/project/configuration/accounts.md). +# Collaborators + +Collaborators are the people who can view and change your TagoDeploy project's +resources. Open the page from the Management sidebar at +`/projects/{id}/management/collaborators`. When the project has none, it shows +"Invite team members to collaborate on this project." +Collaborators are different from TagoIO Admin developers, which you manage +separately under +[TagoIO Admin Accounts](/docs/tagodeploy/project/configuration/accounts.md). A collaborator must have their own TagoDeploy account to accept an invitation. -## Permissions and Limits +## Permissions and limits - Can view and edit project resources - Cannot delete the project - Cannot manage billing -- Cannot access your Admin Portal unless they have an Admin Account there +- Cannot access your Admin console unless they have an Admin account there Project owners can remove collaborators at any time. -## Inviting Collaborators +## Inviting collaborators -Use the Invite action on the Collaborators page and enter the email address of -the user you want to add. The email must match an existing TagoDeploy account. +1. Click **Invite**. +2. In the "Invite Collaborator" dialog, enter the **Email address** of the user. + It must match an existing TagoDeploy account. +3. Select a **Role**: + - **Admin**: full access to the project's resources. + - **Contractor**: scoped access for outside contributors. +4. Click **Send Invite**, or **Cancel** to discard. Invitation states: -- Pending: Invitation sent, not yet accepted -- Accepted: User joined the project +- **Pending**: invitation sent, not yet accepted. +- **Accepted**: the user joined the project. diff --git a/docs/tagodeploy/project/management/domains.md b/docs/tagodeploy/project/management/domains.md index dd2028ae..34650554 100644 --- a/docs/tagodeploy/project/management/domains.md +++ b/docs/tagodeploy/project/management/domains.md @@ -1,82 +1,52 @@ --- title: "Domain Management" -description: "Manage Admin, TagoRUN, API, middleware, and MQTT domains; configure DNS and SSL CNAME records." +description: "View custom and default domains for a project's services, and add a custom domain with the New Domain wizard." keywords: [tagodeploy, iot, domains, dns, ssl] tags: ["tagodeploy"] slug: /tagodeploy/project/domains --- -# Domain Management +# Domains -The Domains section provides centralized management of all network domains -associated with your project, including those for TagoIO Admin, TagoRun -applications, APIs, middleware services, and MQTT brokers. This interface -enables project owners to view, configure, and monitor the domains that serve as -entry points for various services within the project infrastructure. The domain -list displays essential details such as the domain URL, routing target, -destination, and operational status. +The **Domains** page manages the domains that route to your project's services, +including TagoIO Admin, TagoRUN applications, the API, middlewares, and the MQTT +broker. Open it from the Management sidebar at `/projects/{id}/management/domains`. +The page splits domains into two sections: Custom Domains and Default Domains. **Important:** Middleware domains are visible and configurable only by project -owners. Collaborators do not have access to view or modify middleware domains, -ensuring that sensitive routing and service configurations remain secure. +owners. Collaborators cannot view or modify them, which keeps routing and +service configuration secure. -## Understanding Domains +## Custom Domains -Domains are network addresses that allow users and systems to access different -components of your project. Each domain is mapped to a specific service or -application, providing a clear and organized structure for managing access and -connectivity. +Custom domains are external domains that let you use your own branding for the +project's services. When the project has none, the section shows "No custom +domains yet". Use **New Domain** to add one. -The main types of domains managed in this section include: +## Default Domains -- **TagoIO Admin Domains**: Provide access to your project's administrative - interface. -- **TagoRun Domains**: Serve as URLs for your TagoRun applications, enabling - user access to custom interfaces. -- **TagoIO API Domain**: Defines the network endpoint for interacting with the - TagoIO API. -- **Middleware Domains**: Route traffic to middleware services integrated with - your project. -- **MQTT Broker Domains**: Specify network addresses for MQTT broker - connections, supporting IoT device communication. +Default domains are the standard domains assigned to your project for immediate +access. They are listed in a sortable table with these columns: -## Domain Information +- **URL**: the full address used to reach the service. +- **Application**: the service the domain serves, such as TagoIO API, TagoIO + Admin, TagoIO SSE, a middleware, a container, or the MQTT broker. +- **Endpoint**: the endpoint type, for example "API". The MQTT broker row uses + an `mqtts://` URL. -For each configured domain, the domain list displays the following attributes: +## Adding a custom domain -- **URL**: The full web address or endpoint that users or systems will use to - access the service. -- **Target**: The specific service, component, or environment to which the - domain is mapped. -- **Routed To**: The backend destination where incoming traffic is directed. -- **Status**: The real-time operational state of the domain (e.g., active, - pending, error). +Click **New Domain** to open the wizard. It runs in three steps: **Form**, +**Review**, and **Records**. -This information enables efficient management and troubleshooting of network -routing and service access. +1. On the **Form** step, fill in the fields: + - **Subdomain**: the prefix to use, for example `api`, `portal`, or `iot`. + - **Domain**: your primary domain, for example `mycompany.com`. + - **Target**: the service the domain should point to. + Click **Next**. +2. On the **Review** step, confirm the details. +3. On the **Records** step, copy the DNS records shown and add them to your DNS + provider's settings. -## Creating and Configuring a New Domain to a Profile - -To add a new domain to your project, follow these steps: - -1. Head to the TagoDeploy console and go to your project's **Domains** section. -2. **Set the Subdomain:** Enter the desired prefix (e.g., `admin`, `api`, - `mqtt`) to use as your subdomain. -3. **Enter Your Main Domain:** Type in your primary domain (e.g., - `yourcompany.com`). -4. **Choose the Destination:** Select the service or component (such as TagoIO - Admin, TagoRun, API, middleware, or MQTT broker) that the domain should point - to. -5. Click **Add Domain** to create your new domain entry. -6. Next to the domain you just added, click the three-dot menu and select **Edit - Domain**. -7. **Copy the Endpoint and SSL Certificate CNAME records** provided, then add - these records to your DNS provider’s settings. - - - -8. Wait a few minutes for DNS propagation. You can check the status by clicking - **Check Records**. -9. Once the DNS is set up, copy the URL from the domain list and open the Run - module in your TagoIO Profile and add the new domain under the **Domain** - section. +After DNS propagation, the custom domain becomes available for the target +service. diff --git a/docs/tagodeploy/project/management/tokens.md b/docs/tagodeploy/project/management/tokens.md new file mode 100644 index 00000000..99921a7d --- /dev/null +++ b/docs/tagodeploy/project/management/tokens.md @@ -0,0 +1,43 @@ +--- +title: "Project Tokens" +description: "Create and revoke API tokens that grant scripts and services programmatic access to a project." +keywords: [tagodeploy, iot, tokens, api, programmatic access] +tags: ["tagodeploy"] +slug: /tagodeploy/project/management/tokens +--- + +# Project Tokens + +Project tokens give scripts and services programmatic access to a TagoDeploy +project. Open the page from the Management sidebar at +`/projects/{id}/management/tokens`. It lists the tokens that exist for the +project and lets you create new ones or revoke the ones you no longer need. When +the project has none, it shows "Create an API token to enable programmatic +access to this project." + +## How tokens work + +A token authenticates API requests to the project without a browser session. A +token has full access to the project and can be used with the API. + +The list shows each token by its last four characters, who created it, and when. +The full secret is never shown after creation, so the last four characters are +how you tell tokens apart. A project can hold up to 10 tokens. Once you reach +that limit, the New Token button is disabled and the page shows a warning. +Delete a token to free a slot. + +## Creating a token + +Click **New Token** and confirm in the dialog. The dialog has no input fields: +the token is created with full access to the project for use with the API. The +secret is shown once, right after creation, with a Copy button. Copy it and +store it somewhere safe before you close the dialog, because it cannot be shown +again. If you lose it, delete the token and create a new one. + +## Revoking a token + +Use the Delete action on a token row, then confirm in the dialog, which +identifies the token by its last four characters. Revoking takes effect +immediately, and any request that uses the token after that fails. This cannot +be undone, so revoke a token whenever its secret may have leaked or it is no +longer in use. From 0c68c538c1da0e964bd9d0d5bba1eda4fade3985 Mon Sep 17 00:00:00 2001 From: Ricardo Stoklosa Date: Fri, 29 May 2026 16:01:21 -0300 Subject: [PATCH 09/15] docs(tagodeploy): refresh project services docs --- .../project-services/analysis-runtime.md | 84 +++++------ .../project/project-services/api.md | 134 +++++++----------- .../project-services/in-memory-database.md | 102 +++++++------ .../project/project-services/main-database.md | 117 +++++++-------- 4 files changed, 195 insertions(+), 242 deletions(-) diff --git a/docs/tagodeploy/project/project-services/analysis-runtime.md b/docs/tagodeploy/project/project-services/analysis-runtime.md index 04daa3d7..e0c77e7b 100644 --- a/docs/tagodeploy/project/project-services/analysis-runtime.md +++ b/docs/tagodeploy/project/project-services/analysis-runtime.md @@ -1,69 +1,59 @@ --- title: "Analysis Runtime" -description: "Configure memory and monitor Python/Node.js runtime metrics for TagoIO analyses; optimize cost and performance." -keywords: [tagodeploy, iot, analysis, runtime, performance] +description: "Set Node.js and Python memory for the scripts that run your TagoIO analyses, and monitor invocations and duration." +keywords: [tagodeploy, iot, analysis, runtime, memory, monitoring] tags: ["tagodeploy", "analysis"] slug: /tagodeploy/project/analysis-runtime --- # Analysis Runtime -The Analysis Runtime provides visibility and control over the resource usage and -performance metrics of your -[analysis](https://help.tago.io/portal/en/kb/articles/29-analysis-overview) -scripts within the TagoIO platform. Proper configuration and monitoring of -[analysis runtime](https://help.tago.io/portal/en/kb/articles/194-analysis-service) -parameters are essential for optimizing operational costs and maintaining system -performance. Analyses are billed primarily based on their execution duration and -the memory consumed during runtime. +The Analysis Runtime page sets the memory available to the Node.js and Python +scripts that run your +[analyses](https://help.tago.io/portal/en/kb/articles/29-analysis-overview). +Analyses are billed mainly on execution duration and the memory used during a +run, so the memory you set here affects both performance and cost. + +Open the page from the **TagoIO & API** area, under **SERVICES** in the sidebar. ## Memory Configuration -Memory allocation is a critical factor that directly impacts both the -performance and cost of your analyses. Each analysis execution is provisioned -with a configurable memory limit, which determines the maximum amount of RAM -available during runtime. Consuming more memory, especially when processing -large datasets or performing complex calculations, will result in higher costs. +The page has two configuration groups, one per runtime: + +- **Node.js Runtime**: memory allocation for Node.js analysis scripts. The + **Memory (MB)** field defaults to 512. +- **Python Runtime**: memory allocation for Python analysis scripts. The + **Memory (MB)** field defaults to 512. -- **Maximum Allocation:** The highest memory limit you can assign to an analysis - is 10GB. This is intended for advanced analytics or workloads that require - substantial in-memory processing. -- **Default Allocation:** By default, each analysis is allocated 512MB of - memory. This configuration is typically sufficient for standard operations and - applications that do not require intensive data processing. +The default of 512 MB is enough for standard operations that do not run +intensive data processing. Raise it when an analysis works over large datasets +or performs heavy in-memory calculations. Higher memory increases cost, so set +only what the script needs. -Carefully assess the memory requirements of your analysis scripts. Allocate only -as much memory as needed to prevent unnecessary cost increases. Monitor memory -consumption patterns, especially after changes to data retrieval or processing -logic. +Click **Save** to apply changes. -## Runtime Metrics +## Monitoring -To help you manage and optimize your analyses, the platform provides real-time -metrics for both Python and Node.js runtimes: +The **Monitoring** section reports runtime activity. A range toggle switches the +window across 1h, 6h, 12h, 1d, 3d, 7d, and 30d. When there is no data for the +selected window, the chart shows "No data available". -### Invocation Count +### Invocations -This metric tracks the number of analysis executions initiated over a given -period. Monitoring invocation trends can help you identify usage patterns, -optimize scheduling, and anticipate scaling needs. +Counts the analysis executions started in the selected window (COUNT). +Invocation trends help you read usage patterns, tune scheduling, and anticipate +scaling needs. -### Execution Duration +### Duration -This metric records the average time (in seconds) taken for analyses to complete -their execution. Tracking duration helps you detect performance bottlenecks, -optimize script efficiency, and manage resource allocation more effectively. +Reports how long analyses take to run, in milliseconds (MS). Tracking duration +helps you find performance bottlenecks and refactor slow scripts. -## Cost and Performance Optimization +## Cost and Performance -Since analysis billing is based on both execution duration and memory -consumption, it is important to: +Billing follows execution duration and memory use, so: -- Regularly review runtime metrics to identify inefficiencies or unexpected - resource usage. -- Tune memory allocation settings according to the actual requirements of your - analyses. -- Refactor scripts to minimize execution time and avoid unnecessary data - processing or retrieval. -- Set up alerts or monitoring thresholds to proactively manage costs and ensure - stable operations. +- Review the Invocations and Duration charts to find inefficiencies or + unexpected usage. +- Set memory per runtime to the actual needs of your scripts. +- Refactor scripts to cut execution time and avoid unnecessary data retrieval. diff --git a/docs/tagodeploy/project/project-services/api.md b/docs/tagodeploy/project/project-services/api.md index de42861d..4abcc344 100644 --- a/docs/tagodeploy/project/project-services/api.md +++ b/docs/tagodeploy/project/project-services/api.md @@ -1,101 +1,77 @@ --- title: "API Service" -description: "Manage and scale the TagoIO API for your project, with recommended configurations and billing considerations." -keywords: [tagodeploy, iot, api, scaling, monitoring] +description: "Set the machine size and autoscaling for the TagoIO API service, and monitor CPU and memory." +keywords: [tagodeploy, iot, api, scaling, monitoring, autoscaling] tags: ["tagodeploy", "api"] slug: /tagodeploy/project/api --- -# API Service Management +# API Service The [TagoIO API](https://help.tago.io/portal/en/kb/articles/31-api-overview) -service is a core component of your TagoDeploy Project running on AWS -infrastructure. API usage is directly tied to your project’s billing costs, as -resource consumption such as compute, memory, and network utilization impacts -your overall charges. For detailed information on how API resource usage affects -your costs and how to optimize your spending, refer to the -[TagoIO Billing and Cost Management Documentation](/docs/tagodeploy/project/management/billing.md). - -An active API instance is required for your TagoIO services to function. Without -it, none of the TagoIO platform features or integrations will be accessible. - -## What is an API? - -An API (Application Programming Interface) is a standardized interface that -enables different software applications to communicate and exchange data. It -defines the rules, protocols, and data formats for requests and responses, -allowing disparate systems to work together seamlessly. - -Within TagoIO, [the API](/docs/api/sidebar/tagoio-api-intro) acts as the central -gateway through which all services, applications, and devices interact with your -project’s data and features. Every operation relies on the availability and -performance of your API service. - -## API Scaling Strategies - -As your project scales with more devices, users, and automated workflows, it is -critical to ensure your API service can handle increased load. TagoIO provides -two primary approaches to scaling your API infrastructure: - -- **Vertical scaling (Machine Tier)**: Increases the capacity of individual API - server instances by allocating more CPU cores and RAM. This method is - effective when your workload involves intensive data processing or large data - retrieval operations, such as dashboard queries exceeding 10,000 records in a - single request. TagoIO offers multiple machine tiers to accommodate varying - performance needs. For advanced vertical scaling options, contact TagoIO - support. +service is the central gateway through which services, applications, and devices +reach your project's data and features. Every operation depends on it, so an +active API instance is required for the rest of the platform to work. + +This page sets the machine size and autoscaling for incoming API requests. API +usage is tied to your billing costs, since compute, memory, and network use +drive your charges. See the +[Bills](/docs/tagodeploy/project/management/billing.md) page for how that adds +up. + +Open the page from the **TagoIO & API** area, under **SERVICES** in the sidebar. -- **Horizontal scaling (Number of machines)**: Is the recommended strategy for - most production environments. It involves deploying multiple API instances to - distribute incoming requests and improve fault tolerance. This approach aligns - with TagoIO’s cloud-native architecture and is more effective for handling - high concurrency and bursts of activity as your device count and automation - complexity grow. +## Instance Settings -You can configure auto-scaling conditions based on your application’s usage -patterns and performance testing. Typical triggers include CPU utilization, -memory consumption, and request rates. +The **Instance settings** section configures machine type, scaling, and cooldown +parameters: -## Recommended Production Configuration +- **Machine**: the machine type for each instance. Default is 1 vCPU / 2GB RAM. +- **Minimum instances**: the lowest number of instances kept running. Default + is 1. +- **Maximum instances**: the highest number autoscaling can reach. Default is 1. +- **Scale on CPU utilization**: the CPU percentage that triggers scaling. + Default is 60. +- **Cooldown for scaling up**: seconds to wait before adding instances again. + Default is 200. +- **Cooldown for scaling down**: seconds to wait before removing instances. + Default is 300. -For projects supporting up to 10,000 devices, TagoIO recommends the following -baseline settings for API service deployment: +Click **Save** to apply changes. -- **Machine Specification:** 1 vCPU / 2GB RAM per instance -- **Instance Count:** Minimum 2 instances, maximum 5 instances -- **Auto-Scaling Thresholds:** Scale up when CPU utilization exceeds 60% for 200 - seconds; scale down when utilization falls below the threshold for 300 seconds +## Scaling Strategies -These settings provide a balance between performance, availability, and cost -efficiency for most production workloads. +As the project grows with more devices, users, and automated workflows, the API +service has to handle more load. There are two ways to scale it: + +- **Vertical scaling (Machine)**: raise the CPU and RAM of each instance with a + larger machine type. This helps with intensive data processing or large + retrievals, such as dashboard queries returning more than 10,000 records in a + single request. For machine types beyond the listed options, contact TagoIO + support. +- **Horizontal scaling (instances)**: raise the minimum and maximum instance + counts so requests spread across more instances. This is the better fit for + high concurrency and traffic bursts, and it improves fault tolerance. -## Monitoring CPU Metrics +Autoscaling adds and removes instances between the minimum and maximum based on +the CPU threshold and the two cooldown windows. -CPU utilization metrics provide a time-based view of how intensively your API is -using processing resources. As the API handles incoming requests, you should -observe corresponding increases in CPU usage. Monitoring these metrics enables -you to identify peak usage periods and analyze request patterns, offering -actionable insights into when your API experiences the highest load and which -operations may be contributing most to CPU demand. +## Monitoring -## Monitoring Memory Metrics +The **Monitoring** section has a range toggle across 1h, 6h, 12h, 1d, 3d, 7d, +and 30d. Charts show "No data available" until there is data for the window. -Memory usage metrics reflect how much data your application loads into memory -during operation. Many API operations require temporarily storing data in memory -for processing and response generation. During peak usage periods, memory -consumption typically increases due to the simultaneous processing of multiple -requests and the handling of large data payloads. Monitoring memory metrics -helps you detect scenarios where single requests or concurrent operations cause -elevated memory usage, enabling you to optimize data handling and prevent -resource exhaustion. +- **CPU Utilization (%)**: how intensively the API uses processing resources. + Use it to spot peak periods and the operations driving the highest load. +- **Memory Utilization (%)**: how much data the API holds in memory while + serving requests. Use it to catch requests or concurrent operations that push + memory high, then tune data handling. ## Billing Considerations -Because the API service operates on AWS and resource usage directly impacts your -billing, it is important to regularly review your scaling settings and metrics. -Efficient scaling and resource allocation can significantly reduce unnecessary -costs while ensuring your project remains responsive and reliable. +Because the API runs on AWS and resource use drives billing, review the instance +settings and the monitoring charts regularly. Tighter scaling settings cut +unnecessary cost while keeping the project responsive. -For more information on billing models, usage analysis, and cost optimization -strategies, consult the -[TagoIO Billing and Cost Management Documentation](/docs/tagodeploy/project/management/billing.md). +For billing models, usage analysis, and cost details, see the +[Bills](/docs/tagodeploy/project/management/billing.md) page. diff --git a/docs/tagodeploy/project/project-services/in-memory-database.md b/docs/tagodeploy/project/project-services/in-memory-database.md index 053766d8..ca769144 100644 --- a/docs/tagodeploy/project/project-services/in-memory-database.md +++ b/docs/tagodeploy/project/project-services/in-memory-database.md @@ -1,80 +1,76 @@ --- title: "In-Memory Database" -description: "Overview of the distributed in-memory database for caching, queues, and real-time data, including scaling and monitoring." -keywords: [tagodeploy, iot, in-memory database, caching, scaling] +description: "Set the cache machine size and read replicas for the in-memory database, and monitor cache and network metrics." +keywords: [tagodeploy, iot, in-memory database, caching, scaling, monitoring] tags: ["tagodeploy"] slug: /tagodeploy/project/in-memory-database --- # In-Memory Database -The in-memory database in TagoIO aggregates all in-transit memory resources -across multiple active API instances. This system is fundamental to real-time -data processing, high-performance caching, and robust message queuing between -APIs and microservices. By utilizing distributed in-memory queues, TagoIO -prevents service overload and ensures that critical information is retained and -processed, even during failures or traffic spikes. This architecture enables -low-latency data delivery and high availability, supporting demanding enterprise -use cases. +The in-memory database aggregates in-transit memory across active API instances. +It handles real-time data processing, high-frequency caching, and message +queuing between APIs and microservices. Distributed in-memory queues keep +critical information retained and processed during failures or traffic spikes, +which keeps data delivery low-latency and the service available. -## Key Use Cases +This page sets the cache machine size and read replicas. Open it from the +**TagoIO & API** area, under **SERVICES** in the sidebar. -### Real-Time Data Transmission +## Cache Settings -The in-memory database plays a critical role in real-time data delivery. For -example, it enables instantaneous updates to dashboards as soon as new -information becomes available, ensuring users always see the most current data -without delay. +The **Cache settings** section configures machine type and read replicas: -### Caching System +- **Machine**: the machine type for the cache. Default is 2 vCPU / 1GB RAM. +- **Additional reader replicas**: read-only instances added to the cluster. + Default is 0. -TagoIO implements a robust caching mechanism via the in-memory database to -optimize performance for high-frequency requests. Common use cases include token -authentication and other repetitive queries, where cached responses -significantly reduce latency and backend load. +Click **Save** to apply changes. -## Scaling the In-Memory Database +## Key Use Cases -The in-memory database can be scaled to meet your project’s performance and -reliability requirements, using two primary strategies: +### Real-Time Data Transmission -- **Vertical scaling (Machine Tier)**: Involves increasing the CPU and memory - resources allocated to each in-memory database instance. This approach is - effective for handling extreme data ingestion peaks or supporting dashboards - configured to display large volumes of real-time data. +The in-memory database carries real-time data delivery. For example, it updates +dashboards as soon as new information arrives, so users see current data without +delay. -- **Horizontal scaling (Number of machines)**: Adding reader replicas introduces - additional read-only instances to the in-memory database cluster. This - configuration distributes read operations, alleviating load on the primary - instance and improving performance for applications with heavy read access - patterns. +### Caching System -## Recommended Production Configuration +TagoIO caches high-frequency requests through the in-memory database. Common +cases include token authentication and other repeated queries, where cached +responses cut latency and backend load. -For most production environments, TagoIO recommends the following baseline -settings: +## Scaling the In-Memory Database -- **Reader Replicas:** 1 reader replica -- **Machine Specifications:** 2 vCPU / 4GB RAM per instance +Scale the in-memory database to meet your project's performance and reliability +needs using two strategies: -## Monitoring and Metrics +- **Vertical scaling (Machine)**: move to a machine type with more CPU and + memory. This helps with data ingestion peaks or dashboards that display large + volumes of real-time data. +- **Horizontal scaling (reader replicas)**: add read-only instances to the + cluster. This spreads read operations, eases load on the primary instance, and + improves performance for read-heavy access patterns. -Effective monitoring of the in-memory database is essential for maintaining -performance and optimizing resource allocation. Key metrics include: +## Recommended Production Configuration -### Cache Hits +For most production environments, this baseline is a good starting point: -This metric tracks the number of successful cache retrievals over time, -indicating how effectively the cache is serving repeated requests and reducing -backend workload. +- **Machine**: 2 vCPU / 4GB RAM +- **Additional reader replicas**: 1 -### Network Inbound/Outbound +## Monitoring -These metrics measure the volume of data, in bytes, transmitted to and from the -in-memory database. Monitoring network throughput helps identify bottlenecks and -ensures the system is sized appropriately for real-time and high-throughput use -cases. +The **Monitoring** section has a range toggle across 1h, 6h, 12h, 1d, 3d, 7d, +and 30d. Charts show "No data available" until there is data for the window. The +following metrics are available: -By understanding and configuring your in-memory database according to these -guidelines, you can ensure robust, low-latency data delivery and high -availability for all TagoIO services. +- **CPU Utilization (%)**: how intensively the cache uses processing resources. +- **Freeable Memory (BYTES)**: the memory currently available to the cache + instance. +- **Cache Hits (COUNT)**: successful cache retrievals over time, a read on how + well the cache serves repeated requests and reduces backend load. +- **Network Inbound (B/S)** and **Network Outbound (B/S)**: the volume of data, + in bytes per second, transmitted to and from the in-memory database. Use these + to find bottlenecks and check the instance is sized for your throughput. diff --git a/docs/tagodeploy/project/project-services/main-database.md b/docs/tagodeploy/project/project-services/main-database.md index 235d4ec9..c2e43209 100644 --- a/docs/tagodeploy/project/project-services/main-database.md +++ b/docs/tagodeploy/project/project-services/main-database.md @@ -1,60 +1,59 @@ --- title: "Main Database" -description: "Configure backups, scaling, and monitoring for the primary database that stores your TagoIO data." -keywords: [tagodeploy, iot, database, backups, monitoring] +description: "Configure the machine, reader instances, and backups for the primary database that stores your TagoIO data." +keywords: [tagodeploy, iot, database, backups, monitoring, scaling] tags: ["tagodeploy"] slug: /tagodeploy/project/main-database --- # Main Database -The **Database instance** is responsible for storing and maintaining all your -TagoIO data, including profile configurations and device data. If the database -becomes unavailable, the API will not be able to retrieve stored data, which -directly impacts all project functionalities. +The Main Database stores and maintains all your TagoIO data, including profile +configurations and device data. If it becomes unavailable, the API cannot +retrieve stored data, which affects every project feature. -## Backup & Scaling +This page configures the primary database. Open it from the **TagoIO & API** +area, under **SERVICES** in the sidebar. -### Backup Scheduling +## Database Settings -Regular backups are essential to prevent data loss or corruption. You can -configure automated backups to run at intervals aligned with your operational -needs. Each backup is preserved based on a defined **retention period**, which -controls how long it's stored before deletion—allowing a balance between data -protection and storage management. +The **Database settings** section configures machine type, read replicas, and +backup parameters: -For detailed instructions, refer to the [Backups](/docs/tagodeploy/project/management/backups.md) guide. +- **Machine**: the machine type for the database. Default is 2 vCPU / 4GB RAM. +- **Additional reader instances**: read-only instances added alongside the + writer. Default is 0. +- **Backup retention period (days)**: how many days each backup is kept before + deletion. Default is 7. +- **Daily backup schedule**: the time of day, in UTC, when the daily backup + runs. Default is 04:30. -## Automatic Backup Process +Click **Save** to apply changes. -Backups are created automatically every day to ensure consistent data protection -and contain the following key features: +## Backups -- **Daily Schedule**: Backups run automatically on a daily basis -- **Configurable Timing**: You can select the specific time of day for backup - creation -- **Automatic Cleanup**: Backups are automatically deleted after a configurable - number of days to manage storage usage -- **Retention Settings**: The retention period can be customized based on your - needs +Backups run automatically once a day at the scheduled time and are kept for the +retention period, then deleted to manage storage. The schedule and retention are +set here; existing snapshots are listed on the +[Backups](/docs/tagodeploy/project/management/backups.md) page. -### Scaling Your Database +## Scaling Your Database -As application demand grows, you may need to scale the database to handle -increased read/write operations: +As demand grows, you may need to scale the database to handle more read and +write operations: -- **Vertical Scaling (Machine Tier)**: Upgrade your database instance with more - CPU and RAM. This is useful when handling large data submissions or high - write/update activity. -- **Horizontal Scaling (Reader Instances)**: Add read-only instances to improve - performance on read-heavy operations and increase overall service - availability. +- **Vertical scaling (Machine)**: move to a machine type with more CPU and RAM. + This helps with large data submissions or high write and update activity. +- **Horizontal scaling (reader instances)**: add read-only instances to spread + read-heavy operations and improve availability. -## Monitoring & Performance +## Monitoring -To ensure stability and diagnose issues, monitor the following key metrics: +The **Monitoring** section has a range toggle across 1h, 6h, 12h, 1d, 3d, 7d, +and 30d. Charts show "No data available" until there is data for the window. The +following metrics are available: -**CPU Utilization**: As data is read from or written to the database, CPU +**CPU Utilization (%)**: As data is read from or written to the database, CPU resources are consumed to process the data and execute all associated database pipeline operations, including data validation, transaction management, and integrity checks. CPU utilization may exhibit significant spikes during @@ -62,35 +61,27 @@ resource-intensive queries, such as aggregate operations that calculate daily averages over an entire month. Similarly, update operations involving large entity or device datasets can also result in noticeable CPU usage peaks. -**Freeable Memory**: This parameter represents the amount of memory currently -available to the database instance. By default, the database attempts to cache -frequently used queries, utilizing approximately 90% of the freeable memory. As -new queries are cached, the system automatically evicts older cache entries to -make room for newer ones. If the database instance is consistently consuming all -available memory, this typically indicates that the volume or complexity of -incoming requests exceeds the database’s ability to efficiently manage cache -eviction and allocation. In such cases, performance may degrade as the database -struggles to balance memory usage between active queries and cache management. - -**Database Connections**: Displays the number of active connections to your -database, including connections from API instances and other services that -communicate with the database. - -**Read/Write IOPS**: Displays the number of input and output operations -performed each second. When investigating spikes in CPU or memory usage, -correlating these peaks with read and write operation metrics at the same -timestamps can help identify potential causes. Monitoring IOPS alongside -resource utilization provides insight into whether increased disk activity is -contributing to observed performance issues. - -**Network Throughput**: Displays the volume of data in bytes transmitted to and -from the database. +**Freeable Memory (BYTES)**: the memory currently available to the database +instance. By default the database caches frequently used queries, using around +90% of freeable memory, and evicts older entries to make room for newer ones. +Consistently consuming all available memory usually means request volume or +complexity exceeds what the cache can manage, and performance may degrade. + +**Database Connections (COUNT)**: the number of active connections to the +database, including connections from API instances and other services. + +**Read IOPS** and **Write IOPS**: the number of input and output operations per +second. When investigating CPU or memory spikes, lining these up against IOPS at +the same timestamps helps tell whether disk activity is driving the issue. + +**Network Throughput (B/S)**: the volume of data, in bytes per second, +transmitted to and from the database. ## Recommended Production Configuration -For environments supporting up to **10,000 devices**, the following setup is -recommended: +For environments supporting up to **10,000 devices**, this baseline is a good +starting point: - **Machine**: 2 vCPU / 4GB RAM -- **Reader Instances**: 1 -- **Backup Retention Period**: 7 days +- **Additional reader instances**: 1 +- **Backup retention period**: 7 days From 94db770cf6d2131283f44b9fa1c26cfac85b8481 Mon Sep 17 00:00:00 2001 From: Ricardo Stoklosa Date: Fri, 29 May 2026 16:01:21 -0300 Subject: [PATCH 10/15] docs(tagodeploy): refresh deployments, system, and integrations docs --- .../project/configuration/integrations.md | 149 ++++++++---------- .../configuration/system/open-connectors.md | 89 +++++------ .../project/configuration/system/version.md | 76 +++++---- .../project/management/deployments/history.md | 70 ++++---- .../project/management/deployments/logs.md | 59 +++---- .../tagodeploy/project/management/features.md | 143 ++++++++--------- 6 files changed, 277 insertions(+), 309 deletions(-) diff --git a/docs/tagodeploy/project/configuration/integrations.md b/docs/tagodeploy/project/configuration/integrations.md index d936775d..827e6f93 100644 --- a/docs/tagodeploy/project/configuration/integrations.md +++ b/docs/tagodeploy/project/configuration/integrations.md @@ -1,129 +1,112 @@ --- title: "Integrations" -description: "Configure and understand project integrations with third-party services." -keywords: [tagodeploy, iot, integrations, email, sms] +description: "Connect email and SMS providers so your project can send outbound notifications." +keywords: [tagodeploy, iot, integrations, email, sms, sendgrid, twilio] tags: ["tagodeploy"] slug: /tagodeploy/project/configuration/integrations --- -Use Integrations to connect your TagoDeploy instance to third‑party messaging -providers for email and SMS. These settings control how the platform sends 2FA -codes, password resets, invitations, and other system notifications from your -single‑tenant environment. +# Integrations -The Integrations page is available to TagoDeploy administrators only and applies -to the entire instance (all projects and TagoRUN portals that use instance -defaults). +Use Integrations to connect your project to email and SMS providers for outbound +notifications. These settings control how the platform sends 2FA codes, password +resets, invitations, and other system messages. + +The Integrations page lives in the TagoIO & API sidebar under **Integrations**. +The page header reads "Integrations" and the card is titled "Integrations +Management", with the subtitle "Connect email and SMS providers for outbound +notifications." A **Save** action stores your changes. ## What you can configure - Email delivery - SMS delivery -Each channel is optional and can be enabled independently. When disabled, the -platform does not send messages through that channel. - ---- +Each channel is optional and can be enabled independently. When a channel is +disabled, the platform does not send messages through it. ## Email settings Email is used for 2FA, password recovery, user invitations, and any workflow in -your apps that sends email via the platform. +your apps that sends email through the platform. -Fields +Fields: -- **Enable emails:** Master toggle for the email channel. -- **From address:** The email address shown in the From field of outgoing - messages. Use a verified sender for your provider. -- **Provider:** Select the email vendor. Current options include SendGrid. - Contact TagoIO Support to enable additional providers for your instance. -- **API key:** Secret credential for the selected provider. Stored encrypted. - Leave blank to keep the current key when updating other fields. +- **Enable emails**: master toggle for the email channel. Its description reads + "Allow the system to send transactional and notification emails." +- **From address**: the address shown in the From field of outgoing messages. + Use a verified sender for your provider. +- **Provider**: the email vendor. The default is SendGrid. Contact TagoIO support + to enable additional providers for your instance. +- **API key**: the secret credential for the selected provider, stored encrypted. -#### Provider notes: SendGrid +### Provider notes: SendGrid - Create an API key with Mail Send permissions in your SendGrid account. -- Verify the From address or set up a domain authenticated sender to improve +- Verify the From address, or set up a domain authenticated sender, to improve deliverability. -- Rate limits and classification (marketing vs. transactional) are enforced by - your SendGrid plan. - -Common errors and fixes +- Rate limits and message classification are enforced by your SendGrid plan. -- **401/403 from provider:** API key lacks permissions or is invalid. Create a - new key and update the setting. -- **Emails not delivered:** From address not verified or domain authentication - missing. Verify sender/domain in the provider. -- **High spam rate:** Use a dedicated IP or authenticated domain; ensure content - is transactional. +### Common errors and fixes ---- +- **401 or 403 from provider**: the API key is invalid or lacks permissions. + Create a new key and update the setting. +- **Emails not delivered**: the From address is not verified or domain + authentication is missing. Verify the sender or domain in the provider. +- **High spam rate**: use a dedicated IP or an authenticated domain, and keep + content transactional. ## SMS settings SMS is used for 2FA and platform notifications that require text messages. -Fields +Fields: -- **Enable SMS:** Master toggle for the SMS channel. -- **From:** The sender identifier used for SMS: - - In the US/CA, use a 10DLC long code or a toll‑free number that is - registered/verified with your provider. - - In other countries, an alphanumeric sender ID may be supported - (provider‑specific). -- **Provider:** Select your SMS vendor. Current UI supports Twilio. Others may - be enabled per instance. -- **Account SID:** Your provider account identifier (Twilio: Account SID). -- **Authorization token:** The secret token for API access (Twilio: Auth Token). - Stored encrypted. +- **Enable SMS**: master toggle for the SMS channel. Its description reads "Allow + the system to send SMS notifications and alerts." +- **From**: the sender identifier used for SMS. + - In the US and Canada, use a 10DLC long code or a toll-free number that is + registered and verified with your provider. + - In other countries, an alphanumeric sender ID may be supported, depending on + the provider. +- **Provider**: the SMS vendor. The default is Twilio. Others may be enabled per + instance. +- **Account SID**: your provider account identifier (Twilio: Account SID). +- **Authorization token**: the secret token for API access (Twilio: Auth Token), + stored encrypted. -#### Provider notes: Twilio +### Provider notes: Twilio - Make sure the From number is purchased in Twilio and enabled for SMS. -- For US/CA, complete 10DLC or toll‑free verification to avoid filtering. -- Check country permissions in Twilio’s Messaging Geographic Permissions. - -Common errors and fixes +- For the US and Canada, complete 10DLC or toll-free verification to avoid + filtering. +- Check country permissions in Twilio's Messaging Geographic Permissions. -- **400 from provider:** From number not SMS‑enabled or not allowed for the - destination country. Enable SMS or buy a supported number/Sender ID. -- **Message filtering or no delivery:** Registration/verification incomplete - (10DLC/Toll‑free). Complete carrier registration. -- **Rate limiting:** Add messaging services with queueing or request higher - throughput from provider. +### Common errors and fixes ---- +- **400 from provider**: the From number is not SMS-enabled or is not allowed for + the destination country. Enable SMS or buy a supported number or sender ID. +- **Message filtering or no delivery**: carrier registration is incomplete + (10DLC or toll-free). Complete the registration. +- **Rate limiting**: add a messaging service with queueing, or request higher + throughput from the provider. ## Security and operations -- **Secrets management:** API keys and tokens are encrypted at rest. Rotating +- **Secrets management**: API keys and tokens are encrypted at rest. Rotating keys requires admin access. -- **Key rotation:** Update the key in the Integrations page. Leaving the API - key/token field empty keeps the existing secret. -- **Audit:** TagoDeploy doesn't record SMS/Email activities. Use your email/SMS - provider's audit logs to track activities. +- **Key rotation**: update the key on the Integrations page. +- **Audit**: TagoDeploy does not record email or SMS activity. Use your provider's + audit logs to track delivery. ---- +## Recommendations -## Troubleshooting checklist - -- **Provider account limits:** Check per‑minute/per‑day caps. Increase limits if - you see 429/limit errors. -- **Regional restrictions:** Some countries require pre‑registration for SMS - sender IDs or templates. - ---- - -## Requirements and recommendations - -- Use dedicated sender identities per environment (e.g., noreply-dev@, dev - numbers) to avoid cross‑environment confusion. -- Avoid personal mailboxes as From addresses. Use a domain the organization +- Use dedicated sender identities per environment to avoid cross-environment + confusion. +- Avoid personal mailboxes as From addresses. Use a domain your organization controls. -- For production SMS in the US/CA, complete 10DLC or toll‑free verification - before go‑live to prevent blocking. - ---- +- For production SMS in the US and Canada, complete 10DLC or toll-free + verification before go-live to prevent blocking. For help enabling additional providers or configuring private connectivity to providers, contact the TagoIO team at contact@tago.io. diff --git a/docs/tagodeploy/project/configuration/system/open-connectors.md b/docs/tagodeploy/project/configuration/system/open-connectors.md index acff1ae6..f2239732 100644 --- a/docs/tagodeploy/project/configuration/system/open-connectors.md +++ b/docs/tagodeploy/project/configuration/system/open-connectors.md @@ -1,6 +1,6 @@ --- title: "Open Connectors" -description: "Use and synchronize public device and network connectors from TagoIO's open-source Decoders repository." +description: "Sync public device and network connectors into your TagoIO instance from TagoIO's open-source Decoders repository." keywords: [tagodeploy, iot, connectors, decoders, devices] tags: ["tagodeploy"] slug: /tagodeploy/project/system/open-connectors @@ -8,66 +8,51 @@ slug: /tagodeploy/project/system/open-connectors # Open Connectors -[Open Connectors](https://github.com/tago-io/decoders) is a comprehensive -library of public device and network connectors maintained by TagoIO. These +[Open Connectors](https://github.com/tago-io/decoders) is a library of public +device and network connectors maintained by TagoIO. These [connectors](https://help.tago.io/portal/en/kb/articles/466-connector-overview) -enable seamless integration between your project and a wide range of devices and -networks, leveraging the latest decoders and integration logic from the -open-source Decoders repository. By using Open Connectors, you can quickly adopt -new device models as they become available, without the need for custom -development. +route external data into your TagoIO instance and let you adopt new device models +as they become available, without custom development. -## Synchronizing Connectors +Open Connectors is the second section on the **System** page, below the Version +Timeline, reached from the TagoIO & API sidebar under **System**. The section is +titled "Open Connectors" and describes itself as "External connectors routing +data into your TagoIO instance." It includes a "Learn more about open connectors" +link. -To ensure your project uses the most current versions of available connectors, -you can synchronize your connectors with the open-source repository. This is -accomplished by clicking the **Sync decoders** button in your project interface. -When you perform this action, your project's connectors are updated to the -latest versions published in the Decoders library. +## Syncing connectors -During synchronization, all device connectors and network connectors are updated -or added to your project. This process ensures your infrastructure benefits from -the latest features, compatibility improvements, and security patches provided -by the TagoIO community. +To bring the latest connectors into your instance, use the **Sync connectors** +action. This pulls the current versions published in the Decoders library into +your project. -## Connector Update Tracking +Before any connectors are synced, the section shows the empty state "No +connectors synced yet." After a sync, the device and network connectors from the +repository are available in your project. -After synchronization, all connector updates are logged in a synchronization -table. This table provides an audit trail for every time the connectors were -syncronized, including: +## Impact on existing devices -- **FROM**: The version of the connector github repository before the update. -- **TO**: The version of the connector github repository after the update. -- **UPDATED BY IP**: The IP address of the user who performed the - synchronization. -- **UPDATED AT**: The timestamp when the update occurred. +Syncing connectors can change existing devices in your project that already use a +connector from the repository. If a device runs older firmware, changes to a +connector's decoding logic or protocol handling could affect its compatibility +or behavior. Before syncing, review the release notes for the updated connectors +and test changes in a staging environment, especially for devices with legacy +firmware or custom configurations. -## Impact on Existing Devices +## Network connectors and middleware -It is important to note that synchronizing connectors may modify any existing -devices in your project that already utilize a connector from the repository. If -a device is operating with an older firmware version, changes to the -connector—such as updates to decoding logic or protocol handling, could affect -device compatibility or behavior. Before synchronizing, review the release notes -for each updated connector and test changes in a staging environment, especially -for devices with legacy firmware or custom configurations. +Syncing adds network connectors so device data can be decoded. To start receiving +data through a network connector, you also need the matching middleware enabled. +Middlewares are added from the App Catalog under the **Apps** top-nav. Without the +required middleware, data from the network server does not reach your devices and +the connector has nothing to parse. -## Network Connectors and Middleware Activation +## Best practices -When you synchronize, any new network connectors from the repository will be -added to your project to ensure proper decoding of device data. However, to -begin receiving data through these connectors, you must enable the corresponding -middleware for each network on the **Services** page. If the required middleware -is not enabled, data from the network server will not reach your devices, and -the connector will not have any data to parse. - -## Best Practices - -- Always review connector release notes and documentation before synchronizing - to assess the impact of updates. +- Review connector release notes before syncing to assess the impact of updates. - Test connector and network updates in a development or staging environment, - particularly for devices using older firmware versions. -- After synchronization, verify that all required network middleware is enabled - in the **Services** page to ensure data flow from the server to your devices. -- Monitor device and network behavior post-update to ensure everything is - working as expected. + particularly for devices on older firmware. +- After syncing, confirm the required network middleware is enabled so data flows + from the server to your devices. +- Monitor device and network behavior after a sync to confirm everything works as + expected. diff --git a/docs/tagodeploy/project/configuration/system/version.md b/docs/tagodeploy/project/configuration/system/version.md index 4e58fcd1..6d91c352 100644 --- a/docs/tagodeploy/project/configuration/system/version.md +++ b/docs/tagodeploy/project/configuration/system/version.md @@ -1,50 +1,56 @@ --- -title: "Version Management" -description: "Control when your project upgrades to a new platform version and understand affected components and limitations." -keywords: [tagodeploy, iot, version management, updates] +title: "Version Timeline" +description: "Pick the platform version your project runs on, update to a newer release, or roll back to an older one." +keywords: [tagodeploy, iot, version, updates, rollback] tags: ["tagodeploy"] slug: /tagodeploy/project/system/version --- -# Version Management +# Version Timeline -Version management enables you to control when your project infrastructure is -updated to a new release. This functionality allows you to keep your environment -on a stable and thoroughly tested version, only upgrading when you are ready to -adopt new features or bug fixes. This approach minimizes operational risk and -allows you to align infrastructure changes with your internal testing and -release schedules. +The Version Timeline lets you control which platform version your project runs +on. You can move to a newer release when you are ready to adopt new features and +fixes, or roll back to an older one if needed. This keeps your environment on a +version you have reviewed and tested, and lets you align infrastructure changes +with your own release schedule. -Each version release is accompanied by detailed release notes. These notes -provide a comprehensive summary of all changes, enhancements, and bug fixes -included in that version, allowing you to make informed decisions about when to -upgrade. +The Version Timeline is one of the two sections on the **System** page, found in +the TagoIO & API sidebar under **System**. The page header reads "System"; the +card is titled "Version Timeline" with the subtitle "Pick the platform version +this project runs." A **Refresh** button reloads the list. -## Manual Update Process +## Reading the timeline -All updates to your project infrastructure are performed manually. There is no -automated or scheduled update mechanism—an administrator must explicitly trigger -the upgrade to move to a newer version. This gives your team complete control -over the timing and execution of version changes, ensuring that upgrades only -occur when you have fully reviewed and tested the new release. +Versions are listed by date and grouped by where they sit relative to the +version you run today: -## No Rollback Capability +- **Newer Versions**: releases ahead of your current version. A count badge + shows how many are available, the most recent one is tagged "Latest", and each + row has an **Update** action to move to it. +- **Current Version**: the version your project runs now, tagged "Current". +- **Older Versions**: releases behind your current version, each with a + **Rollback** action to return to it. -It is important to note that once an update to a new version has been applied, -it is not possible to roll back to a previous version. The system does not -support rollback or downgrade operations. Additionally, you should maintain -appropriate backup and recovery strategies to mitigate any potential issues -introduced by an upgrade utilizing the -[backup](/docs/tagodeploy/project/management/backups.md) functionality. +Each release comes with notes describing its changes, enhancements, and fixes, +so you can decide when to update or roll back. -## Components Affected by Version Updates +## Updating and rolling back -When you update to a new version, the following infrastructure components may be -affected: +Version changes are manual. There is no automated or scheduled mechanism, so an +administrator explicitly triggers an **Update** to move forward or a +**Rollback** to move back. This gives your team full control over the timing of +version changes. -- **Admin**: Administrative user interface and management tools. -- **TagoRUN**: The runtime environment responsible for executing project - workflows. -- **API**: Backend APIs that provide data access and integration points. -- **Features (Microservices)**: Modular microservices delivering specific +Before changing versions, keep a current backup so you can recover if an upgrade +or rollback surfaces an issue. See the +[backup](/docs/tagodeploy/project/management/backups.md) documentation. + +## Components affected by version changes + +Changing versions may affect the following infrastructure components: + +- **Admin**: administrative user interface and management tools. +- **TagoRUN**: the runtime environment that executes project workflows. +- **API**: backend APIs that provide data access and integration points. +- **Features (Microservices)**: modular microservices delivering specific business or technical functionality. diff --git a/docs/tagodeploy/project/management/deployments/history.md b/docs/tagodeploy/project/management/deployments/history.md index 936a02a8..fdc75e95 100644 --- a/docs/tagodeploy/project/management/deployments/history.md +++ b/docs/tagodeploy/project/management/deployments/history.md @@ -1,49 +1,59 @@ --- -title: "Deployment History" -description: "View past deployments, statuses, and when deployments are triggered in your project." +title: "Deployments" +description: "View the full history of deployments in your project, with status, search, and date filtering." keywords: [tagodeploy, iot, deployments, history, audit] tags: ["tagodeploy"] slug: /tagodeploy/project/deployments/history --- -# Deployment History +# Deployments -The Deployment History section provides a detailed and chronological record of -all deployment activities associated with your project. This feature gives you -comprehensive visibility into both recent and historical deployments, enabling -tracking, auditing, and management of your deployment processes. +The Deployments page keeps a chronological record of every deployment in your +project. It gives you visibility into recent and past deployments so you can +track, audit, and review how your project has changed over time. -While a deployment is in progress, you can not further modify the project. You -will continue to access the previous version of the project until the deployment -is complete. +Open it from the Management sidebar under **Deployments**. The page header reads +"Deployments" and the card is titled "Manage Deployments", with the subtitle +"Complete history of every deployment in this project." + +While a deployment is in progress you can not make further changes to the +project. You keep accessing the previous version until the deployment finishes. ## When do deployments happen? -Deployments occur whenever a modification is made to the project using the -TagoDeploy console. This **does not** include: +A deployment occurs whenever you change the project using the TagoDeploy +console. The following changes do not trigger a deployment: -- Editing MQTT Broker Client/Group/Group Rule/Pipeline settings +- Editing MQTT broker clients, groups, group rules, or pipelines - Adding or removing collaborators - Adding or removing developer accounts -- Adding or Editing Domains +- Adding or editing domains + +When a change needs a deployment, you are taken to the deployment view where you +can watch its status. + +## Browsing the history + +The "History" section lists each deployment, and a refresh button reloads the +list. To find a specific entry, use the controls at the top of the page: + +- A search box (placeholder "Search a deployment...") to match by token or + description. +- A status filter that defaults to "All". +- A "Select Date Range" button to narrow the list to a time window. -If a modification requires a deployment, you will be automatically redirected to -the deployment page, where you can monitor the deployment status. +Each entry records the deployment token or description, the status, and the date +and time of the event. The token is a unique identifier for the deployment. The +status tells you whether it succeeded, is still running, or failed. -## Deployment Record Details +Deployment statuses are: -Each entry in the deployment history captures the deployment token or -description, the deployment status, and the precise date and time of the event. -The deployment token provides a unique identifier for the deployment. The status -field gives immediate insight into whether the deployment was successful, is -still in progress, or encountered errors. The deployment date records when the -event was initiated or logged. +- **Success**: the deployment completed and the resources are operational. +- **In Progress**: the deployment is underway and has not reached a final state. +- **Error**: the deployment hit a failure and did not complete as expected. -Deployment statuses are clearly defined:\ -A status of **Success** indicates the deployment was completed and resources are -fully operational. **In Progress** means the deployment is currently underway -and has not yet reached a final state. **Error** signifies that the deployment -encountered issues or failures and did not complete as expected. +When a project has no deployments yet, the page shows "No deployments yet" with +the note that deployment history appears here once deployments are made. -**Note:** If a deployment fails, please enter contact TagoIO support, please -provide the deployment ID and the date and time of the deployment. +**Note:** if a deployment fails, contact TagoIO support and provide the +deployment ID along with the date and time of the deployment. diff --git a/docs/tagodeploy/project/management/deployments/logs.md b/docs/tagodeploy/project/management/deployments/logs.md index dcf9ffd4..a4911cce 100644 --- a/docs/tagodeploy/project/management/deployments/logs.md +++ b/docs/tagodeploy/project/management/deployments/logs.md @@ -1,36 +1,37 @@ --- -title: "Deployment Logs" -description: "Track deployment progress, understand change management behavior, and identify failures via real-time logs." -keywords: [tagodeploy, iot, deployments, logs, monitoring] +title: "Logs" +description: "View runtime output from the services running in your project, with type, date, and live filters." +keywords: [tagodeploy, iot, logs, monitoring] tags: ["tagodeploy"] slug: /tagodeploy/project/deployments/logs --- # Logs -The Logs section offers a chronological account of your project’s deployment -process. Each log entry records the date and time of deployment actions, -providing real-time visibility into deployment activities. This level of detail -enables you to monitor deployment progress and quickly identify any issues as -they arise, supporting troubleshooting and maintaining a transparent deployment -history. - -Key features of the Logs section include: - -- **Real-Time Tracking:** Each deployment action is timestamped, allowing you to - follow the deployment process step by step and verify that all stages are - completed as expected. -- **Change Management:** Any modification to services automatically triggers a - new deployment. Changes are only applied after the deployment process has - completed and the previous deployment has been removed. This approach ensures - that updates are introduced in a controlled manner, reducing the risk of - configuration drift or partial updates. -- **Immediate Issue Notification:** If the most recent deployment fails, an - orange warning sign will appear at the top of every page within the TagoDeploy - console. This prominent visual alert draws immediate attention to deployment - issues, enabling you to respond and resolve problems without delay. - -**Note:** Logs are specific to the current deployment session. When a new -deployment begins, logs from the previous deployment are cleared and are no -longer accessible. This ensures that you are always viewing the most relevant -and up-to-date information for the active deployment lifecycle. +The Logs page shows runtime output from the services running in your project. +Open it from the Management sidebar under **Logs**. The page header reads "Logs" +and the card is titled "View Logs", with the subtitle "Runtime output from +services running in this project." + +## Filtering and following logs + +Use the controls at the top of the page to focus on what you need: + +- A search box (placeholder "Search logs...") to match entries by text. +- A "Type" filter to limit the output to a specific log type. +- A "Date" filter to narrow logs to a time window. +- A "Refresh" button to reload the current view. +- A "Live" toggle to stream new entries as they arrive. + +When there is no output to show, the page displays "No logs yet" with the note +that logs from your project will appear here. + +## Change management behavior + +Any change to a service automatically triggers a new deployment. Changes are +only applied after the deployment finishes and the previous deployment has been +removed. This keeps updates controlled and reduces the risk of configuration +drift or partial updates. + +If the most recent deployment fails, a warning appears at the top of every page +in the TagoDeploy console so you can respond and resolve the issue without delay. diff --git a/docs/tagodeploy/project/management/features.md b/docs/tagodeploy/project/management/features.md index 64e9e97b..10808e58 100644 --- a/docs/tagodeploy/project/management/features.md +++ b/docs/tagodeploy/project/management/features.md @@ -1,107 +1,90 @@ --- title: "Features" -description: "Enable, disable, and scale native TagoIO features; understand obligatory and optional feature sets." +description: "Enable, disable, and scale native TagoIO features for your project." keywords: [tagodeploy, iot, features, microservices, configuration] tags: ["tagodeploy"] slug: /tagodeploy/project/features/editing-features --- -# Editing Features +# Features -Features in TagoIO are native platform functionalities that can be enabled or -disabled to customize your project’s capabilities. These features extend your -project with services such as data processing, analytics, visualization tools, -and integration modules. While most features can be managed according to your -needs, some are always enabled because they are fundamental to the platform’s -operation and stability. +Features in TagoIO are native platform functionalities you can enable or disable +to tailor your project's capabilities. They extend your project with services +such as data processing, integrations, and notification handling. Most features +can be managed to fit your needs, while some are always enabled because they are +fundamental to platform operation and stability. -## Instance Configuration +The Features page is the entry point of the TagoIO & API section. It is reached +from the "TagoIO & API" breadcrumb tab and from the **Features** item in that +sidebar. The page header reads "Features". -When editing features using the advanced configuration form, you can specify the -minimum and maximum number of instances for each feature. Each instance -increases the feature’s capacity to handle concurrent requests, which is -critical for maintaining performance during periods of high activity. By setting -these parameters, you enable TagoIO to scale resources automatically within your -defined limits. +:::note +On the survey project the Features page rendered without any field content, so +the feature-toggle controls could not be captured directly. The descriptions +below cover the intended behavior. The exact controls, including any +simplified and advanced view switch suggested by the `?view=simplified` URL, +should be confirmed against a project that has a populated feature set. +::: -Each feature, when activated, consumes computational resources from your -allocated infrastructure. The modular design of TagoIO allows you to -independently enable or disable most features, giving you flexibility to -optimize both performance and cost. Because these functionalities are natively -integrated, they are optimized for seamless operation and high efficiency. -Resource allocation for each feature is also scalable, with the platform -dynamically adjusting the number of instances to meet current demand. +## Instance configuration -## Available Features +When the advanced configuration is available, each feature can be given a +minimum and maximum number of instances. Each instance adds capacity to handle +concurrent requests, which matters during periods of high activity. Within the +limits you set, TagoIO scales the feature automatically. -TagoIO provides a comprehensive set of features, each designed to address -specific requirements in your project. The following table summarizes the -available features and their primary functions: +Every enabled feature consumes computational resources from your allocated +infrastructure. Because the design is modular, you can enable or disable most +features independently to balance performance and cost. + +## Available features + +TagoIO provides a set of features grouped into those that are always on and those +you can turn on as needed. Obligatory features: -- **Secrets**: Manages sensitive information such as credentials for analysis - and integrations utilizing the - [TagoIO Secrets](https://help.tago.io/portal/en/kb/articles/secrets), ensuring - secure handling of secrets within your project. -- **Payload Parser**: Processes and parses incoming data from devices, +- **Secrets**: manages sensitive information such as credentials for analyses and + integrations using + [TagoIO Secrets](https://help.tago.io/portal/en/kb/articles/secrets). +- **Payload Parser**: processes and parses incoming data from devices, [connectors](https://help.tago.io/portal/en/kb/articles/466-connector-overview), - and other sources, allowing you to + and other sources, so you can [parse payloads](https://help.tago.io/portal/en/kb/articles/147-payload-parser) as they arrive. -- **Action Handler**: Coordinates and executes internal platform - [actions](https://help.tago.io/portal/en/kb/articles/30-actions), enabling - automated responses to different system events and user-defined triggers. -- **Action - Post Data to Endpoint**: Sends data to external endpoints when - specific actions are triggered, supporting real-time integrations with - third-party systems. -- **Action - Notification**: Delivers notifications as part of automated - workflows, enabling users to receive alerts based on defined conditions. -- **Action - TagoRUN Notifications**: Sends +- **Action Handler**: coordinates and executes internal platform + [actions](https://help.tago.io/portal/en/kb/articles/30-actions) in response to + system events and user-defined triggers. +- **Action - Post Data to Endpoint**: sends data to external endpoints when + specific actions are triggered. +- **Action - Notification**: delivers notifications as part of automated + workflows. +- **Action - TagoRUN Notifications**: sends [targeted notifications](https://help.tago.io/portal/en/kb/articles/223-notifications-for-users) - directly to TagoRUN users, facilitating in-platform communication and user - engagement. + to TagoRUN users. Optional features: -- **Action - SMS (Twilio)**: Sends SMS messages using the - [Twilio](https://www.twilio.com/) service, allowing for automated mobile - notifications. -- **Action - Email (Sendgrid)**: Sends emails via the - [Sendgrid](https://sendgrid.com/) service, supporting automated email - communications within your workflows. -- **Action - Email (SMTP)**: Sends emails using standard SMTP servers, providing - a flexible option for integrating email notifications. -- **Action - Queue (AWS SQS)**: Sends messages to - [AWS SQS](https://docs.aws.amazon.com/sqs/) queues, enabling asynchronous - processing and integration with AWS-based workflows. -- **Action - Whatsapp (Twilio)**: Sends WhatsApp messages using Twilio, allowing - for direct messaging and notifications through WhatsApp. -- **Action - SMS (AWS SNS)**: Sends SMS messages using - [AWS Simple Notification Service](https://docs.aws.amazon.com/sns/) (SNS), - providing another option for scalable SMS delivery. -- **Action - SES (AWS SES)**: Sends emails using - [AWS Simple Email Service](https://docs.aws.amazon.com/ses/) (SES), supporting - scalable and reliable email delivery. - -Note that the optional features are related to optional action types, more -information about actions can be found in the +- **Action - SMS (Twilio)**: sends SMS messages using + [Twilio](https://www.twilio.com/). +- **Action - Email (Sendgrid)**: sends emails via + [Sendgrid](https://sendgrid.com/). +- **Action - Email (SMTP)**: sends emails using standard SMTP servers. +- **Action - Queue (AWS SQS)**: sends messages to + [AWS SQS](https://docs.aws.amazon.com/sqs/) queues for asynchronous processing. +- **Action - Whatsapp (Twilio)**: sends WhatsApp messages using Twilio. +- **Action - SMS (AWS SNS)**: sends SMS messages using + [AWS Simple Notification Service](https://docs.aws.amazon.com/sns/). +- **Action - SES (AWS SES)**: sends emails using + [AWS Simple Email Service](https://docs.aws.amazon.com/ses/). + +The optional features map to optional action types. For more on actions, see the [Defining Actions](https://help.tago.io/portal/en/kb/articles/122-defining-actions#Push_Notification_to_myself) article. -Each feature can be enabled or disabled according to your project’s -requirements, except for those that are essential for core platform operations. -The number of instances for each feature can be configured to match your -workload, ensuring efficient and reliable service delivery. Feature status and -configuration are managed through the platform interface, giving you clear -visibility and control over your project’s active functionalities. - -## Resource Considerations - -To manage features effectively, consider the following: +## Resource considerations -- Ensure you have sufficient computational resources available for all enabled - features. Monitor how your selected combination of features impacts overall - system performance, and regularly review resource consumption to optimize - costs. As your project grows, plan scaling requirements in advance to maintain - an optimal balance between performance and efficiency. +To manage features effectively, keep enough computational resources available for +everything you enable. Watch how your combination of features affects overall +performance, review resource consumption regularly to control costs, and plan +scaling ahead as your project grows. From 4e2ee9f3a9021d15e62c4e5adf368c1b661ab8c6 Mon Sep 17 00:00:00 2001 From: Ricardo Stoklosa Date: Fri, 29 May 2026 16:01:21 -0300 Subject: [PATCH 11/15] docs(tagodeploy): refresh mqtt docs and add connections and instances --- .../services/mqtt/acl-permissions.md | 34 +++---- docs/tagodeploy/services/mqtt/certificates.md | 43 ++++---- docs/tagodeploy/services/mqtt/clients.md | 58 ++++++----- docs/tagodeploy/services/mqtt/connections.md | 46 +++++++++ docs/tagodeploy/services/mqtt/credentials.md | 15 ++- docs/tagodeploy/services/mqtt/group-rules.md | 85 ++++++++-------- docs/tagodeploy/services/mqtt/groups.md | 52 ++++++---- docs/tagodeploy/services/mqtt/index.md | 46 ++++++--- docs/tagodeploy/services/mqtt/instances.md | 39 ++++++++ docs/tagodeploy/services/mqtt/pipelines.md | 97 +++++++++---------- .../services/mqtt/topic-mappings.md | 20 ++-- 11 files changed, 335 insertions(+), 200 deletions(-) create mode 100644 docs/tagodeploy/services/mqtt/connections.md create mode 100644 docs/tagodeploy/services/mqtt/instances.md diff --git a/docs/tagodeploy/services/mqtt/acl-permissions.md b/docs/tagodeploy/services/mqtt/acl-permissions.md index 2f604332..9ce535ea 100644 --- a/docs/tagodeploy/services/mqtt/acl-permissions.md +++ b/docs/tagodeploy/services/mqtt/acl-permissions.md @@ -8,32 +8,28 @@ slug: /tagodeploy/project/mqtt/acl-permissions # ACL Permissions -ACL (Access Control List) permissions are security rules that define what MQTT -topics devices in a group can access and what operations they can perform on -those topics. They serve as the foundation for controlling how your IoT devices -interact with the MQTT broker. +ACL (Access Control List) permissions are the rules that decide which MQTT +topics a client can access and what it can do on them. There is no separate ACL +Permissions page in the broker. ACL permissions live inside [Groups](./groups): +each group holds a list of permission rows, and a client inherits them through +the groups it is assigned to by [Group Rules](./group-rules). -## What are ACL Permissions? +## What an ACL permission is -ACL permissions work as fine-grained access controls that specify: +Each permission is a single rule with three parts: -- **Which topics** devices can access (using topic patterns and wildcards) -- **What operations** they can perform (publish, subscribe, or both) -- **Access levels** (allow or deny specific topic patterns) - -These permissions are applied at the group level, meaning all clients assigned -to a group inherit the same ACL permissions. This provides a scalable way to -manage access control across multiple devices with similar requirements. +- **Permission**: **Allow** or **Deny** the matching access. +- **Action**: **Subscribe** or **Publish**. +- **Topic**: the topic the rule applies to, with MQTT wildcards supported. ## How ACL Permissions Work -When a device attempts to publish a message to a topic or subscribe to receive -messages from a topic, the MQTT broker checks the ACL permissions assigned to -the device's group. The broker will: +When a device tries to publish to a topic or subscribe to one, the broker checks +the permissions in the device's groups. The broker will: -1. **Evaluate the topic pattern** against the configured ACL rules -2. **Check the requested operation** (publish or subscribe) -3. **Grant or deny access** based on the matching ACL permission rules +1. **Evaluate the topic** against the configured rules +2. **Check the action** (subscribe or publish) +3. **Grant or deny access** based on the matching rule ## Topic Patterns and Wildcards diff --git a/docs/tagodeploy/services/mqtt/certificates.md b/docs/tagodeploy/services/mqtt/certificates.md index 5c00e4d1..e5c3d837 100644 --- a/docs/tagodeploy/services/mqtt/certificates.md +++ b/docs/tagodeploy/services/mqtt/certificates.md @@ -8,34 +8,33 @@ slug: /tagodeploy/project/mqtt/certificates # Certificates -This section allows you to enable certificates for your MQTT broker to enable -TLS/SSL encryption. +Provide TLS certificates to encrypt broker traffic and verify clients. The +Certificates page is a form on the MQTT service. Edit the fields and use the +Save button in the page header to stage your changes, which take effect after +you deploy. -## What are Certificates? +## What certificates do -Certificates are used to secure the communication between the MQTT broker and -the devices. They provide: +Certificates secure the communication between the MQTT broker and your devices: -- **Device Authentication**: Authenticate the devices connecting to the broker -- **Encrypted Communication**: Encrypt data transmission between devices and the +- **Encrypted communication**: encrypt data in transit between devices and the broker -- **Secure Connections**: Establish trusted connections using TLS/SSL protocols +- **Trusted connections**: establish connections using TLS +- **Client verification**: with MTLS, verify each connecting device by its + certificate -## Enabling Certificates +## Enabling a custom certificate -To enable certificates, click the "Enable certificates" button. You will then be -redirected to a page where you can upload the required certificate files. +Turn on **Enable Custom Certificate** to provide your own certificate material. +The form then accepts three values, each in its own text area with a copy and +expand control: -### Required Certificate Files +- **CA Certificate**: the Certificate Authority certificate +- **Server Certificate**: the server certificate +- **Server Key**: the private key for the server certificate -You'll need the following certificate components: +## Mutual TLS -- **CA Certificate**: The Certificate Authority certificate -- **Server Certificate**: The server-specific certificate -- **Server Private Key**: The private key for the server certificate - -## Additional Security Features - -When certificates are enabled, you can also enable **MTLS (Mutual TLS)** for -enhanced security, which requires both the client and server to authenticate -each other using certificates. +Turn on **Enable MTLS** to require mutual TLS. With MTLS the broker requires a +custom certificate, and both the client and the broker authenticate each other +using certificates. diff --git a/docs/tagodeploy/services/mqtt/clients.md b/docs/tagodeploy/services/mqtt/clients.md index ba783de9..e0765cc9 100644 --- a/docs/tagodeploy/services/mqtt/clients.md +++ b/docs/tagodeploy/services/mqtt/clients.md @@ -8,12 +8,16 @@ slug: /tagodeploy/project/mqtt/clients # Clients -This section allows you to create, edit and delete the clients that can connect -to your MQTT broker. The existing clients are displayed in a table with the -following columns: +Clients are the credentials that devices use to authenticate with the broker. +This page lists, creates, edits, and deletes them. Existing clients show in a +table with these columns: -- Name -- Authentication Type +- **Client Name** (sortable) +- **Authentication** +- **Actions** (a per-row menu) + +Use the search box to filter by client name. The table pages through results +with the count and page controls at the bottom. ## What are Clients? @@ -41,37 +45,45 @@ When a device attempts to connect to the MQTT broker: 4. **Permission Application**: The client inherits all ACL permissions from its assigned groups -## Authentication Types +## Authentication + +A client authenticates with one of two methods, shown in the Authentication +column as either **Credentials** or **Certificate**. + +### Credentials -Currently, there is a single authentication method: +Username and password authentication. The device connects using: -### Username/Password Authentication +- **Username**: a unique identifier for the client +- **Password**: a secret that validates the client's identity -The standard authentication method where devices connect using: +Credentials can be paired with a certificate for an extra layer of trust. -- **Username**: A unique identifier for the client -- **Password**: A secure credential that validates the client's identity +### Certificate + +Authentication backed by a client certificate, verified by the broker when +custom certificates and MTLS are enabled on the Certificates page. ## Managing Clients -### Creating a New Client +### Creating a new client + +Click **New Client** to open the dialog. Set: -To create a new client, click the "New client" button. You will then be -redirected to a page where you can configure: +- **Name**: a descriptive name to identify the client +- **Authentication**: choose Credentials and fill in the **Username** and + **Password** -- **Client Name**: A descriptive name to identify the client in the system -- **Username**: The username that devices will use to connect -- **Password**: A secure password for authentication +Click **Create client** to add it. -### Editing a Client +### Editing a client -To edit a client, click on the client's three-dot menu button and then select -the "Edit" option. You can modify the client's name, username, and password. +Open the client's row menu and select Edit to change its name and +authentication. -### Deleting a Client +### Deleting a client -To delete a client, click on the client's three-dot menu button and then select -the "Delete" option. +Open the client's row menu and select Delete. ## Modification Impact diff --git a/docs/tagodeploy/services/mqtt/connections.md b/docs/tagodeploy/services/mqtt/connections.md new file mode 100644 index 00000000..9c763b69 --- /dev/null +++ b/docs/tagodeploy/services/mqtt/connections.md @@ -0,0 +1,46 @@ +--- +title: "MQTT Connections" +description: "Live view of the devices currently connected to your project's MQTT broker." +keywords: [tagodeploy, iot, mqtt, connections, sessions] +tags: ["tagodeploy", "mqtt"] +slug: /tagodeploy/project/mqtt/connections +--- + +# Connections + +This page is a live view of the devices currently connected to the broker. It +reads live broker state, so it shows who is connected right now rather than the +clients you have defined. There is no create action, the page is read-only. + +## What a connection is + +A connection is a live session on the broker. It is not the same as a client or +as topic access: + +- A **connection** is one client connected to the broker right now. When the + client disconnects, its row drops off the list. +- A **client** is the set of credentials that authenticate a device. Clients + are created on the Clients page and exist whether or not anyone is connected. +- **Topic access** is who may publish or subscribe to which topics. That is + controlled by Groups and Group Rules, not by this page. + +One client can open several connections at once, and each shows up as its own +row. + +## Reading the table + +Each row describes one live session: + +- **MQTT Client ID** is the client identifier sent in the connect packet. +- **IP Address** is the source address the broker sees for the session. +- **Protocol** is the connection protocol, shown as MQTT. +- **Keep-Alive** is the negotiated keep-alive interval in seconds. +- **Connected At** is when the session opened, in UTC. This column is sortable. +- **Group** is the group the client is assigned to. + +## Finding and paging through sessions + +Use the search box to filter by MQTT Client ID. The table pages through results +with the count and the previous and next controls at the bottom. + +When no device is connected, the page shows an empty state instead of the table. diff --git a/docs/tagodeploy/services/mqtt/credentials.md b/docs/tagodeploy/services/mqtt/credentials.md index e7152078..c15234e1 100644 --- a/docs/tagodeploy/services/mqtt/credentials.md +++ b/docs/tagodeploy/services/mqtt/credentials.md @@ -6,7 +6,16 @@ tags: ["tagodeploy", "mqtt"] slug: /tagodeploy/project/mqtt/credentials --- -### Credentials +# Credentials -The username and password your device will utilize to connect to the MQTT -broker. +Credentials are one of the two authentication types a client can use to connect +to the MQTT broker, the other being a certificate. There is no separate +Credentials page. You set credentials when you create or edit a client on the +[Clients](./clients) page. + +Credentials are a username and password: + +- **Username**: a unique identifier for the client. +- **Password**: the secret that validates the client's identity. + +Credentials can be paired with a certificate for an extra layer of trust. diff --git a/docs/tagodeploy/services/mqtt/group-rules.md b/docs/tagodeploy/services/mqtt/group-rules.md index 13bd18d1..9ebae50a 100644 --- a/docs/tagodeploy/services/mqtt/group-rules.md +++ b/docs/tagodeploy/services/mqtt/group-rules.md @@ -8,51 +8,58 @@ slug: /tagodeploy/project/mqtt/group-rules # Group Rules -This section allows you to create, edit and delete group rules that define which -clients have access to which groups in your MQTT broker. Group rules are -displayed in a table with the following columns: +Group rules assign clients to groups automatically based on matching +conditions. The rules are edited inline on this page, with each rule as a row. +Use **New rule** to add a row and the **Save** button in the page header to +stage your changes, which take effect after you deploy. Each row has these +columns: -- Client Type -- Client IDs/MQTT ID -- Groups +- **Match By** +- **Value** +- **Groups** +- a remove control + +The footer shows how many rules are configured. ## What are Group Rules? -Group rules are assignments that connect clients to groups, determining which -devices can access specific group permissions. They act as the bridge between -individual clients (devices) and the groups that define their access permissions -through ACL rules. +Group rules are the bridge between clients and the groups that grant their +permissions. Each rule matches a connecting client by some condition and +assigns it to one or more groups. A matched client inherits the combined ACL +permissions of every group the rule assigns. + +## Match By -Group rules work by specifying: +Each rule matches on one of three conditions, set in the **Match By** column. +The **Value** field changes to suit the choice: -- **Client Type**: Whether the rule applies to specific client IDs or MQTT - client identifiers -- **Target Clients**: The specific client IDs or MQTT ID patterns that the rule - applies to -- **Group Assignment**: Which groups the specified clients should be assigned to +### Certificate Fingerprint -## Client Types +Match a client by the fingerprint of its certificate. The Value is the +fingerprint text, for example `SHA256:...`. -Group rules support two types of client identification: +### MQTT Client ID + +Match a client by the MQTT client identifier it sends during connection. The +Value is the identifier to match. This accommodates clients that connect with +their own identifiers. ### Client -When the client type is set to "client", the rule applies to specific client IDs -that have been created in the Clients section. This provides direct assignment -of named clients to groups. +Match a named client created on the Clients page. The Value becomes a picker +where you select the client by name. -### MQTT ID +## Groups -When the client type is set to "mqtt id", the rule applies to MQTT client -identifiers used during the connection process. This allows for pattern-based -assignments and can accommodate clients that connect with dynamic identifiers. +The **Groups** column is a multi-select. Pick one or more groups, shown as +chips, for the matched client to join. ## How Group Rules Work When a device connects to the MQTT broker: -1. **Client Identification**: The broker identifies the connecting client - through either the client credentials or MQTT client ID +1. **Client Identification**: The broker identifies the connecting client by + its certificate fingerprint, its MQTT client ID, or its named client 2. **Rule Evaluation**: The broker checks the group rules to determine which groups the client should be assigned to 3. **Permission Application**: The client inherits all ACL permissions from the @@ -62,30 +69,26 @@ When a device connects to the MQTT broker: ## Managing Group Rules -Unlike other sections in the MQTT service, group rules can be managed directly -on the main page without using dropdown menus: +Unlike most sections in the MQTT service, group rules are edited directly on the +page with no dialog or row menu: ### Creating a Group Rule -To create a new group rule, use the creation interface on the group rules page -where you can: +Click **New rule** to add a row, then: -- Select the client type (client or MQTT ID) -- Specify the client IDs or MQTT ID pattern -- Choose which groups to assign to the specified clients +- Choose the **Match By** condition (Certificate Fingerprint, MQTT Client ID, or + Client) +- Enter or pick the **Value** to match +- Select the **Groups** to assign ### Editing a Group Rule -To edit an existing group rule, modify the rule directly on the page to update: - -- The client type or identification method -- The list of client IDs or MQTT ID patterns -- The group assignments +Change the Match By, Value, or Groups directly on the row. ### Deleting a Group Rule -To delete a group rule, remove it directly from the page. This will revoke the -group assignments for the specified clients. +Use the remove control on the row to drop the rule, which revokes those group +assignments. In both cases, use **Save** to stage the change. ## Modification Impact diff --git a/docs/tagodeploy/services/mqtt/groups.md b/docs/tagodeploy/services/mqtt/groups.md index 75583e80..01a75fce 100644 --- a/docs/tagodeploy/services/mqtt/groups.md +++ b/docs/tagodeploy/services/mqtt/groups.md @@ -8,37 +8,53 @@ slug: /tagodeploy/project/mqtt/groups # Groups -This section allows you to create, edit and delete the groups that define how -your clients can interact with the MQTT broker. The existing groups are -displayed in a table with the following columns: +A group bundles ACL permissions that allow or deny access to topics. This page +lists, creates, edits, and deletes groups. Existing groups show in a table with +these columns: -- Name -- Description -- ACL Permissions +- **Name** +- **Description** +- **ACL Permissions** (the number of permission rows in the group) + +Use the search box to filter by group name. ## What are groups? -Groups are collections of permissions that define what topics clients can or -cannot subscribe and publish to. They are identified by a name and a -description. Groups are used in conjunction with group rules to control which -clients can connect to the broker and which topics they are authorized to -access. +Groups are collections of ACL permissions that define which topics clients can +publish to and subscribe to. Each group has a name and a description. Group +Rules assign clients to groups, and a client inherits the combined permissions +of every group it belongs to. + +## ACL permissions + +Each group holds a list of ACL (Access Control List) permissions. A permission +is a single rule with three parts: + +- **Permission**: **Allow** or **Deny** the matching access. +- **Action**: **Subscribe** or **Publish**. +- **Topic**: the topic the rule applies to. MQTT wildcards are supported, where + `+` matches a single level (`sensors/+/temperature`) and `#` matches every + level below a point (`sensors/#`). + +When a device publishes or subscribes, the broker checks the device's groups +and grants or denies the operation based on the matching rules. ### Creating a new group -To create a new group, click the "New group" button. You will then be redirected -to a page where you can fill in the group's name, description and ACL -permissions. +Click **New Group** to open the dialog and set the **Name** and +**Description**. Under **ACL Permissions**, use **Add permission** to add the +first rule, then **New permission** to add more. Each row sets a Permission, an +Action, and a Topic, with a remove control to drop it. Click **Create group** +to save. ### Editing a group -To edit a group, click on the group's three-dot menu button and then select the -"Edit" option. +Open the group's row menu and select Edit to change its name, description, and +permission rows. ### Deleting a group -To delete a group, click on the group's three-dot menu button and then select -the "Delete" option. +Open the group's row menu and select Delete. ## Modification/Deletion Impact diff --git a/docs/tagodeploy/services/mqtt/index.md b/docs/tagodeploy/services/mqtt/index.md index 869e5c6b..7d6df678 100644 --- a/docs/tagodeploy/services/mqtt/index.md +++ b/docs/tagodeploy/services/mqtt/index.md @@ -9,7 +9,7 @@ slug: /tagodeploy/project/mqtt The TagoDeploy MQTT Broker is a fully managed MQTT service that runs inside your private TagoDeploy instance. It gives you a dedicated, single-tenant MQTT infrastructure with enterprise security, fine-grained access control, and -built-in routing to TagoIO—separate from the public, multi-tenant TagoIO MQTT +built-in routing to TagoIO, separate from the public, multi-tenant TagoIO MQTT broker. Use it to deploy one or more private brokers, authenticate devices, enforce @@ -20,11 +20,10 @@ performance and full administrative control. - Private, isolated MQTT infrastructure within your TagoDeploy environment - TLS encryption with custom certificate management -- Advanced authentication (per client) and ACLs via Groups -- Real-time visibility of connections and activity +- Per-client authentication and topic access control through Groups +- Live visibility of connected devices - Multi-broker support in the same TagoDeploy instance -- Global deployment across 12+ AWS regions -- Integrated pipelines to deliver MQTT data to your API instance +- Pipelines that forward MQTT messages to your API instance @@ -32,18 +31,35 @@ performance and full administrative control. The broker processes data in three stages: -1. Authenticate: Devices connect over TLS using client credentials you define. -2. Authorize: Groups and ACLs control publish/subscribe permissions per topic. -3. Route: Pipelines forward matched topics to your API instance with the +1. Authenticate: devices connect over TLS using clients you define. +2. Authorize: Groups and their ACL permissions control publish and subscribe + access per topic, and Group Rules assign clients to those groups. +3. Route: Pipelines forward mapped topics to your API instance with the required authorization and network tokens. +## MQTT sub-pages + +The broker service splits its configuration across these pages: + +- **Overview**: broker name, service URL, and service controls. +- **Instances**: machine size and autoscaling for the broker service. +- **Settings**: broker-level configuration. +- **Clients**: credentials that devices use to authenticate. +- **Groups**: bundles of ACL permissions that allow or deny topic access. +- **Group Rules**: rules that assign clients to groups automatically. +- **Connections**: live view of devices currently connected. +- **Pipelines**: forward incoming MQTT messages to external services, with + topic mappings on the same page. +- **Certificates**: TLS certificates that encrypt broker traffic and verify + clients. + ## Typical setup -- Create the MQTT service in your region and track deployment in the console. +- Add the Broker from the App Catalog and track its deployment. - Get the broker endpoint from Domains. -- Configure authentication (Client IDs, usernames, passwords). -- Define Groups and topic permissions (publish/subscribe). -- Link auth to Groups with ACLs. -- Create a Network and payload parser (e.g., extract serial, map to device). -- Configure a Pipeline: target API endpoint, topics, and credentials. -- Send data using your assigned credentials and topics. +- Create clients with credentials or certificate authentication. +- Define Groups with ACL permissions for publish and subscribe access. +- Use Group Rules to assign clients to groups. +- Configure a Pipeline with the target API URL and tokens, then map topics + to it. +- Connect your devices using their credentials and authorized topics. diff --git a/docs/tagodeploy/services/mqtt/instances.md b/docs/tagodeploy/services/mqtt/instances.md new file mode 100644 index 00000000..242395cd --- /dev/null +++ b/docs/tagodeploy/services/mqtt/instances.md @@ -0,0 +1,39 @@ +--- +title: "MQTT Instances" +description: "Set the machine size and autoscaling range for the MQTT broker service and watch its CPU and memory." +keywords: [tagodeploy, iot, mqtt, instances, autoscaling] +tags: ["tagodeploy", "mqtt"] +slug: /tagodeploy/project/mqtt/instances +--- + +# Instances + +The Instances page controls how the MQTT broker service scales. From here you +pick the machine size, set the autoscaling range, tune the thresholds, and read +CPU and memory charts for the service. + +## Instance settings + +The settings are staged and applied through the project deploy flow, so a change +here takes effect only after you deploy it. Use the **Save** button in the page +header to stage your edits. The button stays disabled until you change +something. + +- **Machine** is the vCPU and RAM tier each instance runs on, for example + 1 vCPU / 2GB RAM. The list of tiers is capped by your project plan. +- **Minimum Instances** and **Maximum Instances** set the floor and ceiling for + how many copies of the broker run. The minimum cannot be larger than the + maximum. +- **Scale on CPU Utilization** is the CPU percentage that triggers autoscaling. + When average CPU crosses this value, more instances are added up to the + maximum. +- **Cooldown for Scaling Up** and **Cooldown for Scaling Down** are wait periods + in seconds that the service holds before adding or removing instances again, + so it does not react to short spikes. + +## Monitoring + +Below the settings, two charts plot CPU Utilization and Memory Utilization as +percentages over time. Pick a time range from 1h to 30d for both charts at once. +Use these to judge whether the current machine size and instance range match the +load your devices put on the broker. diff --git a/docs/tagodeploy/services/mqtt/pipelines.md b/docs/tagodeploy/services/mqtt/pipelines.md index 8f5f0bae..927f3f0c 100644 --- a/docs/tagodeploy/services/mqtt/pipelines.md +++ b/docs/tagodeploy/services/mqtt/pipelines.md @@ -8,84 +8,75 @@ slug: /tagodeploy/project/mqtt/pipelines # Pipelines -This section allows you to create, edit and delete the pipelines that process -data from your MQTT broker. The existing pipelines are displayed in a table with -the following columns: +Pipelines forward incoming MQTT messages to external services. This page lists, +creates, edits, and deletes them, and it also holds the Topic Mappings that +route topics to pipelines. Existing pipelines show in a table with these +columns: -- Name -- Description +- **NAME** (sortable) +- **DESCRIPTION** +- **STATUS** (for example, Active) + +Use the search box to filter by pipeline name. ## What are Pipelines? -Pipelines are data processing workflows that automatically handle messages -received from the MQTT broker and forward them to TagoIO instances. They serve -as the bridge between your MQTT devices and TagoIO's data processing and -visualization capabilities. +Pipelines are the bridge between your MQTT devices and an external service such +as a TagoIO instance. A pipeline forwards the messages from its mapped topics to +the configured endpoint with the right tokens. Pipelines work by: -- **Listening**: Monitoring specific MQTT topics for incoming messages -- **Processing**: Handling the data from MQTT messages -- **Forwarding**: Sending processed data to designated TagoIO instances +- **Receiving**: taking messages from the topics mapped to the pipeline +- **Forwarding**: sending them to the configured API URL with the network and + authorization tokens ## How Pipelines Work -When a message is published to an MQTT topic that has an associated pipeline: - -1. **Message Reception**: The MQTT broker receives the message on the monitored - topic -2. **Pipeline Trigger**: The associated pipeline is automatically triggered -3. **Data Processing**: The pipeline processes the message data according to its - configuration -4. **Data Forwarding**: Processed data is sent to the configured TagoIO instance - -## Pipeline Configuration Requirements - -To create a functional pipeline, you need: +When a message is published to a topic mapped to a pipeline: -- **API Endpoint**: The URL of the TagoIO instance where data should be sent -- **Authorization Token**: The authentication token for the TagoIO profile -- **Network Token**: The token identifying the network the device belongs to -- **Topic Mappings**: Assignment of MQTT topics to the pipeline +1. **Reception**: the broker receives the message on the mapped topic +2. **Match**: the topic mapping forwards it to the pipeline +3. **Forwarding**: the pipeline sends the message to its API URL with the + network and authorization tokens ## Managing Pipelines ### Creating a Pipeline -To create a new pipeline, click the "New pipeline" button. You will be -redirected to a configuration page where you can specify: +Click **New pipeline** to open the dialog. The API URL is generated from your +project settings by default. Set: -- **Pipeline Name**: A descriptive name for identification -- **Description**: Details about the pipeline's purpose -- **TagoIO Configuration**: API endpoint, authorization token, and network token +- **NAME**: a descriptive name +- **DESCRIPTION**: what the pipeline is for +- **API URL**: the endpoint to forward messages to (default + `https://api.tagoio.net`) +- **NETWORK TOKEN**: the token identifying the network +- **AUTHORIZATION TOKEN**: the token that authorizes the request -### Editing a Pipeline +Click **Create pipeline** to save. -To edit a pipeline, click on the three-dot menu button and use the edit option. -You will be redirected to the configuration page where you can modify: +### Editing a Pipeline -- Pipeline name and description -- TagoIO instance connection details -- Authentication and network tokens +Open the pipeline's row menu and use Edit to change its name, description, API +URL, and tokens. ### Deleting a Pipeline -To delete a pipeline, click on the three-dot menu button and use the delete -option. +Open the pipeline's row menu and use Delete. ## Topic Mappings -Pipelines work in conjunction with Topic Mappings to determine which MQTT topics -trigger data processing. Each pipeline can be associated with multiple topics, -and the same topic can trigger multiple pipelines for different processing -workflows. - -## Integration Benefits +Topic Mappings route MQTT topics to specific pipelines. They live in a section +on this same Pipelines page, edited inline with no dialog. Use **New mapping** +to add a row and the **Save** button to stage your changes, which take effect +after you deploy. Each row has: -Pipelines enable seamless integration between MQTT devices and TagoIO by: +- **TOPIC**: the topic to match, for example `devices/+/telemetry`. MQTT + wildcards are supported, where `+` matches a single level and `#` matches + every level below a point. +- **PIPELINE**: the pipeline to forward matching messages to, picked by name. +- a remove control. -- **Automated Processing**: Eliminating manual data transfer steps -- **Real-time Data Flow**: Providing immediate data availability in TagoIO -- **Scalable Architecture**: Supporting multiple devices and data streams -- **Flexible Configuration**: Allowing different processing rules for different - device types +A single topic can map to more than one pipeline, and the same pipeline can +serve many topics. diff --git a/docs/tagodeploy/services/mqtt/topic-mappings.md b/docs/tagodeploy/services/mqtt/topic-mappings.md index 32f70218..69eb8d9a 100644 --- a/docs/tagodeploy/services/mqtt/topic-mappings.md +++ b/docs/tagodeploy/services/mqtt/topic-mappings.md @@ -8,14 +8,22 @@ slug: /tagodeploy/project/mqtt/topic-mappings # Topic Mappings -This section allows you to assign MQTT topics to pipelines. When a message is -published to a mapped topic, the associated pipeline will be triggered. +Topic Mappings route MQTT topics to specific pipelines. When a message is +published to a mapped topic, it is forwarded to the pipeline. There is no +separate Topic Mappings page. They live in a section on the +[Pipelines](./pipelines) page, edited inline with no dialog. -## What are Topic Mappings? +## Editing topic mappings -Topic Mappings connect MQTT topics to data pipelines. A single topic can be -mapped to multiple pipelines, allowing the same message to trigger different -processing workflows. +Use **New mapping** to add a row, and the **Save** button to stage your changes, +which take effect after you deploy. Each row has: + +- **TOPIC**: the topic to match, for example `devices/+/telemetry`. +- **PIPELINE**: the pipeline to forward matching messages to, picked by name. +- a remove control. + +A single topic can map to more than one pipeline, so the same message can reach +several pipelines. ## MQTT Topic Patterns From 3fe7e43e9b392f7610acef9c6c90af28e34b3adf Mon Sep 17 00:00:00 2001 From: Ricardo Stoklosa Date: Fri, 29 May 2026 16:01:21 -0300 Subject: [PATCH 12/15] docs(tagodeploy): refresh container docs and add instances --- .../services/container/docker-image.md | 176 ++++----------- .../container/environment-variables.md | 47 ++-- .../services/container/instances.md | 40 ++++ docs/tagodeploy/services/container/network.md | 205 ++---------------- .../tagodeploy/services/container/overview.md | 103 ++++----- docs/tagodeploy/services/container/runtime.md | 85 ++------ 6 files changed, 172 insertions(+), 484 deletions(-) create mode 100644 docs/tagodeploy/services/container/instances.md diff --git a/docs/tagodeploy/services/container/docker-image.md b/docs/tagodeploy/services/container/docker-image.md index 84907a8a..4fb9d8d8 100644 --- a/docs/tagodeploy/services/container/docker-image.md +++ b/docs/tagodeploy/services/container/docker-image.md @@ -1,6 +1,6 @@ --- title: "Docker Image Configuration" -description: "Configure Docker image settings and registry authentication for container deployments in TagoDeploy." +description: "The Docker Image and Registry Authentication sections of the Docker Settings page: pick an image and authenticate to private registries." keywords: [tagodeploy, iot, docker, container, registry] tags: ["tagodeploy", "container"] slug: /tagodeploy/project/container/docker-image @@ -8,152 +8,58 @@ slug: /tagodeploy/project/container/docker-image # Docker Image Configuration -Configure the Docker image settings and authentication credentials for your container deployment. This section allows you to specify which Docker image to deploy and how to authenticate with private registries. +The **Docker Image** and **Registry Authentication** sections sit at the top of +the container **Docker Settings** page. They decide which image the container +pulls and how it authenticates to a private registry. Edit the fields and use +**Save** to stage the change, which is applied through the project deploy flow. -## Docker Image Settings +## Docker Image -### Image Configuration +This section sets the image the container runs: -The image configuration determines which Docker container will be deployed in your project: +- **Image Name**: the name of the Docker image to use, including the registry + and repository path when it is not on Docker Hub (for example + `nginx`, `docker.io/library/postgres`, `ghcr.io/company/app`). +- **Image Tag**: the tag of the Docker image to use (for example `latest`, + `v1.2.0`, `main`). -- **Image**: The full Docker image name including registry and repository path (e.g., `docker.io/library/nginx`, `ghcr.io/company/app`) -- **Image Tag**: The specific version or tag of the image to deploy (e.g., `latest`, `v1.2.0`, `main`) +Pin a specific tag instead of `latest` for production so deploys stay +reproducible. -### Image Naming Examples +## Registry Authentication -**Public Images (Docker Hub):** +Use this section to provide credentials for private Docker registries. Public +images from Docker Hub do not need credentials. -- `nginx` (shorthand for `docker.io/library/nginx:latest`) -- `docker.io/library/postgres:13` -- `redis:alpine` +- **Registry Username**: the username for the Docker registry. +- **Registry Access Password**: the access password or token for the Docker + registry. The field has a reveal toggle and is treated as a secret, so it is + only sent when you edit it. -**Private Images:** +### Docker Hub -- `docker.io/mycompany/myapp:v1.0.0` -- `ghcr.io/organization/service:main` -- `myregistry.com/project/app:latest` +For a private Docker Hub repository, create a personal access token instead of +using your account password: -## Authentication +1. Sign in to [Docker Hub](https://hub.docker.com). +2. Open **Account Settings** then **Security**. +3. Click **New Access Token**, give it a description, and pick **Read** access + for pulling images. +4. Generate the token, then enter your Docker Hub username as the Registry + Username and the token as the Registry Access Password. -Authentication is required when deploying images from private Docker registries. TagoIO Deploy supports authentication with major registry providers. +### GitHub Container Registry -### When Authentication is Needed +For images on `ghcr.io`, create a GitHub personal access token: -- **Private repositories** on Docker Hub, GitHub Container Registry, or other registries -- **Organization-owned images** that require access credentials -- **Custom private registries** with authentication requirements +1. Open [GitHub token settings](https://github.com/settings/tokens). +2. Generate a classic token with `read:packages` (and `repo` if the image lives + in a private repository). +3. Enter your GitHub username as the Registry Username and the token as the + Registry Access Password. -Public images from Docker Hub do not require authentication credentials. +### Other registries -### Docker Hub Authentication - -Docker Hub is the default Docker registry and hosts millions of public container images. For private repositories, you'll need to provide authentication credentials. - -#### Setting Up Docker Hub Authentication - -1. **Get Your Docker Hub Credentials**: - - **Username**: Your Docker Hub username - - **Access Token**: Create a personal access token (recommended) or use your account password - -2. **Creating a Docker Hub Access Token**: - 1. Log in to [Docker Hub](https://hub.docker.com) - 2. Go to **Account Settings** → **Security** - 3. Click **New Access Token** - 4. Provide a description (e.g., "TagoIO Deploy") - 5. Select appropriate permissions (typically **Read** is sufficient for pulling images) - 6. Click **Generate** and copy the token - -3. **Configure Authentication**: - - **Username**: Enter your Docker Hub username - - **Registry Access Password**: Paste your access token (not your account password) - -#### Docker Hub Image Examples - -``` -# Public image (no authentication needed) -docker.io/library/nginx:latest - -# Private image (authentication required) -docker.io/myusername/private-app:v1.0.0 -``` - -### GitHub Container Registry Authentication - -GitHub Container Registry (ghcr.io) allows you to store Docker images alongside your GitHub repositories with fine-grained access controls. - -#### Setting Up GitHub Container Registry Authentication - -1. **Get Your GitHub Credentials**: - - **Username**: Your GitHub username - - **Personal Access Token**: A GitHub personal access token with appropriate permissions - -2. **Creating a GitHub Personal Access Token**: - 1. Go to [GitHub Settings](https://github.com/settings/tokens) - 2. Click **Generate new token** → **Generate new token (classic)** - 3. Provide a note (e.g., "TagoIO Deploy Container Access") - 4. Select expiration (choose based on your security requirements) - 5. Select scopes: - - `read:packages` (required for pulling container images) - - `repo` (if accessing private repository images) - 6. Click **Generate token** and copy it immediately - -3. **Configure Authentication**: - - **Username**: Enter your GitHub username - - **Registry Access Password**: Paste your personal access token - -### Other Private Registries - -TagoIO Deploy supports authentication with other private Docker registries including: - -- **AWS Elastic Container Registry (ECR)** -- **Google Container Registry (GCR)** -- **Azure Container Registry (ACR)** -- **Custom private registries** - -For these registries: - -- **Username**: Registry-specific username or access key -- **Registry Access Password**: Registry-specific password, token, or access key - -## Best Practices - -### Image Selection - -- **Use specific tags** instead of `latest` for production deployments to ensure consistency -- **Choose minimal base images** (like Alpine Linux) to reduce attack surface and deployment time -- **Verify image sources** and use trusted, well-maintained images - -### Authentication Security - -- **Use access tokens** instead of passwords when available -- **Grant minimal permissions** - typically read-only access is sufficient for image pulling -- **Rotate credentials regularly** and update them in your container configuration -- **Keep credentials secure** - never share or commit authentication credentials - -### Registry Performance - -- **Choose geographically close registries** when possible to reduce image pull times -- **Consider registry mirrors** or caching for frequently deployed images -- **Monitor registry rate limits** to avoid deployment interruptions - -## Troubleshooting - -### Common Issues - -**Authentication Failed:** - -- Verify username and access token are correct -- Check that the access token has appropriate permissions -- Ensure the registry URL in the image name is correct - -**Image Not Found:** - -- Confirm the image name and tag are spelled correctly -- Verify the image exists in the specified registry -- Check if the image is public or requires authentication - -**Pull Rate Limits:** - -- Docker Hub has rate limits for anonymous pulls -- Authenticate even for public images to get higher rate limits -- Consider using alternative registries or mirrors +The same two fields work for AWS ECR, Google GCR, Azure ACR, and other private +registries. Use the registry's username or access key as the Registry Username +and its password, token, or secret key as the Registry Access Password. diff --git a/docs/tagodeploy/services/container/environment-variables.md b/docs/tagodeploy/services/container/environment-variables.md index 47711ebe..1c14c2ef 100644 --- a/docs/tagodeploy/services/container/environment-variables.md +++ b/docs/tagodeploy/services/container/environment-variables.md @@ -1,6 +1,6 @@ --- title: "Container Environment Variables" -description: "Configure environment variables for containers, including security and configuration best practices." +description: "The Environment Variables section of the Docker Settings page: key/value pairs passed to your container at runtime." keywords: [tagodeploy, iot, container, environment variables, configuration] tags: ["tagodeploy", "container"] slug: /tagodeploy/project/container/environment-variables @@ -8,36 +8,23 @@ slug: /tagodeploy/project/container/environment-variables # Environment Variables -Configure environment variables that will be passed to your container at -runtime. Environment variables are key-value pairs that provide configuration -settings, API keys, database connections, and other runtime parameters to your -containerized applications. +The **Environment Variables** section on the container **Docker Settings** page +holds the key/value pairs passed to your container at runtime. Use them for +configuration the container reads from its environment, such as connection +strings, feature flags, and API keys. -## What are Environment Variables? +## Managing variables -Environment variables are dynamic values that can affect the way running -processes behave in your container. They provide a way to: +The section starts empty, with "No environment variables configured". Use +**Add variable** to add a key/value row, and repeat for each variable. Edit the +values and use **Save** to stage the change, which is applied through the +project deploy flow. -- **Configure Applications**: Pass configuration settings without modifying code -- **Store Credentials**: Provide API keys, database passwords, and other - sensitive information -- **Set Runtime Parameters**: Control application behavior based on deployment - environment -- **Enable Feature Flags**: Toggle application features on or off +## Best practices -## Best Practices - -### Security Considerations - -- **Use Descriptive Names**: Make variable purposes clear through naming -- **Avoid Hardcoding**: Use environment variables instead of hardcoded values in - your application - -### Configuration Management - -- **Group Related Variables**: Use prefixes to organize related configuration - (e.g., `DB_*`, `SMTP_*`) -- **Provide Defaults**: Have sensible defaults in your application when - variables are optional -- **Validate Values**: Implement validation in your application for critical - environment variables +- **Use clear names**: make each variable's purpose obvious, and group related + ones with a prefix (for example `DB_`, `SMTP_`). +- **Keep secrets out of the image**: pass credentials as environment variables + instead of baking them into the image. +- **Provide defaults in your app**: handle missing optional variables and + validate the critical ones at startup. diff --git a/docs/tagodeploy/services/container/instances.md b/docs/tagodeploy/services/container/instances.md new file mode 100644 index 00000000..88beed24 --- /dev/null +++ b/docs/tagodeploy/services/container/instances.md @@ -0,0 +1,40 @@ +--- +title: "Container Instances" +description: "Set the machine size and autoscaling rules for a container application, and watch its CPU and memory usage." +keywords: [tagodeploy, iot, container, instances, autoscaling] +tags: ["tagodeploy", "container"] +slug: /tagodeploy/project/container/instances +--- + +# Container Instances + +The Instances page controls how a container application scales. You pick the +machine size, set the instance count range and the autoscaling thresholds, and +review CPU and memory charts for the running service. + +## Instance settings + +The settings form holds the scaling configuration: + +- **Machine** is the vCPU and RAM tier each instance runs on, which defaults to + 1 vCPU / 2GB RAM. The list of tiers is limited by your project plan, so larger + sizes appear only when your plan allows them. +- **Minimum Instances** and **Maximum Instances** set the range the service can + scale between, defaulting to 1 and 2. The minimum cannot be higher than the + maximum, and the highest selectable count is capped by your plan. +- **Scale on CPU Utilization** is the CPU percentage that triggers autoscaling, + which defaults to 60. +- **Cooldown for Scaling Up** and **Cooldown for Scaling Down** are the wait + periods in seconds before another scaling step, defaulting to 200 and 300. + +Edit the values and use **Save** to stage the change. Only the fields you +changed are sent. Save is disabled until you make a change, and staged changes +are applied through the project deploy flow. + +## Monitoring + +The Monitoring section charts CPU Utilization and Memory Utilization for the +service as percentages over time. Use the time range control to change the +window across 1h, 6h, 12h, 1d, 3d, 7d, and 30d. Read these charts alongside the +Scale on CPU Utilization threshold to judge whether the instance range and +machine size fit the load. diff --git a/docs/tagodeploy/services/container/network.md b/docs/tagodeploy/services/container/network.md index a887c969..89b9a974 100644 --- a/docs/tagodeploy/services/container/network.md +++ b/docs/tagodeploy/services/container/network.md @@ -1,203 +1,28 @@ --- title: "Container Network Configuration" -description: "Configure protocol, port mappings, TLS, and load balancer integration for container networking." -keywords: [tagodeploy, iot, container, network, tls] +description: "The Network section of the Docker Settings page: network protocol and port mappings for the load balancer." +keywords: [tagodeploy, iot, container, network, port mappings] tags: ["tagodeploy", "container"] slug: /tagodeploy/project/container/network --- # Network Configuration -Configure network settings for your Docker container, including load balancer -ports, communication protocols, and TLS encryption. Network configuration -determines how external traffic reaches your container and how your application -communicates with other services. +The **Network** section on the container **Docker Settings** page sets the +network protocol and port mappings for the load balancer that fronts your +container. Edit the fields and use **Save** to stage the change, which is +applied through the project deploy flow. -## Network Settings Overview +## Network protocol -The network configuration provides control over: +**Network protocol** is a dropdown that defaults to **TCP**. It sets the +protocol the load balancer uses to reach the container. -- **Protocol Selection**: Choose between TCP and UDP protocols -- **Port Mapping**: Map container ports to external host ports -- **TLS Encryption**: Enable secure connections with TLS/SSL termination -- **Load Balancer Integration**: Automatic integration with project load - balancing +## Port mappings -## Network Protocol +**Port mappings** route external traffic to the port your container listens on. +The list starts empty, with "No port mappings configured". Use **Add port** to +add a mapping row, and repeat for each port your container exposes. -### Protocol Selection - -Choose the appropriate protocol for your application's communication needs: - -- **TCP (Transmission Control Protocol)**: Reliable, connection-oriented - protocol ideal for web applications, APIs, and services requiring guaranteed - delivery -- **UDP (User Datagram Protocol)**: Faster, connectionless protocol suitable for - real-time applications, gaming, and streaming services - -**Common Protocol Uses:** - -- **TCP**: Web servers (HTTP/HTTPS), APIs (REST/GraphQL), databases, file - transfers -- **UDP**: DNS services, video streaming, online gaming, IoT sensor data - -## Port Mappings - -Port mappings define how external traffic reaches your container by connecting -container ports to host ports accessible from outside your project. - -### Understanding Port Mapping - -- **Container Port**: The port your application listens on inside the container -- **Host Port**: The external port that will be accessible from outside the - project -- **TLS**: Whether to enable TLS/SSL encryption for this port mapping - -### Port Mapping Examples - -**Web Application (HTTP):** - -- Container Port: `3000` (your app's internal port) -- Host Port: `80` (standard HTTP port) -- TLS: `Disabled` - -**Web Application (HTTPS):** - -- Container Port: `3000` (your app's internal port) -- Host Port: `443` (standard HTTPS port) -- TLS: `Enabled` - -**API Service:** - -- Container Port: `8080` (API server port) -- Host Port: `8080` (external API access) -- TLS: `Enabled` (for secure API calls) - -## TLS Configuration - -### What is TLS? - -TLS (Transport Layer Security) provides encryption for data transmitted between -clients and your container. It ensures: - -- **Data Encryption**: All communication is encrypted in transit -- **Identity Verification**: Clients can verify they're connecting to the - correct service -- **Data Integrity**: Protection against data tampering during transmission - -### When to Enable TLS - -**Enable TLS for:** - -- **Public-facing web applications** (HTTPS) -- **API endpoints** handling sensitive data -- **Services processing user authentication** -- **Any service requiring encrypted communication** - -**TLS may not be needed for:** - -- **Internal services** within the project network -- **Development and testing environments** -- **Services behind additional TLS termination** - -### TLS Best Practices - -- **Always use TLS** for production web applications -- **Enable TLS for APIs** that handle sensitive data -- **Consider performance impact** - TLS adds small overhead -- **Use standard ports** (443 for HTTPS, 8443 for HTTPS APIs) - -## Load Balancer Integration - -### Automatic Load Balancing - -TagoIO Deploy automatically integrates your container with the project's load -balancer: - -- **Traffic Distribution**: Incoming requests are distributed across container - instances -- **Health Checks**: Automatic monitoring of container health and availability -- **SSL Termination**: TLS encryption/decryption handled at the load balancer - level -- **Scaling Support**: Load balancer adapts to container scaling events - -### Load Balancer Features - -- **High Availability**: Automatic failover if container instances become - unavailable -- **Geographic Distribution**: Traffic routing based on client location -- **Protocol Support**: Both TCP and UDP load balancing capabilities -- **Performance Optimization**: Connection pooling and request optimization - -## Common Network Configurations - -### Single Web Application - -**Simple web app setup:** - -``` -Protocol: TCP -Port Mapping: -- Container: 3000 → Host: 80 (TLS: Disabled) -- Container: 3000 → Host: 443 (TLS: Enabled) -``` - -### Microservice with API - -**Service with both web interface and API:** - -``` -Protocol: TCP -Port Mappings: -- Container: 3000 → Host: 80 (TLS: Disabled, Web UI) -- Container: 3000 → Host: 443 (TLS: Enabled, Web UI) -- Container: 8080 → Host: 8080 (TLS: Enabled, API) -``` - -## Security Considerations - -### Network Security - -- **Minimize Exposed Ports**: Only expose ports that need external access -- **Use TLS**: Enable encryption for all public-facing services -- **Port Ranges**: Avoid using well-known system ports (1-1023) unless necessary -- **Protocol Selection**: Choose the most appropriate protocol for your use case - -### Access Control - -- **Internal Services**: Consider if services need external access or can remain - internal -- **Authentication**: Implement application-level authentication for sensitive - services -- **Rate Limiting**: Configure application-level rate limiting for public APIs -- **Monitoring**: Monitor network traffic for unusual patterns - -## Troubleshooting - -### Common Network Issues - -**Service Not Accessible:** - -- Verify port mappings are configured correctly -- Check that your application is listening on the container port -- Ensure the container is running and healthy -- Confirm firewall rules aren't blocking traffic - -**TLS Connection Issues:** - -- Verify TLS is enabled for the correct port mapping -- Check that your application supports the configured protocol -- Ensure certificates are properly configured (handled automatically by TagoIO) - -**Protocol Mismatch:** - -- Confirm your application uses the same protocol (TCP/UDP) as configured -- Verify port numbers match between container and mapping configuration -- Check application logs for connection errors - -**Performance Issues:** - -- Consider if TLS overhead is affecting performance -- Review port mapping efficiency -- Monitor load balancer metrics for bottlenecks -- Check if UDP might be more appropriate for real-time applications +Only expose the ports that need external access. Confirm your application is +listening on the port you map, otherwise the load balancer has nothing to reach. diff --git a/docs/tagodeploy/services/container/overview.md b/docs/tagodeploy/services/container/overview.md index e09087d1..6a30f941 100644 --- a/docs/tagodeploy/services/container/overview.md +++ b/docs/tagodeploy/services/container/overview.md @@ -1,6 +1,6 @@ --- title: "Custom Docker" -description: "Deploy and manage custom Docker containers in your TagoDeploy project, with image, network, runtime, and logging options." +description: "The container service overview: service name, URL, and where the Instances and Docker Settings pages live." keywords: [tagodeploy, iot, docker, container, deployment] tags: ["tagodeploy", "container"] slug: /tagodeploy/project/container/overview @@ -8,72 +8,57 @@ slug: /tagodeploy/project/container/overview # Custom Docker -The **Custom Docker** addon allows you to deploy and manage custom Docker -containers within your TagoIO Deploy projects. This powerful feature enables you -to run any containerized application, microservice, or custom workload alongside -your other project resources. - -## What is Container Deployment? - -Container deployment provides a flexible way to run Docker containers in your -project infrastructure. This addon supports: - -- **Custom Docker Images**: Deploy any Docker image from public or private - registries -- **Private Registry Support**: Authenticate with Docker Hub, GitHub Container - Registry, and other private registries -- **Environment Configuration**: Set environment variables for your container - applications -- **Network Configuration**: Configure port mappings and load balancer settings - with TLS support -- **Runtime Customization**: Override default working directories and startup - commands -- **Real-time Monitoring**: View container logs and monitor application - performance - -> [!WARNING] -> -> High log volume can significantly increase your project costs. Monitor your -> application's logging output and configure appropriate log levels to control -> expenses. +The **Custom Docker** addon runs your own container image alongside the rest of +your project. You point it at an image, set how it scales, and configure how it +is built and run. The service is reached on its own subdomain under your +project. + +The container service has three pages in its sidebar: + +- **Overview**: service name, URL, and product details (this page). +- **Instances**: machine size and autoscaling range. See + [Container Instances](/tagodeploy/project/container/instances). +- **Settings**: image, registry credentials, environment variables, network, + and runtime, grouped on one **Docker Settings** page. See the sections below. -## Container Management Features +## Overview page -### Image Management +The Overview page shows the service details and a few controls. -- **Flexible Image Sources**: Support for Docker Hub, GitHub Container Registry, - and custom registries -- **Version Control**: Pin specific image tags or use rolling tags like `latest` -- **Private Registry Access**: Secure authentication for private repositories +### Service Information -### Network Configuration +- **Display Name**: the name shown for this service in your project. +- **Addon**: the product type, shown as "Custom Docker". Read-only. +- **Service URL**: the address the container is served on, + `https://{serviceId}.{projectId}.tagoio.net`. Read-only, with a copy button. -- **Port Mapping**: Map container ports to host ports for external access -- **Protocol Support**: Configure TCP or UDP protocols based on your application - needs -- **TLS Termination**: Enable TLS/SSL encryption for secure connections -- **Load Balancer Integration**: Automatic integration with project load - balancing +Edit the Display Name and use **Save** to stage the change. Save is disabled +until you make a change. -### Runtime Flexibility +### Danger Zone -- **Custom Commands**: Override default container startup commands -- **Working Directory**: Set custom working directories for your applications -- **Environment Variables**: Pass configuration and secrets to your containers -- **Resource Management**: Containers run within your project's resource - allocation +A collapsible section with irreversible actions for this service. -## Getting Started +## Docker Settings -To deploy a container in your project: +The **Docker Settings** page (the Settings sidebar entry) is where the container +is built, configured, and run. It is one page with collapsible sections, in this +order: -1. **Add Container Addon**: Navigate to your project and add the Container addon -2. **Configure Image**: Set up your Docker image and registry authentication if - needed -3. **Set Environment**: Configure any required environment variables -4. **Configure Network**: Set up port mappings for external access -5. **Deploy**: Save your configuration to deploy the container +- **Docker Image** and **Registry Authentication**: the image to pull and + credentials for private registries. See + [Docker Image Configuration](/tagodeploy/project/container/docker-image). +- **Environment Variables**: key/value pairs passed to the container. See + [Environment Variables](/tagodeploy/project/container/environment-variables). +- **Network**: protocol and port mappings for the load balancer. See + [Network Configuration](/tagodeploy/project/container/network). +- **Runtime**: working directory and command overrides. See + [Runtime Configuration](/tagodeploy/project/container/runtime). -The Container addon integrates seamlessly with your project's existing -infrastructure, providing a powerful platform for running custom applications -alongside your other TagoIO resources. +Changes on the Docker Settings page are staged with **Save** and applied through +the project deploy flow. + +> [!NOTE] +> +> The container service has no Logs page of its own. Runtime output appears on +> the project's **Logs** page under Management. diff --git a/docs/tagodeploy/services/container/runtime.md b/docs/tagodeploy/services/container/runtime.md index 0f66af56..ec0be2dd 100644 --- a/docs/tagodeploy/services/container/runtime.md +++ b/docs/tagodeploy/services/container/runtime.md @@ -1,6 +1,6 @@ --- title: "Container Runtime" -description: "Configure container working directory, startup command, and image overrides for custom runtime behavior." +description: "The Runtime section of the Docker Settings page: override the container's work directory and command." keywords: [tagodeploy, iot, container, runtime, docker] tags: ["tagodeploy", "container"] slug: /tagodeploy/project/container/runtime @@ -8,77 +8,22 @@ slug: /tagodeploy/project/container/runtime # Runtime Configuration -Configure runtime settings to customize how your Docker container executes, -including the working directory and startup command. These settings allow you to -override the default behavior defined in your Docker image. +The **Runtime** section on the container **Docker Settings** page overrides the +default work directory and command from the Docker image. Leave a field empty to +keep the image default. Edit the fields and use **Save** to stage the change, +which is applied through the project deploy flow. -## Runtime Settings Overview +## Work Directory -Runtime configuration provides control over: +**Work Directory** is the directory the container runs in. Leave it empty to use +the working directory defined in the image, or set an absolute path (starting +with `/`) to override it. Common values are `/app` and `/usr/src/app`. -- **Working Directory**: The directory where your application runs inside the - container -- **Startup Command**: The command executed when the container starts -- **Image Overrides**: Customization that supersedes Docker image defaults +## Command -## Working Directory +**Command** is what runs when the container starts. Leave it empty to use the +`CMD` or `ENTRYPOINT` from the image, or set your own command with any arguments, +such as `node server.js`, `python app.py`, or `java -jar app.jar`. -### What is Working Directory? - -The working directory is the file system location where your application runs -inside the container. It serves as the default location for relative file paths -and command execution. - -**Default Behavior:** - -- If left empty, uses the working directory defined in the Docker image -- Most images define a sensible default (often `/app`, `/usr/src/app`, or - `/opt/app`) - -**Custom Working Directory:** - -- Override the image default with a specific path -- Must be an absolute path (starting with `/`) - -**Examples:** - -``` -/app # Common for Node.js, Python apps -/usr/src/app # Alternative for web applications -/opt/myapp # Custom application directory -``` - -## Startup Command - -### What is Startup Command? - -The startup command defines what executes when your container starts. This can -be application startup, script execution, or service commands. - -**Default Behavior:** - -- If left empty, uses the `CMD` or `ENTRYPOINT` defined in the Docker image - -**Custom Commands:** - -- Override the image default with your specific command -- Can include command-line arguments and flags - -**Examples:** - -``` -node server.js # Node.js application -python app.py # Python application -npm start # Using npm scripts -java -jar app.jar # Java application -``` - -## Best Practices - -- **Use Standard Paths**: Follow common conventions for your application type -- **Foreground Execution**: Ensure your command runs in the foreground (doesn't - exit immediately) -- **Absolute Paths**: Always use absolute paths for working directories starting - with `/` -- **Test Locally**: Verify your configuration works with `docker run` before - deploying +Make sure the command runs in the foreground so the container does not exit +right after it starts. From 032552886baa77718bc7d74ff506f0b0bf490a2e Mon Sep 17 00:00:00 2001 From: Ricardo Stoklosa Date: Fri, 29 May 2026 16:01:21 -0300 Subject: [PATCH 13/15] docs(tagodeploy): add webservice overview, settings, and instances --- .../services/webservice/_category_.json | 5 ++ .../services/webservice/instances.md | 45 +++++++++++++++ .../services/webservice/overview.md | 55 +++++++++++++++++++ .../services/webservice/settings.md | 40 ++++++++++++++ 4 files changed, 145 insertions(+) create mode 100644 docs/tagodeploy/services/webservice/_category_.json create mode 100644 docs/tagodeploy/services/webservice/instances.md create mode 100644 docs/tagodeploy/services/webservice/overview.md create mode 100644 docs/tagodeploy/services/webservice/settings.md diff --git a/docs/tagodeploy/services/webservice/_category_.json b/docs/tagodeploy/services/webservice/_category_.json new file mode 100644 index 00000000..769c1a68 --- /dev/null +++ b/docs/tagodeploy/services/webservice/_category_.json @@ -0,0 +1,5 @@ +{ + "label": "Web Service", + "position": 3, + "collapsed": true +} diff --git a/docs/tagodeploy/services/webservice/instances.md b/docs/tagodeploy/services/webservice/instances.md new file mode 100644 index 00000000..a8d6d5f3 --- /dev/null +++ b/docs/tagodeploy/services/webservice/instances.md @@ -0,0 +1,45 @@ +--- +title: "Web Service Instances" +description: "Set the machine size and autoscaling rules for a web service connector, and watch its CPU and memory usage." +keywords: [tagodeploy, webservice, middleware, instances, autoscaling, machine] +tags: ["tagodeploy", "webservice"] +slug: /tagodeploy/project/webservice/instances +--- + +A web service is a middleware connector that bridges an external IoT network or +protocol to TagoIO over webhooks. The Instances page controls how that connector +scales, so it can absorb ingest spikes when the external network sends a burst of +uplinks. You pick the machine size, set the instance count range and the +autoscaling thresholds, and review CPU and memory charts for the running +connector. + +## Instance settings + +The settings form holds the machine size, scaling range, and autoscaling +thresholds for the connector. + +- **Machine** is the vCPU and RAM tier each instance runs on, for example + "1 vCPU / 2GB RAM". The list of tiers is limited by your project plan, so + larger sizes appear only when your plan allows them. +- **Minimum Instances** and **Maximum Instances** set the range the connector + can scale between. The minimum cannot be higher than the maximum, and the + maximum cannot be lower than the minimum. The highest selectable count is + capped by your plan. +- **Scale on CPU Utilization** is the CPU percentage that triggers autoscaling. + A burst of uplinks raises CPU, and crossing this threshold adds instances to + keep up. +- **Cooldown for Scaling Up** and **Cooldown for Scaling Down** are the wait + periods in seconds before another scaling step. + +Edit the values and use Save to stage the change. Only the fields you changed +are sent. Save is disabled when you lack edit permission or while a project +deploy is in progress, and staged changes are applied through the project +deploy flow. + +## Monitoring + +The Monitoring section charts CPU Utilization and Memory Utilization for the +connector as percentages over time. Use the time range control to change the +window, with options from 1h to 30d. Read these charts alongside the +Scale on CPU Utilization threshold to judge whether the instance range and +machine size fit the connector's uplink load. diff --git a/docs/tagodeploy/services/webservice/overview.md b/docs/tagodeploy/services/webservice/overview.md new file mode 100644 index 00000000..f5ec1d58 --- /dev/null +++ b/docs/tagodeploy/services/webservice/overview.md @@ -0,0 +1,55 @@ +--- +title: "Web Service Overview" +description: "Review a web service connector's core details and set a display name to recognize it across the project." +keywords: [tagodeploy, webservice, middleware, connector, overview] +tags: ["tagodeploy", "webservice"] +slug: /tagodeploy/project/webservice/overview +--- + +A web service is a middleware connector that bridges an external IoT +network or protocol to TagoIO over webhooks. The Overview page shows +the connector's core details and lets you give it a display name you +can recognize across the project. + +## Service Information + +This section holds the identity of the connector. It is open by +default and contains three fields. + +- **Display Name** is the only editable field. Use it to label the + connector so you can tell it apart from others in the same project, + for example "TTN US915" or "Sigfox EU". The name is required and can + be up to 100 characters. The Save button stays disabled until you + change the value. +- **Addon** is read-only and shows the connector type this service was + created from. It reads "Middleware {Type}", for example "Middleware + Chirpstack". Connector types include AWS IoT, Chirpstack, Everynet, + Generic HTTPS, Loriot, MachineQ, Myriota, Senet, Sigfox, Tektelic, + and TTN. +- **Service URL** is read-only and is the webhook endpoint your network + posts uplinks to. It follows the pattern + `https://..tagoio.net`. A copy button next to + the field puts the URL on your clipboard. + +The display name is cosmetic. It does not change the connector type, +the Service URL, or how messages flow between the device and TagoIO. + +## Related pages + +The Overview page covers identity only. Two sibling pages handle the +rest of the connector. + +- **Settings** holds the connector configuration: the credentials and + endpoints the middleware uses to talk to the external network. This + is where the network token and TagoIO API URL are set. +- **Instances** controls scaling, so you can adjust how much capacity + the connector runs with. + +## Danger Zone + +This section is collapsed by default and holds one irreversible action. +**Remove service** deletes the connector from the project. Removing a +service cannot be undone, so a confirmation dialog appears before it +runs. After removal you are returned to the project management +overview. The button is only shown if you have permission to disable +addons. diff --git a/docs/tagodeploy/services/webservice/settings.md b/docs/tagodeploy/services/webservice/settings.md new file mode 100644 index 00000000..defc2106 --- /dev/null +++ b/docs/tagodeploy/services/webservice/settings.md @@ -0,0 +1,40 @@ +--- +title: "Web Service Settings" +description: "Set the network token and API endpoint the middleware uses to bridge your IoT network to TagoIO." +keywords: [tagodeploy, webservice, middleware, settings, network token, api url] +tags: ["tagodeploy", "webservice"] +slug: /tagodeploy/project/webservice/settings +--- + +A web service is a middleware connector that relays uplink messages from an +external network or protocol to TagoIO over webhooks, and often relays downlink +messages back to devices. This page holds the connector's configuration: the +credentials and endpoints it uses to talk to both sides. + +## Configuration + +The Configuration section holds the credentials and endpoints used by this +middleware. + +- **Network Token** is selected from a network combobox. Pick the network you + want the connector to use, and use the "Refresh networks" button to reload the + list. A "Use custom token (advanced)" toggle reveals a manual token text field + if you need to supply a token by hand instead of picking from the list. +- **TagoIO Api URL** is the API endpoint the connector posts to. It defaults to + `https://api..tagoio.net`. + +## Saving changes + +Save is available once you edit a field. The button stays disabled while the +form is unchanged, and the whole form locks while a deployment for the project +is in flight, with an alert at the top of the page. Saving does not apply the +change to the running connector right away. It stages the change through the +project deploy flow, where it is applied together with the project's other +pending changes on the next deploy. + +## Related pages + +The Overview page shows the service identity, such as its display name and +service URL, and the action to remove it from the project. The Instances page +controls how the connector scales. Use this Settings page for the connector's +network token and API endpoint. From 617e7f5bf358d4f1ac539bf222ac11eb2aa5f744 Mon Sep 17 00:00:00 2001 From: Ricardo Stoklosa Date: Fri, 29 May 2026 16:01:22 -0300 Subject: [PATCH 14/15] docs(tagodeploy): refresh getting-started and services overview docs --- docs/tagodeploy/getting-started/index.md | 30 ++++++---- .../tagodeploy/getting-started/new-project.md | 47 +++++++++++----- docs/tagodeploy/services/index.md | 47 +++++++++------- docs/tagodeploy/services/middlewares/index.md | 55 +++++++++++-------- .../middlewares/managing-middleware.md | 25 +++++---- 5 files changed, 126 insertions(+), 78 deletions(-) diff --git a/docs/tagodeploy/getting-started/index.md b/docs/tagodeploy/getting-started/index.md index 501f9eaf..4b719d26 100644 --- a/docs/tagodeploy/getting-started/index.md +++ b/docs/tagodeploy/getting-started/index.md @@ -1,15 +1,19 @@ --- title: "TagoDeploy" -description: "A brief overview of Tago Deploy, a dedicated single-tenant IoT platform built on the TagoIO architecture, with an architecture overview and pointers to core capabilities, add-on services, and implementation considerations." +description: "A brief overview of TagoDeploy, a dedicated single-tenant IoT platform built on the TagoIO architecture, with an architecture overview and pointers to core capabilities, add-on services, and implementation considerations." keywords: [tagodeploy, iot, single-tenant, enterprise, infrastructure] +tags: ["tagodeploy"] slug: /tagodeploy --- -Tago Deploy provides a dedicated, single‑tenant IoT platform environment built +TagoDeploy provides a dedicated, single-tenant IoT platform environment built on the complete TagoIO architecture. This enterprise solution delivers isolated infrastructure with full resource control, enabling organizations to operate their IoT platform without shared infrastructure constraints. +You switch between projects from the project switcher in the top navigation, and +you add new projects and services from the App Catalog at `/apps`. + ![Image 1](/docs_imagem/tagoio/external-45f285f7.png) ## Architecture Overview @@ -26,7 +30,7 @@ position their infrastructure based on latency requirements, compliance needs, or data residency regulations. The deployment includes custom API endpoints and administrative interfaces with -configurable URLs, enabling complete white‑label implementation. All TagoIO +configurable URLs, enabling complete white-label implementation. All TagoIO platform capabilities are included, with the addition of TagoRUN integration for custom application deployment and user management. @@ -38,7 +42,7 @@ Each Tago Deploy instance operates on isolated infrastructure with dedicated resources. Organizations receive their own compute instances, storage systems, and network configurations without sharing resources with other tenants. This architecture ensures predictable performance and eliminates the resource -contention common in multi‑tenant environments. +contention common in multi-tenant environments. ![Image 2](/docs_imagem/tagoio/external-2780a3eb.png) @@ -87,15 +91,19 @@ platform touchpoints. Platform updates and feature deployments are managed through controlled versioning. Organizations maintain authority over when updates are applied, -allowing for testing and validation in non‑production environments before +allowing for testing and validation in non-production environments before rolling changes to production systems. This approach ensures operational stability while providing access to new platform capabilities. ## Add-on Services +Add-on services install from the App Catalog at `/apps`, the same place you +create a project. The catalog groups items by category: Platform, Middleware, +MQTT, and Others. + ### MQTT Broker -A dedicated MQTT broker can be deployed within the Tago Deploy environment, +A dedicated MQTT broker can be deployed within the TagoDeploy environment, providing complete control over device communication protocols. The broker supports custom authentication mechanisms, message routing rules, and protocol configurations tailored to specific IoT deployment requirements. @@ -104,11 +112,11 @@ configurations tailored to specific IoT deployment requirements. ### Middleware Services -Custom middleware components can be deployed to extend platform functionality or -integrate with existing enterprise systems. These services operate within the -isolated environment while maintaining full access to platform APIs and data -streams. Services such as LNS (LoRaWAN Network Service) for Netmore, TTI, and -others, and MQTT are supported. +Middleware components can be deployed to connect external networks and systems to +your project. They operate within the isolated environment while maintaining full +access to platform APIs and data streams. Available middleware types include AWS +IoT, Chirpstack, Everynet, Generic HTTPS, Loriot, MachineQ, Myriota, Senet, +Sigfox, Tektelic, and TTN. ![Image 8](/docs_imagem/tagoio/external-4045d1cd.png) diff --git a/docs/tagodeploy/getting-started/new-project.md b/docs/tagodeploy/getting-started/new-project.md index 66ae36d8..4f62fb80 100644 --- a/docs/tagodeploy/getting-started/new-project.md +++ b/docs/tagodeploy/getting-started/new-project.md @@ -6,29 +6,46 @@ tags: ["tagodeploy"] slug: /tagodeploy/new-project --- -# Home +# Creating a New Project -Welcome to your Home page. Here, you can quickly access your projects, stay -updated with recent messages, and find support resources. +A project in TagoDeploy is created by installing the **TagoIO Platform** app from +the App Catalog. The catalog provisions the project's infrastructure and gives you +a dedicated, single-tenant TagoIO environment. -## Create your First Project +## Open the App Catalog -Create your first project by clicking on the "Deploy your first project" link in -the home page. If you need a specific Middleware or a MQTT Broker to receive -data from your devices, you can enable them in the services page once you've -created a project. +There are two ways to start a new project: -## What You’ll Find on the Home Page +1. Open the project switcher in the top navigation and click **New project** at the + bottom of the dropdown. +2. Open **Apps** in the top navigation to reach the App Catalog at `/apps` and + select the **TagoIO Platform** card. -The Home page is organized into three sections: +Both routes open the same install flow. -1. **Project List** View all your current projects at a glance. +## Install the TagoIO Platform -2. **Recent Messages** Stay informed with a list of the 5 most recent emails - containing announcements that have been sent to your email. +Selecting the TagoIO Platform opens a detail dialog with its category, dates, and +an overview. Click **Next** to open the install dialog. -3. **Support Card** Need help? Easily access support resources and connect with - the TagoIO Community. +In the install dialog, set the following: + +- **Installation:** For the TagoIO Platform this is fixed to **New Project**. The + "In a project" option is reserved for services and is shown as coming soon here. +- **Region:** The AWS region the project runs in. Choose the one closest to your + devices or required by your data residency rules. +- **Version:** Defaults to the latest platform version. Pick an older version only + when you need compatibility with a specific stack. +- **Name:** The display name for your project, under **Settings**. + +Click **Next** to continue to review, then confirm to install. The project is +provisioned and appears in the project switcher once ready. + +## Add Services Later + +If you need a middleware or an MQTT broker to receive data from your devices, you +install them from the same App Catalog after the project exists. See +[Services](/docs/tagodeploy/services/index.md) for the available service types. ## Help & Support diff --git a/docs/tagodeploy/services/index.md b/docs/tagodeploy/services/index.md index 71c82bee..0f8169fb 100644 --- a/docs/tagodeploy/services/index.md +++ b/docs/tagodeploy/services/index.md @@ -8,17 +8,17 @@ slug: /tagodeploy/services/overview # Services -The **Services** page enables you to configure and assign additional features to -your projects. Integrating services allows you to extend and tailor your -project's functionality to meet specific requirements. +Services add capabilities to your projects beyond the base TagoIO Platform. You +add them from the **App Catalog** at `/apps`, the same place you create a project. ## Overview of Services -Services are modular components that add advanced capabilities to your projects. -Currently, the following service types are available: +Services are modular components that you install into a project. The catalog +groups items by category: Platform, Middleware, MQTT, and Others. The service +types available today are: -- **Middleware**: Connect your project with external platforms—such as LoRaWAN - LNS—to facilitate seamless data integration and exchange. +- **Middleware**: Connect your project with external networks, such as LoRaWAN + LNS providers, to move data between TagoIO and those systems. - **MQTT Broker**: Deploy a fully integrated MQTT broker within your project, enabling device connectivity and communication using the MQTT protocol. @@ -26,22 +26,31 @@ Currently, the following service types are available: ### Middleware -Middleware services function as intermediaries between your project and -third-party systems. They are typically used to integrate with platforms like -LoRaWAN LNS, supporting bi-directional data flow between your project and -external environments. +Middleware services act as intermediaries between your project and external +networks, supporting bi-directional data flow. The available middleware types +are AWS IoT, Chirpstack, Everynet, Generic HTTPS, Loriot, MachineQ, Myriota, +Senet, Sigfox, Tektelic, and TTN. ### MQTT Broker The MQTT Broker service provisions an MQTT broker instance within your project. -This service allows you to connect IoT devices and manage data transmission -using the MQTT protocol, supporting both data ingestion and distribution. +It lets you connect IoT devices and manage data transmission using the MQTT +protocol, supporting both data ingestion and distribution. -## Using Services +## Installing a Service -To utilize services within your project, follow these steps: +Open **Apps** in the top navigation to reach the App Catalog. Use the search box +or the category filters on the left to find a service, then click its card to +open the detail dialog and review the overview and features. Click **Next** to +open the install dialog. -Begin by browsing the list of available services on the Services page. Once you -identify a service that aligns with your project needs, select it to review its -features and configuration options. After selection, assign the service to your -desired project to activate its functionality. +The install dialog asks where the service should run: + +- **In a project**: Add the service to an existing project. You pick the target + **Project**, then the **Region** and **Version**. +- **New Project**: Provision the service alongside a new project. You pick the + **Region** and **Version** only. + +Under **Settings** you set the service **Name** and any required credentials. +Confirm to install. The service provisions networking, compute, and a default +autoscaling policy, then appears as a resource tab in the project. diff --git a/docs/tagodeploy/services/middlewares/index.md b/docs/tagodeploy/services/middlewares/index.md index d5e5556d..af34bab7 100644 --- a/docs/tagodeploy/services/middlewares/index.md +++ b/docs/tagodeploy/services/middlewares/index.md @@ -1,21 +1,23 @@ --- title: "Network Middlewares" -description: "Overview of Network Middlewares in TagoDeploy, including LoRaWAN LNS such as Tektelic, TTI, and others, and how to assign them to projects." +description: "Overview of Network Middlewares in TagoDeploy, including LoRaWAN LNS such as Chirpstack, Loriot, and TTN, and how to install them into projects." keywords: [tagodeploy, iot, middleware, lorawan, integration] tags: ["tagodeploy"] slug: /tagodeploy/services/middlewares --- Middleware services extend your TagoDeploy project with managed endpoints that -connect external networks and systems to TagoIO. You install them from Services -at the top of the page. +connect external networks and systems to TagoIO. You install them from the App +Catalog at `/apps`. Inside a project, a middleware's add-on label reads +"Middleware {Type}", for example "Middleware Chirpstack". > The catalog evolves over time; this guide focuses on how to deploy and operate -> any middleware. +> any middleware. Available types today are AWS IoT, Chirpstack, Everynet, Generic +> HTTPS, Loriot, MachineQ, Myriota, Senet, Sigfox, Tektelic, and TTN. An active middleware instance runs inside your single-tenant environment and -uses your project’s resources. You can scale instances, attach custom domains, -and point external networks to the middleware’s endpoint. +uses your project's resources. You can scale instances, attach custom domains, +and point external networks to the middleware's endpoint. ## What is a Middleware? @@ -26,23 +28,31 @@ with its own configuration, token, and scaling policy. ## Installing a Middleware -You install a middleware from Services. +You install a middleware from the App Catalog. Open **Apps** in the top +navigation, find the middleware type, and click its card to open the detail +dialog. Click **Next** to open the install dialog. -During installation you’ll see these fields: +The install dialog first asks where the middleware should run: -- **Name:** Display name for the service instance. -- **Project and Region:** Target project to deploy in. -- **Version:** Default to the latest unless you need compatibility with an older +- **In a project:** Add it to an existing project. Action button "Add to + Project". +- **New Project:** Provision it alongside a new project. Action button "Review + and Install". + +You then set these fields: + +- **Project:** The target project (only when installing into an existing + project). +- **Region:** The AWS region the service runs in. +- **Version:** Defaults to the latest unless you need compatibility with an older stack. -- **Network Token:** - - Select an Existing Network to have TagoDeploy create and bind a Network - Token for that network, or - - Use custom token to paste a specific Network Token that the middleware - should use. -- **TagoIO API URL:** Pre-filled with your project’s API endpoint. +- **Name:** Display name for the service instance, under Settings. +- **Network Token:** The token the middleware uses to write and read in your + project. +- **TagoIO API URL:** Pre-filled with your project's API endpoint. -You can review the configuration and deploy. The service will provision -networking, compute, and a default autoscaling policy. +Confirm to deploy. The service provisions networking, compute, and a default +autoscaling policy. ### Domains @@ -52,9 +62,10 @@ Registration at ## Using the Middleware -Once deployed, you can use the middleware’s public endpoint with your external -network or platform. Follow the integration steps for your network in the TagoIO -documentation at [TagoIO Network Integrations](/docs/tagodeploy/project/configuration/integrations.md). +Once deployed, you can use the middleware's public endpoint with your external +network or platform. You can find the endpoint URL on the middleware's Overview +page in the project, and follow the integration steps for your network in the +TagoIO documentation. The middleware authenticates using the Network Token you selected at install time. That token scopes which devices the middleware can write and read in your diff --git a/docs/tagodeploy/services/middlewares/managing-middleware.md b/docs/tagodeploy/services/middlewares/managing-middleware.md index 720aba0b..69908958 100644 --- a/docs/tagodeploy/services/middlewares/managing-middleware.md +++ b/docs/tagodeploy/services/middlewares/managing-middleware.md @@ -6,31 +6,33 @@ tags: ["tagodeploy"] slug: /tagodeploy/services/middlewares/managing-middleware --- -Open Services > [Middleware Name] in your project to view and change settings. -Most updates apply without downtime; scaling actions may briefly recycle -instances. +After you install a middleware from the App Catalog, it appears as a resource tab +in the project breadcrumb, labeled with its display name. Open that tab to view +and change settings. The middleware sub-navigation has Overview, Instances, and +Settings. Most updates apply without downtime; scaling actions may briefly +recycle instances. ### Settings -- Name: Change the display name shown in Services. +- Name: Change the display name shown in the project. - Network Token: Locked by default to prevent accidental changes. Unlock to switch the token if you must move the middleware to a different network context. -- TagoIO API URL: Your project’s internal API endpoint. Normally you don’t +- TagoIO API URL: Your project's internal API endpoint. Normally you don't change this. ### Instance Settings and Scaling Middleware services support vertical and horizontal scaling. Choose a -configuration that matches your traffic pattern—message rate, payload size, and +configuration that matches your traffic pattern: message rate, payload size, and downlink volume. Recommended baseline for typical production projects up to ~10,000 devices connected through a single middleware: - **Machine:** 1 vCPU / 2 GB RAM -- **Minimum instances:** 1–2 (use 2 for higher availability) -- **Maximum instances:** 3–5 +- **Minimum instances:** 1 to 2 (use 2 for higher availability) +- **Maximum instances:** 3 to 5 - **Scale on CPU utilization:** 60% - **Cooldown for scaling up:** 200 seconds - **Cooldown for scaling down:** 300 seconds @@ -67,9 +69,10 @@ confirm whether bursts or steady load are the cause. ### Updating and Versioning -When a new middleware version is available, use the Update action in the service -page. For non-breaking updates, rolling replacement keeps the endpoint -available. For major changes, validate in a non‑production project first. +Platform and service versions are managed from the project's System page, under +Version Timeline. Newer versions offer an Update action, and older versions offer +Rollback. For non-breaking updates, rolling replacement keeps the endpoint +available. For major changes, validate in a non-production project first. ## Troubleshooting From e36f65a682fd450e2d0bbeb54cd5749fc858c824 Mon Sep 17 00:00:00 2001 From: Ricardo Stoklosa Date: Fri, 29 May 2026 16:01:43 -0300 Subject: [PATCH 15/15] docs: record orphan-doc disposition and product flags --- specs/orphans-disposition.md | 50 ++++++++++++++++++++++++++++++++++++ 1 file changed, 50 insertions(+) create mode 100644 specs/orphans-disposition.md diff --git a/specs/orphans-disposition.md b/specs/orphans-disposition.md new file mode 100644 index 00000000..8a593c5d --- /dev/null +++ b/specs/orphans-disposition.md @@ -0,0 +1,50 @@ +# Orphan Docs Disposition + +Outcome of auditing the 8+ docs the SPA registry never links, against the live SPA survey. + +## Wire-up candidate (real SPA control, add to registry + DocsButton) + +- **`project/system/open-connectors`** (`configuration/system/open-connectors.md`). + The SPA HAS this: an "Open Connectors" section on the System page (`/tago-io/system`, + below the Version Timeline) with a "Sync connectors" action and a "No connectors synced yet" + empty state. Content was corrected. Recommend registering a slug and adding a DocsButton on the + System page in the deploy repo. + +## No standalone page (sub-section of a parent screen) — keep as corrected cross-reference stubs, do NOT wire + +- **`mqtt/acl-permissions`**: ACLs are rows inside Groups (Allow/Deny, Subscribe/Publish, Topic). + Full model now lives in `mqtt/groups.md`. Stub kept, points to Groups. +- **`mqtt/credentials`**: one of two client Authentication types inside Clients. Covered in + `mqtt/clients.md`. Stub kept, points to Clients. +- **`mqtt/topic-mappings`**: a section on the Pipelines page, no own route. Covered in + `mqtt/pipelines.md`. Stub kept, points to Pipelines. +- **`container/docker-image`, `container/environment-variables`, `container/network`, + `container/runtime`**: all collapsible sections of one "Docker Settings" page + (`/docker/{id}/settings`), not separate pages. Content corrected per section. + +## Obsolete (page does not exist in the SPA) + +- **`container/logs`**: the container resource has no Logs sub-page (sub-nav is Overview, + Instances, Settings). Runtime logs live at Management > Logs (project-level). Flagged as a + deletion candidate. Not deleted; left for reviewer decision. + +## Consolidation recommendation (for a follow-up, not this PR) + +The four container settings docs map to one SPA page. A future pass could merge +`docker-image` + `environment-variables` + `network` + `runtime` into a single "Docker Settings" +doc with H2 sections, matching the UI one-to-one. None of these four slugs is in the registry, so +there is no link cost to consolidating. Kept separate in this PR to avoid a destructive change +without sign-off. + +## Product flags surfaced during the refresh (confirm before publish) + +- **Bills "Queue" category**: the Bills page lists a "Queue" service cost category, while + `packages/web/CLAUDE.md` says `data-queue` must not be surfaced in the UI. Documented per the + live UI; confirm this is intended. +- **Backups restore flow**: the page only lists snapshots; no restore UI was observed. Existing + restore guidance kept (unverified against the SPA). +- **Tokens dialog detail**: 10-token limit, last-four identification, Copy/Delete actions come + from the SPA local-fallback draft; the survey confirmed only the New Token dialog (no fields) + and the empty state. +- **In-Memory Database recommendation**: field default machine is 2 vCPU / 1GB RAM; the prior doc + recommended 2 vCPU / 4GB RAM. Documented the field default; recommendation left as a suggestion.