DOC-3498: tinymceai on-premises documentation#4142
Open
kemister85 wants to merge 15 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
|
|
||
| The TinyMCE AI on-premises service is now running. | ||
|
|
||
| == Verifying the installation |
Contributor
There was a problem hiding this comment.
this section is confusing to read because there's no breaks between the steps being checked. needs some subheadings / bold titles / at least a sentence about what each step is checking. otherwise the snippets for expected then next step flow into each other
metricjs
reviewed
May 21, 2026
| [[postgresql-schema-prerequisite]] | ||
| == PostgreSQL schema prerequisite | ||
|
|
||
| The AI service expects a schema named `cs-on-premises` (with a hyphen). If that schema does not exist, the container crashes on first boot with: |
Contributor
There was a problem hiding this comment.
Suggested change
| The AI service expects a schema named `cs-on-premises` (with a hyphen). If that schema does not exist, the container crashes on first boot with: | |
| The AI service expects a schema named `cs-on-premises` (with hyphens). If that schema does not exist, the container crashes on first boot with: |
nitpick
metricjs
reviewed
May 21, 2026
|
|
||
| Pin to `mysql:8.0` in every manifest: `docker run`, Docker Compose, Kubernetes, Helm, ECS. Running newer MySQL versions with workarounds (removing the flag and switching to `caching_sha2_password`) is not a supported configuration. | ||
|
|
||
| TIP: The same principle applies to PostgreSQL. Pin `postgres:16` rather than `postgres:latest`. |
Contributor
There was a problem hiding this comment.
I'd put this in a postgres section, not here?
metricjs
reviewed
May 21, 2026
|
|
||
| This bypasses the hyphenated schema entirely. | ||
|
|
||
| NOTE: MySQL does not have this issue. The database itself is the namespace, set through `DATABASE_DATABASE`. |
Contributor
There was a problem hiding this comment.
this feels a little weird to me to include? at least here
metricjs
reviewed
May 21, 2026
| [[database-user-privileges]] | ||
| == Database user privileges | ||
|
|
||
| On first boot the AI service runs schema migrations and creates roughly 32 tables across the following namespaces: `ai_assistant_*`, `environments__*`, `security__*`, `insights__*`, `blob_storage__*`, and `cs_migrations*`. |
Contributor
There was a problem hiding this comment.
my audit flagged this too iirc, but formatting is weird here
Contributor
There was a problem hiding this comment.
Suggested change
| On first boot the AI service runs schema migrations and creates roughly 32 tables across the following namespaces: `ai_assistant_*`, `environments__*`, `security__*`, `insights__*`, `blob_storage__*`, and `cs_migrations*`. | |
| On first boot the AI service runs schema migrations and creates roughly 32 tables across the following namespaces: `ai_assistant_*`, `environments_*`, `security_*`, `insights_*`, `blob_storage_*`, and `cs_migrations*`. |
I'm guessing the __ should be _?
metricjs
reviewed
May 21, 2026
|
|
||
| [NOTE] | ||
| -- | ||
| Some builds report false-positive "Not enough permissions to access database" errors even with `ALL PRIVILEGES`. If this occurs, grant the privileges globally rather than per-database, or use the MySQL `root` user for development. |
Contributor
There was a problem hiding this comment.
"builds"? as in builds of the service, builds of the databases, what?
metricjs
reviewed
May 21, 2026
| ---- | ||
| ==== | ||
|
|
||
| If `DATABASE_SCHEMA=public` was chosen, substitute `public` for `"cs-on-premises"` in each grant statement. |
Contributor
There was a problem hiding this comment.
move this above the examples? so someone doesn't try them as is, find they fail, then come back looking for more info
metricjs
reviewed
May 21, 2026
| ---- | ||
| ==== | ||
|
|
||
| After `docker compose up -d`, create the PostgreSQL schema (if not using `DATABASE_SCHEMA=public`): |
Contributor
There was a problem hiding this comment.
Suggested change
| After `docker compose up -d`, create the PostgreSQL schema (if not using `DATABASE_SCHEMA=public`): | |
| If using PostgreSQL and not using `DATABASE_SCHEMA=public`, after `docker compose up -d`, create the PostgreSQL schema: |
put the conditions first for anyone skimming
Contributor
There was a problem hiding this comment.
actually this section confuses me. whats the purpose of the Docker single container section? to run the containers? and why are we repeating the postgres thing at the top and bottom of this section?
Contributor
There was a problem hiding this comment.
might just be that I'm not familiar with docker compose, but Idk how to follow the Docker compose + Docker single container sections. are those steps? what do I do with the snippets?
metricjs
reviewed
May 21, 2026
|
|
||
| Mount the certificate file into the container and reference the path in `DATABASE_SSL_CA`. Download the CA bundle from the cloud provider documentation. | ||
|
|
||
| NOTE: `DATABASE_SSL_CERT` and `DATABASE_SSL_KEY` are required only for mutual TLS (mTLS). Most managed database services require only the CA certificate for server verification. |
Contributor
There was a problem hiding this comment.
Suggested change
| NOTE: `DATABASE_SSL_CERT` and `DATABASE_SSL_KEY` are required only for mutual TLS (mTLS). Most managed database services require only the CA certificate for server verification. | |
| NOTE: Most managed database services require only the CA certificate for server verification. However `DATABASE_SSL_CERT` and `DATABASE_SSL_KEY` are also required only for mutual TLS (mTLS). |
?
metricjs
reviewed
May 21, 2026
|
|
||
| === Setup | ||
|
|
||
| Redis is typically included in the Docker Compose file alongside the database (see the compose examples above). For standalone setup: |
Contributor
There was a problem hiding this comment.
Suggested change
| Redis is typically included in the Docker Compose file alongside the database (see the compose examples above). For standalone setup: | |
| When using Docker Compose files, Redis is typically included alongside the database (see the compose examples above). For standalone setup: |
?
metricjs
reviewed
May 21, 2026
| :description: Database, Redis, and file storage setup for the TinyMCE AI On-Premises service | ||
| :keywords: AI, on-premises, database, MySQL, PostgreSQL, Redis, Docker, Podman, file storage, S3, Azure Blob | ||
|
|
||
| This page covers the data layer: the SQL database, Redis, and file storage. |
Contributor
There was a problem hiding this comment.
just realised that because of other changes to the docs, we no longer explain what the data layer does or why you need db + redis... anywhere? flagging here, but I might make a couple suggestions elsewhere for this...
Contributor
There was a problem hiding this comment.
co-opting my old draft
Suggested change
| This page covers the data layer: the SQL database, Redis, and file storage. | |
| This page covers the data layer: the SQL database, Redis, and file storage. The purpose of each is: | |
| - **SQL database:** Stores persistent data such as configurations, conversations, files, and documents. | |
| - **Redis:** Handles temporary data and inter-instance communication for scaling. When multiple application instances are running, Redis ensures that data is shared correctly across all of them. | |
| - **File storage:** Stores uploaded files and documents. |
metricjs
reviewed
May 21, 2026
| The service ships as a single Open Container Initiative (OCI) container image (`registry.containers.tiny.cloud/ai-service-tiny`). It exposes a REST API, a Management Panel, Server-Sent Events streaming, and an OpenAPI spec. | ||
|
|
||
| == Architecture | ||
|
|
Contributor
There was a problem hiding this comment.
per other comment, realised we don't actually describe the architecture anywhere. throwing this in from my old docs draft - feel free to massage
Suggested change
| The TinyMCE AI service infrastructure consists of two layers: | |
| The **application layer** runs the AI service and communicates with LLM providers to process AI requests. It may consist of one or more application server instances, each running the TinyMCE AI service Docker image, and, optionally, a load balancer to distribute incoming requests across the instances. The round-robin algorithm is recommended if using a load balancer. | |
| The **data layer** consists of a SQL database, a Redis instance, and file storage. The purpose of each is: | |
| - **SQL database:** Stores persistent data such as configurations, conversations, files, and documents. | |
| - **Redis:** Handles temporary data and inter-instance communication for scaling. When multiple application instances are running, Redis ensures that data is shared correctly across all of them. | |
| - **File storage:** Stores uploaded files and documents. | |
| === Data flow | |
metricjs
reviewed
May 21, 2026
|
|
||
| == Provider and model architecture | ||
|
|
||
| The AI service uses two related environment variables: |
Contributor
There was a problem hiding this comment.
we say two env vars, but the table has three rows?
metricjs
reviewed
May 21, 2026
|
|
||
|
|
||
|
|
||
| The `PROVIDERS` environment variable tells the AI service how to reach the configured large language model (LLM) provider. The `MODELS` environment variable tells the service which models are exposed to clients and which features each model supports. This page documents every supported `type`, every required field, and every known production issue for both variables. |
Contributor
There was a problem hiding this comment.
should describe not just what the page does, but why its useful? additionally, I have no idea how this fits into the overall steps for setting up the service. what file do these vars go in? when do I set them? as a reference page this seems fine, but coming here straight from the nav leaves me without context, and idk if another page is pointing people here at the right point in the process?
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
2 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