DOC-3498: tinymceai on-premises documentation#4142
Open
kemister85 wants to merge 21 commits into
Open
Conversation
Add missing customer-facing content identified by comparing the original internal documentation against the current on-premises AsciiDoc pages: capabilities matrix on the overview page, Podman production runbook, performance characteristics table, expanded known limits reference, MySQL 8.4 caveat, Ollama systemd and Modelfile examples, and getting-started teardown and config update guidance.
Expand 18 acronyms (OCI, JWT, LLM, SSE, TLS, CORS, MCP, NTP, HPA, OTLP, IRSA, ADC, SSR, CSP, SIEM, PII, HA, mTLS) on first prose occurrence per page for readers unfamiliar with the terms.
Reduce edge clutter by connecting a single representative replica to downstream services and grouping the data layer into a subgraph. Fix SVG width to use a fixed pixel value consistent with other diagrams in the set.
- Generalize overview page for standalone API use, not just TinyMCE - Swap complex architecture diagram for simplified overview diagram - Move detailed enterprise topology to production page (collapsible) - Fix capabilities table: chat, document review, file attachments, scaling - Redis: mark Sentinel as not supported - Remove TinyMCE 8.0+ from prerequisites (not required for API-only) - Reverse proxy changed from required to recommended - Fix decision tree cross-references (Section 33 -> guide names) - Replace troubleshooting flowchart with ordered triage list - Rename "Framework integration" to "TinyMCE integration" across all refs - Fix API key reference for on-prem (license key or API key) - Reorder support section docker commands for logical flow - Make MCP diagram arrows bidirectional - LLM providers: clarify native vs OpenAI-compatible providers - Re-render all mermaid diagrams
Registry URL confirmed as registry.containers.tiny.cloud/ai-service-tiny.
kemister85
force-pushed
the
hotfix/8/DOC-3498
branch
from
a80cb4c to
260ed25
Compare
5 tasks
- Soften privacy claim to clarify LLM provider data handling - Reword data flow steps (JWT, prompt phrasing) - Clarify setup path section and topic guide introduction - Remove orphan diagrams (troubleshooting-fig-1, complete-guide-fig-9) - Remove "Must include" from plugins table, fix troubleshooting wording - Replace MySQL 8.4 references with "the latest MySQL" across all pages - Add provenance NOTE to performance characteristics - Consolidate production page diagrams (promote complete-guide-fig-1) - Improve overview and providers diagram layouts (LR, spacing) - Move provider examples out of collapsible block for visibility
Remove Performance characteristics and Sizing guide from the production page until engineering provides verified data.
kemister85
requested review from
ArvinJ-H,
ShiridiGandham,
frossi933,
hamza0867,
metricjs and
tjdett
Fix Redis Sentinel contradiction, add terminationGracePeriodSeconds and PDB to K8s manifest, add S3 credentials and topology spread, bootstrap step after Service manifest, HPA I/O-bound caveat, managed database TLS section, Docker network resolution for Compose v2, MODELS requirement clarification, and assorted cross-links and callouts identified during the independent evaluation audit.
metricjs
reviewed
May 20, 2026
metricjs
reviewed
May 20, 2026
metricjs
reviewed
May 20, 2026
metricjs
reviewed
May 20, 2026
metricjs
reviewed
May 20, 2026
metricjs
reviewed
May 20, 2026
metricjs
reviewed
May 20, 2026
metricjs
reviewed
May 20, 2026
…back - Add Credentials table and OpenAPI capability to Overview - Expand CORS section with format, wildcards, preflight, common mistakes - Add production readiness checklist and prerequisite statement - Document agent-1 default model behavior on Providers page - Add MODELS and secrets to ECS task definition example - Document IAM/IRSA limitation across all deployment targets - Trim rate limiting, distributed logging, PDB, topology to one-liners - Remove marketing sections from Advanced (guardrails, document pipeline) - Label install commands in JWT examples for clarity - Address reviewer feedback on Getting Started clarity and formatting
- Fix "On-Premise" to "on-premises" in page titles
- Update Advanced description to match trimmed content
- Add external links: K8s Secrets, Ingress, HPA, KEDA, OTLP, nginx
- Replace jargon ("upstream", "definitive") with neutral phrasing
- Normalize xref capitalization to sentence case
- Replace "ensure" with direct imperatives per style guide
Move MCP and web scraping/search content to a dedicated child page (tinymceai-on-premises-mcp.adoc) under LLM providers. Move multi-tenant deployment content into the JWT authentication page. Delete the catch-all Advanced scenarios page and update all cross-references and nav accordingly.
- Getting Started: add ALLOWED_ORIGINS, fix CORS blocker, mark TINYMCE_API_KEY required for CDN demo, fix NOTE inside bash block, un-collapse launch script, add prerequisites section - Production: add missing storage secret keys to K8s Secret, add ALLOWED_ORIGINS to K8s and ECS, align HPA minReplicas, add ECS startPeriod, label Podman as eval-only storage - JWT: fix aud description, fix sanity-check port, coerce sub to String - Frameworks: add React, Vue, Angular minimal examples - Database: add AI service connection env vars section - MCP: label Express example as illustrative - Overview: add MCP to topic guides table
metricjs
reviewed
May 21, 2026
metricjs
reviewed
May 21, 2026
metricjs
reviewed
May 21, 2026
metricjs
reviewed
May 21, 2026
metricjs
reviewed
May 21, 2026
metricjs
reviewed
May 21, 2026
metricjs
reviewed
May 21, 2026
metricjs
reviewed
May 21, 2026
metricjs
reviewed
May 21, 2026
metricjs
reviewed
May 21, 2026
metricjs
reviewed
May 21, 2026
metricjs
reviewed
May 21, 2026
metricjs
reviewed
May 21, 2026
metricjs
reviewed
May 21, 2026
- Add deployment architecture diagram (overview-fig-2.svg) to Overview - Add "where this fits" introductory context to Database, Providers, JWT, and Frameworks pages linking to overall deployment flow - Un-nest MCP page to same nav level as other on-prem pages - Add Step 1/2/3 subheadings to Getting Started verification section - Remove raw Management API reference from Getting Started - Restructure Database version pinning into neutral parent section - Fix "two layers" to "three layers" matching the diagram - Address metricjs PR feedback: hyphens, TLS note, Redis wording, schema note ordering, conditions-first, section explanations
Add theme config with 14px font and wider node spacing, shorten truncated model names, use uniform arrow weight throughout, and fix SVG width to 1200px.
Un-collapse fields table and Ollama networking into visible sections, remove duplicated LLM_TIMEOUT_MS, consolidate vLLM and LM Studio into a comparison table, fix Verify to hit the AI service endpoint, and add a "when to use" introductory sentence.
Replace em dashes and double hyphens with colons in label:description list patterns across all on-premises pages. Normalize bold formatting to single-asterisk emphasis for consistency.
- Reorder nav: MCP moved after TinyMCE Integration, marked optional - Un-collapse token server, K8s manifest, and MySQL compose file - Add "Next steps" section to Getting Started bridging to production - Replace dynamic launch script with static docker run + TIP - Add expected boot log after docker run - Promote prerequisites to "Before you begin" with verification commands - Add complete docker run reference to Reference page - Add numbered steps (1-5) to Production K8s section - Standardize placeholders to <kebab-case> format across all pages - Condense agent-1 explanation on Providers page - Remove raw management API reference from Production page
| @@ -0,0 +1,14 @@ | |||
| flowchart LR | |||
Contributor
There was a problem hiding this comment.
hmmm... the output looks the same as modules/ROOT/images/tinymceai-on-premises/advanced-scenarios-fig-2.svg
| * A token endpoint exists that signs JSON Web Tokens (JWTs) for the AI service. See xref:tinymceai-on-premises-jwt.adoc[JWT authentication] for back-end implementations. | ||
| * A valid TinyMCE license key or API key with the AI feature enabled. On-premises deployments typically use a license key provided by a Tiny account representative. | ||
|
|
||
| For general framework setup (installing wrappers, component structure, server-side rendering (SSR) patterns), see the existing integration guides: |
Contributor
There was a problem hiding this comment.
Suggested change
| For general framework setup (installing wrappers, component structure, server-side rendering (SSR) patterns), see the existing integration guides: | |
| For general framework setup (installing wrappers, component structure), see the existing integration guides: |
|
|
||
|
|
||
|
|
||
| == Editor-side token provider |
Contributor
There was a problem hiding this comment.
Suggested change
| == Editor-side token provider | |
| == Editor-side configuration |
| @@ -0,0 +1,23 @@ | |||
| %%{init: {'theme': 'base', 'themeVariables': { 'primaryColor': '#ECECFF', 'primaryBorderColor': '#9370DB', 'lineColor': '#333333', 'edgeLabelBackground': '#e8e8e8', 'fontSize': '16px' }, 'flowchart': { 'nodeSpacing': 40, 'rankSpacing': 80 }}}%% | |||
Contributor
There was a problem hiding this comment.
Can a dotted box be added to clearly indicate client layer and application layer?
|
|
||
| === Data flow | ||
|
|
||
| Data flow for a single AI request: |
Contributor
There was a problem hiding this comment.
Suggested change
| Data flow for a single AI request: | |
| AI Request Flow |
Comment on lines
+30
to
+32
| . The AI service verifies the token, checks per-feature permissions, and forwards the prompt to the configured large language model (LLM). | ||
| . The LLM streams its response back to the AI service. | ||
| . The AI service relays the response to the client through Server-Sent Events (SSE). |
Contributor
There was a problem hiding this comment.
So the AI services are just a gate keeper that validates permissions and forwards prompts to a LLM? I believe it could be re-worded to be simpler
|
|
||
| When used with TinyMCE `tinymceai`, the plugin handles steps 1, 2, and 5 automatically through the `tinymceai_token_provider` callback. | ||
|
|
||
| IMPORTANT: The browser connects directly to the AI service — requests do not pass through the application back end. The AI service must be network-reachable from the end-user browser, which means it must have a public URL (or be accessible through a VPN/internal network when deployed on an intranet). Configure xref:tinymceai-on-premises-frameworks.adoc#_cross_origin_requests_to_the_ai_service[CORS] and xref:tinymceai-on-premises-production.adoc#_tls_https[TLS] on the AI service accordingly. |
Contributor
There was a problem hiding this comment.
Maybe just a note instead of important mark
|
|
||
| IMPORTANT: The browser connects directly to the AI service — requests do not pass through the application back end. The AI service must be network-reachable from the end-user browser, which means it must have a public URL (or be accessible through a VPN/internal network when deployed on an intranet). Configure xref:tinymceai-on-premises-frameworks.adoc#_cross_origin_requests_to_the_ai_service[CORS] and xref:tinymceai-on-premises-production.adoc#_tls_https[TLS] on the AI service accordingly. | ||
|
|
||
| The shared secret (API Secret) never leaves the back end; the editor and the AI service only ever see signed tokens. |
Contributor
There was a problem hiding this comment.
I believe that the secret never leaves the AI service Docker container.
| |Only for self-hosted editor deployments. Provided by the Tiny account representative. | ||
| |=== | ||
|
|
||
| NOTE: `LICENSE_KEY` (the AI service license) and `TINYMCE_API_KEY` / `license_key` (the editor license) are different credentials from different sources. Do not interchange them. |
Contributor
There was a problem hiding this comment.
Suggested change
| NOTE: `LICENSE_KEY` (the AI service license) and `TINYMCE_API_KEY` / `license_key` (the editor license) are different credentials from different sources. Do not interchange them. | |
| NOTE: `LICENSE_KEY` (the AI service license) and `TINYMCE_API_KEY` / `license_key` (the editor license) are different credentials from different sources. They are not interchangable. |
| [.text-center] | ||
| image::tinymceai-on-premises/complete-guide-fig-2.svg[Setup path decision tree,width=100%] | ||
|
|
||
| == Topic guides |
Contributor
There was a problem hiding this comment.
Do the topics mean to match each path on the flow chart?
| * A TinyMCE license key and container registry credentials (from the Tiny account representative) | ||
| * At least one LLM provider API key (OpenAI, Anthropic, or Google) | ||
|
|
||
| == Five-minute demo with Docker Compose |
Contributor
There was a problem hiding this comment.
Suggested change
| == Five-minute demo with Docker Compose | |
| == Quick demo with Docker Compose |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
4 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Ticket
DOC-3498
Summary
Complete on-premises deployment documentation for the TinyMCE AI service, cherry-picked from
feature/8.6.0/DOC-3401_DOC-3498(#4137) and retargeted totinymce/8for independent merge.New pages (10)
Assets
.mmdsource files with pre-rendered.svgdiagrams-scripts/render-mermaid.shwidth=100%for responsive scalingNavigation
nav.adocupdated with a new "On-premises deployment" section containing all 10 pages in logical reading order.Review feedback addressed
All review comments from PR #4137 have been incorporated, including:
Pre-checks