docs: document the attach deployment topology

[pratyush618]

Closes #555. S9 of the executor-attach plan — the last piece before the Helm chart (#556).

deployment.mdx gains an ## Attached executors section covering the split topology end to end.

What it documents

• When the split is worth it — duplicate resident RAM and autoscale cold start, explicitly not disk, which layer sharing already handles.
• Compose — the scheduler service plus the existing app image with an executor command. No new build, no new pull.
• Kubernetes — two shapes. Same-pod over a Unix socket on a shared emptyDir (scheduler as a native sidecar, executor from the app image), and one scheduler over TCP with its own Deployment and Service.
• Security requirements, stated as requirements: routable binds need a token, the token comes from the environment and never argv, mTLS terminates in a front proxy, the attach port is never published, and for a Unix socket the filesystem is the whole boundary.
• SOCI / eStargz as the complementary fix for cold start when staying with a conventional worker — and its limit: it fixes the pull, not the second resident runtime.
• Costs — CPU-heavy tasks competing with request latency, a network hop per job, and one more process to operate.

Two things the code says that the plan doc did not

• The server terminates no TLS. config/listen.rs bails when TASKITO_LISTEN_TLS_CERT/_KEY are set, so the docs say proxy-terminated mTLS with the token as the second factor.
• A Unix-socket attach is uid-gated. UnixListener::bind leaves the socket at umask-derived 0755 and connect(2) needs write permission, so a same-pod attach only works when both containers share runAsUser. The manifest sets it explicitly and says why.

Also

• The attach guide showed port 7749; the published image EXPOSEs 7777, as do the server README and --help. Realigned, and cross-linked to the new section.
• One commit syncs the generated changelog page, which was stale against the root CHANGELOG.md.

Follow-up not taken here

Nothing chmods the attach socket. set_permissions(0o660) plus a documented group would make the Unix-socket case work across uids instead of relying on operators matching them. Out of scope for a docs change; worth its own issue.

Verification

pnpm --dir docs lint, typecheck, check:parity (CodeTabs SDK coverage ok) and a full build all pass. The section renders on all three SDK routes and the #attached-executors anchor resolves from the checklist and the attach guide.

Summary by CodeRabbit

• Documentation
  • Documented the taskito-server distroless container image for Linux AMD64 and ARM64, including PostgreSQL and Redis support.
  • Added deployment guidance for attached executors using Docker Compose and Kubernetes, covering connectivity, configuration, security, reconnection, scaling, and operational considerations.
  • Updated executor examples and error messages across supported SDKs to use attach port 7777.
  • Added an operational checklist covering port isolation, authentication tokens, and mTLS for non-loopback connections.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: 2ec05db8-0b3b-45fc-bf39-d8ac30e972b8

📥 Commits

Reviewing files that changed from the base of the PR and between 5affab4 and 445f43a.

📒 Files selected for processing (6)

• crates/taskito-core/src/worker/executor.rs
• docs/content/docs/shared/guides/operations/deployment.mdx
• sdks/java/src/main/java/org/byteveda/taskito/cli/Cli.java
• sdks/java/src/main/java/org/byteveda/taskito/worker/Executor.java
• sdks/node/src/executor.ts
• sdks/python/taskito/cli.py

🔗 Linked repositories identified

CodeRabbit considers these linked repositories for cross-repo context during reviews:

• ByteVeda/taskito (manual)

🚧 Files skipped from review as they are similar to previous changes (1)

• docs/content/docs/shared/guides/operations/deployment.mdx

---

📝 Walkthrough

Walkthrough

The operations guide now documents attached executors with Docker Compose and Kubernetes Unix-socket or TCP deployments. It adds security and scaling guidance, updates executor examples to port 7777, and records the multi-architecture taskito-server image.

Changes

Attached executor deployment

Layer / File(s)	Summary
Deployment model and Compose configuration docs/content/docs/shared/guides/operations/deployment.mdx	Defines scheduler and executor responsibilities. Adds Compose configurations with attachment endpoints, tokens, slot limits, restart behavior, and isolated database credentials.
Kubernetes deployment topologies docs/content/docs/shared/guides/operations/deployment.mdx	Adds same-pod Unix-socket and dedicated Deployment TCP patterns with shared volumes, tokens, probes, executor settings, and dashboard exposure guidance.
Operational guidance and documentation alignment docs/content/docs/shared/guides/operations/deployment.mdx, docs/content/docs/shared/guides/operations/executor.mdx, crates/taskito-core/src/worker/executor.rs, sdks/java/src/main/java/org/byteveda/taskito/cli/Cli.java, sdks/java/src/main/java/org/byteveda/taskito/worker/Executor.java, sdks/node/src/executor.ts, sdks/python/taskito/cli.py, docs/content/docs/resources/changelog.mdx	Adds security, scaling, and cost guidance. Updates attachment examples and error messages from port 7749 to 7777. Documents the distroless multi-architecture server image.

Estimated code review effort: 3 (Moderate) | ~20 minutes

Possibly related issues

• Executor Attach: detached scheduler with a language-agnostic deploy image #546 — Covers the attached-executor deployment model and standardized attach port documented here.

Possibly related PRs

• ByteVeda/taskito#595 — Introduces the executor functionality that this PR documents and aligns with port 7777.
• ByteVeda/taskito#603 — Adds related attached-executor documentation updated by this PR.
• ByteVeda/taskito#610 — Documents the related distroless taskito-server image and attach listener configuration.

Suggested labels: deployment

Suggested reviewers: stromanni

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly and concisely describes the main change: documenting the attach deployment topology.
Linked Issues check	✅ Passed	The deployment guide covers the linked issue's topology, security, cold-start, scaling, and limitation requirements, with related port updates synchronized.
Out of Scope Changes check	✅ Passed	The changelog, cross-links, and attach-port updates directly support or synchronize the documented deployment-topology change.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

---

_{Comment @coderabbitai help to get the list of available commands.}

[coderabbitai]

Actionable comments posted: 4

🧹 Nitpick comments (1)

docs/content/docs/shared/guides/operations/deployment.mdx (1)

1626-1628: 📐 Maintainability & Code Quality | 🔵 Trivial | 💤 Low value

Match the phrasing of the other checklist items.

Every other item in this checklist is an imperative statement. This item opens with a question. A conditional clause keeps the list uniform and states the condition before the action.

♻️ Proposed wording

-- [ ] Running [attached executors](`#attached-executors`)? Keep the attach port off
-      the host network, set `TASKITO_ATTACH_TOKEN` for any bind but loopback, and
-      terminate mTLS in front of it
+- [ ] For [attached executors](`#attached-executors`), keep the attach port off the
+      host network, set `TASKITO_ATTACH_TOKEN` for any bind but loopback, and
+      terminate mTLS in front of it

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@docs/content/docs/shared/guides/operations/deployment.mdx` around lines 1626
- 1628, Rewrite the checklist item around “attached executors” as an imperative
conditional statement rather than a question, placing the condition first and
preserving the existing actions: keep the attach port off the host network, set
TASKITO_ATTACH_TOKEN for non-loopback binds, and terminate mTLS in front of it.

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@docs/content/docs/shared/guides/operations/deployment.mdx`:
- Around line 672-679: In the executor manifest example, replace the empty
command array under the executor container with a clear comment placeholder
indicating that an SDK-specific command must be supplied. Keep the surrounding
image, environment variables, and per-SDK command guidance unchanged.
- Around line 643-650: Update the adjacent deployment comment to state that the
Unix socket mode is derived from 0777 & ~umask, with 0755 resulting from the
common umask 022, rather than presenting 0755 as fixed. Preserve the
access-boundary conclusion while explicitly noting that it depends on the umask
clearing group and other write permissions.
- Around line 774-777: Update the readinessProbe configuration to work when
TASKITO_DASHBOARD_AUTH is set to session: use the open readiness endpoint for an
unexposed dashboard, or configure probe credentials and send the required
Authorization header. Preserve the existing /readiness route and dashboard port.

In `@docs/content/docs/shared/guides/operations/executor.mdx`:
- Line 57: Replace all remaining 7749 references with 7777 across the Rust
examples and tests, Node and Java SDK messages and examples, and the Python CLI
message, while preserving unrelated port values and existing formatting.

---

Nitpick comments:
In `@docs/content/docs/shared/guides/operations/deployment.mdx`:
- Around line 1626-1628: Rewrite the checklist item around “attached executors”
as an imperative conditional statement rather than a question, placing the
condition first and preserving the existing actions: keep the attach port off
the host network, set TASKITO_ATTACH_TOKEN for non-loopback binds, and terminate
mTLS in front of it.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: e0b3cb9f-b7c1-4cef-adf2-26fbcde98578

📥 Commits

Reviewing files that changed from the base of the PR and between e0492f4 and 5affab4.

📒 Files selected for processing (3)

• docs/content/docs/resources/changelog.mdx
• docs/content/docs/shared/guides/operations/deployment.mdx
• docs/content/docs/shared/guides/operations/executor.mdx

🔗 Linked repositories identified

CodeRabbit considers these linked repositories for cross-repo context during reviews:

• ByteVeda/taskito (manual)