Skip to content

DOC-3498: tinymceai on-premises documentation#4142

Open
kemister85 wants to merge 20 commits into
tinymce/8from
hotfix/8/DOC-3498
Open

DOC-3498: tinymceai on-premises documentation#4142
kemister85 wants to merge 20 commits into
tinymce/8from
hotfix/8/DOC-3498

Conversation

@kemister85
Copy link
Copy Markdown
Contributor

@kemister85 kemister85 commented May 18, 2026 •
edited
Loading

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 to tinymce/8 for independent merge.

New pages (10)

Page Scope
Overview Architecture, capabilities, prerequisites, setup paths, and support
Getting started Five-minute Docker Compose quick start with end-to-end smoke test
Database, Redis, and storage MySQL/PostgreSQL setup, Redis configuration, container runtimes, and managed cloud options
LLM providers OpenAI, Anthropic, Google Gemini, Azure OpenAI, AWS Bedrock, Google Vertex AI, and self-hosted endpoints
JWT authentication HS256 signing model, claims, permissions reference, and token endpoint examples in 8 languages
TinyMCE integration Editor-side configuration, token provider, CORS, CSP, and SSR patterns
Production deployment Podman, Kubernetes, AWS ECS, scaling, security hardening, observability, rate limiting, backup/recovery, and sizing
Advanced scenarios MCP integration, web scraping/search, multi-tenant patterns, custom models with guardrails, and AI-powered document pipelines
Troubleshooting Quick triage, container startup, JWT, LLM provider, editor, and performance diagnostics
Reference Environment variables, API endpoints, SSE events, error codes, and known limits

Assets

  • Include new Mermaid .mmd source files with pre-rendered .svg diagrams
  • Render script at -scripts/render-mermaid.sh
  • All diagrams set to width=100% for responsive scaling

Navigation

nav.adoc updated 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:

  • Generalized overview for standalone API use (not just TinyMCE)
  • Simplified architecture diagram on overview; detailed version moved to production page
  • Redis Sentinel marked as not supported
  • "Framework integration" renamed to "TinyMCE integration"
  • License key reference for on-premises deployments
  • LLM provider wording corrected (native vs OpenAI-compatible)
  • Troubleshooting flowchart replaced with triage list
  • Docker image name updated to `ai-service-tiny` per confirmed registry URL

Pre-checks

  • Branch prefixed with `hotfix/8/`
  • `modules/ROOT/nav.adoc` has been updated
  • Local build passes with no new errors
  • Documentation Team Lead has reviewed

kemister85 added 5 commits May 18, 2026 14:31
@kemister85
DOC-3498: tinymceai on-prem documentation.
3ca63c6
@kemister85
DOC-3498: Address content gaps identified in source audit
8bb3162 
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.
@kemister85
DOC-3498: Expand acronyms on first prose use across on-premises pages
deae589 
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.
@kemister85
DOC-3498: Clean up architecture overview diagram
3bb5069 
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.
@kemister85
DOC-3498: Address PR review feedback from metricjs
68ed54f 
- 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
@kemister85 kemister85 requested review from a team and soritaheng as code owners May 18, 2026 04:34
@kemister85
DOC-3498: Update Docker image name to ai-service-tiny
260ed25 
Registry URL confirmed as registry.containers.tiny.cloud/ai-service-tiny.
@kemister85 kemister85 force-pushed the hotfix/8/DOC-3498 branch from a80cb4c to 260ed25 Compare May 18, 2026 04:37
@kemister85 kemister85 mentioned this pull request May 18, 2026
Closed
5 tasks
kemister85 added 4 commits May 19, 2026 13:36
@kemister85
DOC-3498: Address review feedback from tiny-ben-tran and ArvinJ-H
2e68692 
- 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
@kemister85
DOC-3498: Remove internal testing reference from performance note
84caab2
@kemister85
DOC-3498: Remove unverified performance and sizing sections
21c8452 
Remove Performance characteristics and Sizing guide from the
production page until engineering provides verified data.
@kemister85
DOC-3498: Remove redundant [arabic] list style attributes
cf8b90f
@kemister85
DOC-3498: Address evaluation findings from on-prem setup testing
42fb21f 
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
metricjs reviewed May 20, 2026
View reviewed changes
Comment thread modules/ROOT/pages/tinymceai-on-premises-getting-started.adoc Outdated
metricjs
metricjs reviewed May 20, 2026
View reviewed changes
Comment thread modules/ROOT/pages/tinymceai-on-premises-getting-started.adoc Outdated
metricjs
metricjs reviewed May 20, 2026
View reviewed changes
Comment thread modules/ROOT/pages/tinymceai-on-premises-getting-started.adoc
metricjs
metricjs reviewed May 20, 2026
View reviewed changes
Comment thread modules/ROOT/pages/tinymceai-on-premises-getting-started.adoc
metricjs
metricjs reviewed May 20, 2026
View reviewed changes
Comment thread modules/ROOT/pages/tinymceai-on-premises-getting-started.adoc Outdated
metricjs
metricjs reviewed May 20, 2026
View reviewed changes
Comment thread modules/ROOT/pages/tinymceai-on-premises-getting-started.adoc Outdated
metricjs
metricjs reviewed May 20, 2026
View reviewed changes
Comment thread modules/ROOT/pages/tinymceai-on-premises-getting-started.adoc Outdated
metricjs
metricjs reviewed May 20, 2026
View reviewed changes
Comment thread modules/ROOT/pages/tinymceai-on-premises-getting-started.adoc Outdated
kemister85 added 4 commits May 20, 2026 21:34
@kemister85
DOC-3498: Apply CockroachDB-benchmark review pass and address PR feed…
ad5b4ed 
…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
@kemister85
DOC-3498: Style fixes, terminology consistency, and external links
9781ec5 
- 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
@kemister85
Restructure Advanced scenarios page into focused child pages
532e30f 
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.
@kemister85
Fix audit findings across all on-premises documentation
0e15d60 
- 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
metricjs reviewed May 21, 2026
View reviewed changes
Comment thread modules/ROOT/pages/tinymceai-on-premises-getting-started.adoc
metricjs
metricjs reviewed May 21, 2026
View reviewed changes
Comment thread modules/ROOT/pages/tinymceai-on-premises-database.adoc Outdated
metricjs
metricjs reviewed May 21, 2026
View reviewed changes
Comment thread modules/ROOT/pages/tinymceai-on-premises-database.adoc Outdated
metricjs
metricjs reviewed May 21, 2026
View reviewed changes
Comment thread modules/ROOT/pages/tinymceai-on-premises-database.adoc Outdated
metricjs
metricjs reviewed May 21, 2026
View reviewed changes
Comment thread modules/ROOT/pages/tinymceai-on-premises-database.adoc
metricjs
metricjs reviewed May 21, 2026
View reviewed changes
Comment thread modules/ROOT/pages/tinymceai-on-premises-database.adoc Outdated
metricjs
metricjs reviewed May 21, 2026
View reviewed changes
Comment thread modules/ROOT/pages/tinymceai-on-premises-database.adoc Outdated
metricjs
metricjs reviewed May 21, 2026
View reviewed changes
Comment thread modules/ROOT/pages/tinymceai-on-premises-database.adoc Outdated
metricjs
metricjs reviewed May 21, 2026
View reviewed changes
Comment thread modules/ROOT/pages/tinymceai-on-premises-database.adoc Outdated
metricjs
metricjs reviewed May 21, 2026
View reviewed changes
Comment thread modules/ROOT/pages/tinymceai-on-premises-database.adoc Outdated
metricjs
metricjs reviewed May 21, 2026
View reviewed changes
Comment thread modules/ROOT/pages/tinymceai-on-premises-database.adoc Outdated
metricjs
metricjs reviewed May 21, 2026
View reviewed changes
Comment thread modules/ROOT/pages/tinymceai-on-premises.adoc
metricjs
metricjs reviewed May 21, 2026
View reviewed changes
Comment thread modules/ROOT/pages/tinymceai-on-premises-providers.adoc
metricjs
metricjs reviewed May 21, 2026
View reviewed changes
Comment thread modules/ROOT/pages/tinymceai-on-premises-providers.adoc Outdated
kemister85 added 5 commits May 21, 2026 19:05
@kemister85
Add architecture diagram, page intros, and address PR feedback
e006b46 
- 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
@kemister85
Improve providers diagram readability
08c74b8 
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.
@kemister85
Restructure OpenAI-compatible provider section for clarity
bbe55ce 
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.
@kemister85
Increase overview architecture diagram width to 1200px
d663c61
@kemister85
Normalize definition-style lists to colon delimiter
ccfe41e 
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.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@metricjs metricjs metricjs left review comments

@soritaheng soritaheng Awaiting requested review from soritaheng soritaheng is a code owner

@EkimChau EkimChau Awaiting requested review from EkimChau EkimChau is a code owner automatically assigned from tinymce/documentation-team

@MitchC1999 MitchC1999 Awaiting requested review from MitchC1999 MitchC1999 is a code owner automatically assigned from tinymce/documentation-team

@tiny-ben-tran tiny-ben-tran Awaiting requested review from tiny-ben-tran tiny-ben-tran is a code owner automatically assigned from tinymce/documentation-team

@tjdett tjdett Awaiting requested review from tjdett

@frossi933 frossi933 Awaiting requested review from frossi933

@ArvinJ-H ArvinJ-H Awaiting requested review from ArvinJ-H

@hamza0867 hamza0867 Awaiting requested review from hamza0867

@ShiridiGandham ShiridiGandham Awaiting requested review from ShiridiGandham

At least 2 approving reviews are required to merge this pull request.

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

2 participants

@kemister85 @metricjs