From be39ffe4a90a75d6ef262369dd6e20b718920efa Mon Sep 17 00:00:00 2001 From: Karl Kemister-Sheppard Date: Fri, 13 Jun 2025 15:57:36 +1000 Subject: [PATCH 1/9] DOC-3231: Refactor documentation for server-side components to support Docker deployment - Removed the deprecated logging services configuration documentation. - Updated references from WAR file deployment to Docker container deployment across multiple documents. - Revised installation and configuration instructions for spellchecking, image proxy, and media embed services to reflect Docker usage. - Added new sections for Docker image retrieval, configuration, and requirements. - Clarified system requirements and troubleshooting steps for Dockerized services. - Adjusted custom dictionaries and Hunspell dictionaries path requirements to remove references to Java services. - Updated supported application servers section to emphasize Docker as the primary deployment method. --- modules/ROOT/nav.adoc | 2 - modules/ROOT/pages/8.0-release-notes.adoc | 17 +- .../pages/configure-logging-services.adoc | 45 ---- .../pages/introduction-to-mediaembed.adoc | 2 +- ...uction-to-premium-selfhosted-services.adoc | 241 +++--------------- .../introduction-to-tiny-spellchecker.adoc | 2 +- .../ROOT/pages/mediaembed-server-config.adoc | 2 +- modules/ROOT/pages/support.adoc | 29 ++- modules/ROOT/pages/troubleshoot-server.adoc | 79 ++---- .../autocorrect_service_url.adoc | 4 +- .../image_proxy_service_url.adoc | 2 +- .../configuration/mediaembed_service_url.adoc | 2 +- .../configuration/spellchecker_rpc_url.adoc | 4 +- .../docker/common/docker-configuration.adoc | 12 + .../docker/common/docker-image-retrieval.adoc | 21 ++ .../docker/common/docker-requirements.adoc | 8 + .../common/docker-service-configuration.adoc | 98 +++++++ .../misc/custom-dictionaries-path.adoc | 2 +- .../misc/hunspell-dictionaries-path.adoc | 2 +- .../misc/supported-application-servers.adoc | 20 +- 20 files changed, 262 insertions(+), 332 deletions(-) delete mode 100644 modules/ROOT/pages/configure-logging-services.adoc create mode 100644 modules/ROOT/partials/docker/common/docker-configuration.adoc create mode 100644 modules/ROOT/partials/docker/common/docker-image-retrieval.adoc create mode 100644 modules/ROOT/partials/docker/common/docker-requirements.adoc create mode 100644 modules/ROOT/partials/docker/common/docker-service-configuration.adoc diff --git a/modules/ROOT/nav.adoc b/modules/ROOT/nav.adoc index 04ebfa9fe1..9d5dd4006f 100644 --- a/modules/ROOT/nav.adoc +++ b/modules/ROOT/nav.adoc @@ -140,8 +140,6 @@ **** xref:configure-imageproxy-service.adoc[Image Proxy service settings] **** xref:configure-spelling-service.adoc[Spelling service settings] **** xref:self-hosting-hunspell.adoc[Spelling service - Using Hunspell dictionaries] -**** xref:configure-logging-services.adoc[Activity logging] -*** xref:introduction-to-premium-selfhosted-services.adoc[Server-side component installation without Docker] *** xref:troubleshoot-server.adoc[Troubleshoot server-side components] ** Customizing the editor appearance *** xref:customize-ui.adoc[Customizing the UI] diff --git a/modules/ROOT/pages/8.0-release-notes.adoc b/modules/ROOT/pages/8.0-release-notes.adoc index 7c62f25b54..78f3894a8b 100644 --- a/modules/ROOT/pages/8.0-release-notes.adoc +++ b/modules/ROOT/pages/8.0-release-notes.adoc @@ -163,7 +163,22 @@ For information on using Enhanced Skins & Icon Packs, see: xref:enhanced-skins-a [[deprecated]] == Deprecated -{productname} {release-version} includes the following deprecation: +{productname} {release-version} includes the following deprecations: + +=== Java application server-based server components have been deprecated +// #DOC-3231 + +{productname} {release-version} deprecates the Java application server-based deployment method for self-hosted services. Docker containers are now the **only** supported deployment method for self-hosted services. The Java `.war` files (`ephox-spelling.war`, `ephox-image-proxy.war`, `ephox-hyperlinking.war`) will be removed in a future release. + +For information about setting up containerized server-side components using Docker containers, see: xref:bundle-intro-setup.adoc[Introduction and initial setup for containerized server-side services from the premium self-hosted bundles] + +=== Docker container services + +* Enhanced Media Embed and Link Checker service, see: xref:individual-hyperlinking-container.adoc[Deploy the {productname} hyperlinking server-side component using Docker]. +* Image Editing and Export image proxy service, see: xref:individual-image-proxy-container.adoc[Deploy the {productname} image proxy server-side component using Docker]. +* Spell Checker service, see: xref:individual-spelling-container.adoc[Deploy the {productname} spelling service server-side component using Docker]. +* Export to PDF service, see: xref:individual-export-to-pdf-on-premises.adoc[Deploy the {productname} Export to PDF service server-side component using Docker]. +* Import from Word and Export to Word services, see: xref:individual-import-from-word-and-export-to-word-on-premises.adoc[Deploy the {productname} Import from Word and Export to Word service server-side component using Docker]. // === The `` configuration property, ``, has been deprecated // #TINY-vwxyz1 diff --git a/modules/ROOT/pages/configure-logging-services.adoc b/modules/ROOT/pages/configure-logging-services.adoc deleted file mode 100644 index 2722f9807e..0000000000 --- a/modules/ROOT/pages/configure-logging-services.adoc +++ /dev/null @@ -1,45 +0,0 @@ -= Activity logging -:description: Setting up logging for the premium server-side components. - -It may be useful to make the {productname} server-side components write to their own log file. This can assist in troubleshooting and make it easier to provide logs as part of a support ticket. - -The {productname} server-side components use the http://logback.qos.ch/manual/configuration.html[Logback] logging format. - -To write the logs to a specific file: - -. Create a logging configuration XML file. Save the snippet below as `+logback.xml+` after replacing `+{$LOG_LOCATION}+` with the full path to the destination log file (e.g. /var/log/tinymce_server_components.log). -+ -[source,xml,subs="attributes+"] ----- - - - - - %d{HH:mm:ss.SSS} [%thread] %-5level %logger\{36} - %msg%n - - - - - {$LOG_LOCATION} - - %d{HH:mm:ss.SSS} [%thread] %-5level %logger\{36} - %msg%n - - - - - - - - - - - - - ----- -. Pass the configuration file to the Java application server. Assuming you've saved your `+logback.xml+` file in `+/etc/opt/tinymce+`, follow xref:introduction-to-premium-selfhosted-services.adoc#pass-the-configuration-file-to-the-java-application-server[step 4] and xref:introduction-to-premium-selfhosted-services.adoc#restart-the-java-application-server[step 5] on the _Install Server-side Components_ page to set the following JVM system property on your Java application server: -+ -.... --Dlogback.configurationFile=/etc/opt/tinymce/logback.xml -.... diff --git a/modules/ROOT/pages/introduction-to-mediaembed.adoc b/modules/ROOT/pages/introduction-to-mediaembed.adoc index a24671abd3..2e2b0c8af8 100644 --- a/modules/ROOT/pages/introduction-to-mediaembed.adoc +++ b/modules/ROOT/pages/introduction-to-mediaembed.adoc @@ -73,4 +73,4 @@ include::partial$configuration/mediaembed_max_width.adoc[leveloffset=+1] == Downloading Enhanced Media Embed plugin -A link:{pricingpage}/[{enterpriseversion} subscription] includes the ability to download and install the *Media Embed* plugin and a *WAR* file to access the service backend. Please follow these xref:introduction-to-premium-selfhosted-services.adoc#set-up-editor-client-instances-to-use-the-server-side-functionality[instructions] to configure the *WAR* file. +A link:{pricingpage}/[{enterpriseversion} subscription] includes the ability to pull down the Docker image for the *Media Embed* plugin. For more information on how to deploy the *Media Embed* plugin, please see the xref:individual-hyperlinking-container.adoc[Deploy the {productname} hyperlinking server-side component using Docker] guide. diff --git a/modules/ROOT/pages/introduction-to-premium-selfhosted-services.adoc b/modules/ROOT/pages/introduction-to-premium-selfhosted-services.adoc index 7d02b98d05..79f5ed7482 100644 --- a/modules/ROOT/pages/introduction-to-premium-selfhosted-services.adoc +++ b/modules/ROOT/pages/introduction-to-premium-selfhosted-services.adoc @@ -2,228 +2,71 @@ :description: Server-side components for premium plugins like spelling as-you-type. :keywords: enterprise, tinymcespellchecker, spell check, Spell Checker, editimage, server -Some {productname} Enterprise features require a server-side component. If you're using the {cloudname} solution, we've done all the hard work for you and you can skip this page. Alternatively, if you've purchased our Self-hosted solution then please read on. +Some {productname} Enterprise features require server-side components. If you're using the {cloudname} solution, we've done all the hard work for you and you can skip this page. Alternatively, if you've purchased our Self-hosted solution then please read on. -Server-side components must be deployed onto a Java Servlet 3.0 compatible application server. We currently support Jetty, Apache Tomcat, and WebSphere Application Server. To discuss support for additional Java application servers, please contact us at mailto:sales@tiny.cloud[sales@tiny.cloud] +IMPORTANT: As of {productname} 8.0, server-side components are only supported using Docker containers. The older Java application server-based deployment (.war files) has been deprecated. The following server-side components are included in the {productname} Self-hosted package: -[cols="<,<,<",options="header"] +[cols="<,<",options="header"] |=== -|Component |File |Description -|xref:introduction-to-tiny-spellchecker.adoc[Spellchecking], xref:autocorrect.adoc[Spelling Autocorrect] |ephox-spelling.war |Spell checking and Autocorrect service for {productname} Enterprise. -|xref:editimage.adoc[Image Editing] |ephox-image-proxy.war |Image proxy service for the Export and Image Editing plugins. -|xref:introduction-to-mediaembed.adoc[Enhanced Media Embed], xref:linkchecker.adoc[Link Checker] |ephox-hyperlinking.war |Link Checker and Enhanced Media Embed service for {productname} Enterprise. +|Component |Description +|xref:introduction-to-tiny-spellchecker.adoc[Spellchecking], xref:autocorrect.adoc[Spelling Autocorrect] |Spell checking and Autocorrect service for {productname} Enterprise +|xref:editimage.adoc[Image Editing] |Image proxy service for the Export and Image Editing plugins +|xref:introduction-to-mediaembed.adoc[Enhanced Media Embed], xref:linkchecker.adoc[Link Checker] |Link Checker and Enhanced Media Embed service for {productname} Enterprise |=== -NOTE: The "Allowed Origins" service (ephox-allowed-origins.war) has been deprecated. Trusted domains should now be specified directly in the configuration file. +NOTE: The configuration of xref:configure-required-services.adoc#allowed-origins[allowed origins] should be specified directly in the Docker container configuration file. -This guide will help you get these server-side components up and running. - -[[install-a-java-application-server]] -== Step 1. Install a Java application server - -If you've already got a Java application server like Jetty or Tomcat installed, skip to Step 2. - -If you don't, pick either http://tomcat.apache.org/[Tomcat] or https://www.eclipse.org/jetty/[Jetty] and install one of these with their default settings using the instructions on their website. +[[deploy-server-side-components]] +== Deploying server-side components using Docker [IMPORTANT] -.Memory requirement ==== -Please ensure that you configure your Java Server (Tomcat/Jetty etc) with a minimum of 4GB. Please refer to xref:troubleshoot-server.adoc#out-of-memory-errors[Out of memory errors] section of the Troubleshoot page if you require instructions on how to explicitly define how much RAM will be allocated to your Java server. +A valid access token is required to access the {companyname} Cloud Docker registry and pull the Docker images. Contact link:https://www.tiny.cloud/contact/[{companyname} Support^] to request the access token. ==== -[[deploy-server-side-components]] -== Step 2. Deploy server-side components - -Deploy all the WAR files that came packaged with the {productname} Enterprise Self-hosted package to your newly installed application server: +=== Requirements -* `ephox-spelling.war` -* `ephox-image-proxy.war` -* `ephox-hyperlinking.war` +* The link:https://docs.docker.com/engine/docker-overview/[Docker Engine^] is installed and running +* Administrative or Root user access to run Docker commands +* Either: +** A Unix-like operating system (Linux or macOS) +** Windows with Unix command line tools via link:https://gitforwindows.org/[Git for Windows^], link:https://www.cygwin.com/[Cygwin^], or link:https://docs.microsoft.com/en-us/windows/wsl/install-win10[Windows Subsystem for Linux^] -The easiest way to deploy these files is to copy them into the _webapps_ directory of your Tomcat/Jetty installation and then restart the application server. +For detailed requirements and setup instructions for each service, refer to: -IMPORTANT: Tomcat 10 will require the applications to be placed in the _webapps-javaee_ directory. Once placed there they will be converted by Tomcat to the Jakarta servlet framework. https://tomcat.apache.org/migration-10.html#Specification_APIs[Tomcat 10 Migration guide] +* For Spellchecking and Autocorrect services, see: xref:individual-spelling-container.adoc[Deploy the Spelling server-side component using Docker] +* For Image Editing service, see: xref:individual-image-proxy-container.adoc[Deploy the Image Proxy server-side component using Docker] +* For Enhanced Media Embed and Link Checker services, see: xref:individual-hyperlinking-container.adoc[Deploy the Hyperlinking server-side component using Docker] -More information can be found in the documentation of your chosen application server: +=== Configuration -* https://tomcat.apache.org/tomcat-9.0-doc/deployer-howto.html[Deploying applications with Tomcat 9.0] -* https://www.eclipse.org/jetty/documentation/current/#configuring-deployment[Deploying applications with Jetty] +Each service requires configuration to function properly. For details on configuring each service, refer to: -[[create-a-configuration-file]] -== Step 3. Create a configuration file - -Refer to the xref:configure-required-services.adoc[Configure] page for the details and come back here when you're done. - -[[pass-the-configuration-file-to-the-java-application-server]] -== Step 4. Pass the configuration file to the Java application server +* For Spellchecking and Autocorrect services, see the Configuration section in xref:individual-spelling-container.adoc[Deploy the Spelling server-side component using Docker] +* For Image Editing service, see the Configuration section in xref:individual-image-proxy-container.adoc[Deploy the Image Proxy server-side component using Docker] +* For Enhanced Media Embed and Link Checker services, see the Configuration section in xref:individual-hyperlinking-container.adoc[Deploy the Hyperlinking server-side component using Docker] [IMPORTANT] .HTTP proxy ==== -If you are relying on an HTTP proxy for outgoing HTTP/HTTPS connections to the Internet, consider configuring use of the proxy by the application server by setting JVM system properties at this point. These can be set in the same manner as `+ephox.config.file+` using the instructions below (using the `+-D+` option to the `+java+` command). Please refer to http://docs.oracle.com/javase/8/docs/api/java/net/doc-files/net-properties.html[Networking Properties for Java] for details on the relevant proxy system properties. The system properties `+http.proxyHost+`, `+http.proxyPort+`, `+http.nonProxyHosts+`, `+https.proxyHost+`, `+https.proxyPort+` are recognized as well as `+http.proxyUser+` and `+http.proxyPassword+` to support authenticating proxies. Alternatively, use of a proxy for server-side components can be set directly in their configuration file as discussed on the xref:configure-common-settings-services.adoc#proxy[Configure] page. +If you are relying on an HTTP proxy for outgoing HTTP/HTTPS connections to the Internet, the proxy configuration can be set directly in the Docker container configuration as discussed in the documentation for each service. ==== -Tell the services about the configuration file by setting the `+ephox.config.file+` JVM system property to the absolute path of the configuration file. The exact method for doing this varies depending on your operating system, application server and whether the application server is being run as a system service. The authoritative reference for configuring any application server is the vendor documentation, but we'll do our best to get you started below. - -=== Windows - -All Windows examples will assume the name of your configuration file is `+application.conf+` and it is located in the directory `+C:\config\file\location\+`. You'll need to set the JVM system property `+-Dephox.config.file=C:\config\file\location\application.conf+`. - -==== Tomcat - -===== From the command line - -The following assumes you've downloaded the Tomcat 9.0 zip archive from the Tomcat website, unpacked it and you're working from the unpacked Tomcat directory. - -Create or edit the script `+.\bin\setenv.bat+` to contain the following line: - -[source,bat] ----- -set "CATALINA_OPTS= -Dephox.config.file=C:\config\file\location\application.conf" ----- - -There should only be a single line in this file defining the `+CATALINA_OPTS+` environment variable. - -You may also need to add another line with the path to your Java Runtime Environment installation (replace with the actual path on your system) such as: - -[source,bat] ----- -set "JRE_HOME=C:\Program Files\Java\jre1.8.0_131" ----- - -After editing `+setenv.bat+`, run the following command to start Tomcat: - -[source,sh] ----- -.\bin\startup.bat ----- - -For further information see the documentation on https://tomcat.apache.org/tomcat-9.0-doc/RUNNING.txt[running Tomcat 9.0]. - -===== As a Windows service - -If you download the Windows installer, Tomcat 9.0 will always be installed as a Windows system service. See the notes on https://tomcat.apache.org/tomcat-9.0-doc/setup.html#Windows[Windows setup] for Tomcat 9.0 and the instructions for setting JVM system properties in the https://tomcat.apache.org/tomcat-9.0-doc/windows-service-howto.html[Tomcat 9.0 Windows Service HOW-TO]. - -As a minimal example, if the installer installed Tomcat to `+C:\Program Files\Apache Software Foundation\Tomcat 9.0\+` (default option): - -* Run `+C:\Program Files\Apache Software Foundation\Tomcat 9.0\bin\Tomcat9w+` which opens the *Apache Tomcat 9.0 Tomcat9 Properties* dialog box -* Select the `+Java+` tab -* Add the following line to `+Java Options+`: -+ -[source] ----- --Dephox.config.file=C:\config\file\location\application.conf ----- - -For other versions of Tomcat on Windows, check the Tomcat documentation for that version. - -==== Jetty - -===== From the command line - -If you're following the instructions for https://www.eclipse.org/jetty/documentation/current/#quickstart-running-jetty[Starting Jetty] for Jetty 9.4.5, the path to the configuration file can simply be supplied as a command option: - -[source,sh] ----- -java -D"ephox.config.file=C:\config\file\location\application.conf" -jar C:\jetty\install\directory\start.jar ----- - -For other versions of Jetty on Windows, check the Jetty documentation for that version. - -===== As a Windows service - -Follow the instructions in https://www.eclipse.org/jetty/documentation/current/#startup-windows-service[Startup via Windows Service] for Jetty 9.4.5. Remember to append the following snippet to the line beginning with `+set PR_JVMOPTIONS+` in your `+install-jetty-service.bat+` script: - -[source,bat] ----- -;-Dephox.config.file="C:\config\file\location\application.conf" ----- - -NOTE: Check the `+install-jetty-service.bat+` has the correct paths to your Java installation. The service will fail to start with some rather unhelpful errors if the paths are incorrect. - -For other versions of Jetty on Windows, check the Jetty documentation for that version. - -=== Linux - -All Linux examples will assume the name of your configuration file is `+application.conf+` and it is located in the directory `+/config/file/location/+`. You'll need to set the JVM system property `+-Dephox.config.file=/config/file/location/application.conf+`. - -NOTE: If the path to your `+application.conf+` file has spaces in it, you must ensure you prefix each white space with an escape character (\). Example: `+-Dephox.config.file=/config/file/location/with/white\ space/application.conf+` - -Tomcat and/or Jetty can be obtained via the package manager for many Linux distributions. The commands for starting the service and the location of the configuration files will vary across distributions. If you installed an application server via the package manager, follow your distribution's documentation for configuring it. - -==== Tomcat - -The following assumes you've downloaded Tomcat 9.0 from the Tomcat website and unpacked the archive to `+/opt/tomcat+`. - -For other versions of Tomcat on Linux, check the Tomcat documentation for that version. - -If you've obtained Tomcat from your distribution's package manager, refer to your distribution's documentation for Tomcat. - -===== From the command line - -Create or edit the script `+/opt/tomcat/bin/setenv.sh+` to contain the following line: - -[source,sh] ----- -CATALINA_OPTS=" -Dephox.config.file=/config/file/location/application.conf" ----- - -There should only be a single line in this file defining the `+CATALINA_OPTS+` environment variable. - -After editing `+setenv.sh+`, run the following command to start Tomcat: - -[source,sh] ----- -/opt/tomcat/bin/startup.sh ----- - -For further information see the documentation on https://tomcat.apache.org/tomcat-9.0-doc/RUNNING.txt[running Tomcat 9.0]. - -==== Jetty - -The following assumes you've downloaded Jetty 9.4.5 from the Jetty website and unpacked the archive to `+/opt/jetty+`. - -For other versions of Jetty on Linux, check the Jetty documentation for that version. - -If you've obtained Jetty from your distribution's package manager, refer to your distribution's documentation for Jetty. - -===== From the command line - -The path to the configuration file can simply be supplied as a command option: - -[source,sh] ----- -java -Dephox.config.file="/config/file/location/application.conf" -jar /opt/jetty/start.jar ----- - -===== As a Linux service - -Assuming you've followed the instructions to https://www.eclipse.org/jetty/documentation/current/#startup-unix-service[Startup a Unix Service using jetty.sh] for Jetty 9.4.5, edit `+/etc/default/jetty+` and add the line: - -[source] ----- -JETTY_ARGS=" -Dephox.config.file=/config/file/location/application.conf" ----- - -There should only be a single line in this file defining the `+JETTY_ARGS+` variable. - -[[restart-the-java-application-server]] -== Step 5: Restart the Java application server - -After you've completed the steps on this page to xref:deploy-server-side-components[Deploy server-side components], xref:create-a-configuration-file[Create a configuration file] and xref:pass-the-configuration-file-to-the-java-application-server[Pass the configuration file to the Java application server], the application server may need to be restarted to pick up all your changes. Turn it off and on again now, just to be safe. - [[set-up-editor-client-instances-to-use-the-server-side-functionality]] -== Step 6: Set up editor client instances to use the server-side functionality +== Set up editor client instances to use the server-side functionality -Now that the server-side components deployed and running, you'll need to tell your {productname} instances where to find them: +Once you have the Docker containers deployed and running, you'll need to tell your {productname} instances where to find them: -* Set the {productname} `+spellchecker_rpc_url+` configuration property to the URL of the deployed server-side spelling component. -* Set the {productname} `+editimage_proxy_service_url+` and `+export_image_proxy_service_url+` configuration properties to the URL of the deployed server-side image proxy component. -* Set the {productname} `+mediaembed_service_url+` and `+linkchecker_service_url+` configuration properties to the URL of the deployed server-side linkchecker and media embed component. +* Set the {productname} `+spellchecker_rpc_url+` and `+autocorrect_service_url+` configuration properties to the URL where the spelling service is running +* Set the {productname} `+editimage_proxy_service_url+` and `+export_image_proxy_service_url+` configuration properties to the URL where the image proxy service is running +* Set the {productname} `+mediaembed_service_url+` and `+linkchecker_service_url+` configuration properties to the URL where the hyperlinking service is running -This example assume your Java application server is running on port 80 (http) on `+yourserver.example.com+` and that all the server-side components are deployed to the same Java application server. Replace `+yourserver.example.com+` with the actual domain name or IP address of your server. +For example, if your services are exposed as follows: +- Spelling service on port 18080 +- Image proxy service on port 19040 +- Hyperlinking service on port 19100 Example of {productname} client configuration: @@ -233,11 +76,11 @@ tinymce.init({ selector: 'textarea', // change this value according to your HTML toolbar: 'image', plugins: 'tinymcespellchecker image editimage media mediaembed', - spellchecker_rpc_url: 'http://yourserver.example.com/ephox-spelling/', - autocorrect_service_url: 'http://yourserver.example.com/ephox-spelling/', - editimage_proxy_service_url: 'http://yourserver.example.com/ephox-image-proxy/', - export_image_proxy_service_url: 'http://yourserver.example.com/ephox-image-proxy/', - mediaembed_service_url: 'http://yourserver.example.com/ephox-hyperlinking/', - linkchecker_service_url: 'http://yourserver.example.com/ephox-hyperlinking/' + spellchecker_rpc_url: 'http://yourserver.example.com:18080', + autocorrect_service_url: 'http://yourserver.example.com:18080', + editimage_proxy_service_url: 'http://yourserver.example.com:19040', + export_image_proxy_service_url: 'http://yourserver.example.com:19040', + mediaembed_service_url: 'http://yourserver.example.com:19100', + linkchecker_service_url: 'http://yourserver.example.com:19100' }); ---- diff --git a/modules/ROOT/pages/introduction-to-tiny-spellchecker.adoc b/modules/ROOT/pages/introduction-to-tiny-spellchecker.adoc index c81e00a4bf..570c7498fd 100644 --- a/modules/ROOT/pages/introduction-to-tiny-spellchecker.adoc +++ b/modules/ROOT/pages/introduction-to-tiny-spellchecker.adoc @@ -37,7 +37,7 @@ tinymce.init({ To enable the {productname} Enterprise Spellchecking plugin, add `+tinymcespellchecker+` to the `+plugins+` list. -For information on installing the server-side component for spell checking, please see the xref:introduction-to-premium-selfhosted-services.adoc[server-side component installation guide]. +For information on installing the server-side component for spell checking, please see the xref:individual-spelling-container.adoc[Deploy the {productname} spelling service server-side component using Docker]. === Example: TinyMCE Self-hosted Installation diff --git a/modules/ROOT/pages/mediaembed-server-config.adoc b/modules/ROOT/pages/mediaembed-server-config.adoc index 8098f3b665..34b0da8f54 100644 --- a/modules/ROOT/pages/mediaembed-server-config.adoc +++ b/modules/ROOT/pages/mediaembed-server-config.adoc @@ -2,7 +2,7 @@ :description: Instructions for getting the Enhanced Media Embed server configured. :keywords: enterprise, pricing, video, youtube, vimeo, mp3, mp4, mov, movie, clip, film, link, linkchecking, linkchecker, mediaembed, media -Once you have the xref:introduction-to-premium-selfhosted-services.adoc[server-side component] installed, additional configuration to your `+application.conf+` file is required. (Don't forget to restart the Java application server after updating the configuration.) +Once you have the xref:individual-hyperlinking-container.adoc[Deploy the {productname} hyperlinking server-side component using Docker] installed, additional configuration to your `+application.conf+` file is required. (Don't forget to restart the Docker container after updating the configuration.) The Enhanced Media Embed service allows you to choose between using your own https://iframely.com/[Iframely] account, configuring custom http://oembed.com/[oEmbed] endpoints or using a combination of both. diff --git a/modules/ROOT/pages/support.adoc b/modules/ROOT/pages/support.adoc index e6c5e79206..703cf90be1 100644 --- a/modules/ROOT/pages/support.adoc +++ b/modules/ROOT/pages/support.adoc @@ -32,16 +32,27 @@ include::partial$misc/plugin-support-table.adoc[leveloffset=+1] include::partial$misc/support-powerpaste.adoc[leveloffset=+1] -=== Supported Application Servers: Self-hosted Enterprise +=== System Requirements: Self-hosted Enterprise -The {productname} spell checking server-side component requires a Java Web Application Server that supports Servlet Implementation API 3.0. +The {productname} server-side components are delivered as Docker containers. The following requirements must be met: -Java Development Kit:: -* JDK 8 +Docker Requirements:: +* Docker Engine +* Docker Compose -Java (J2EE) Application Servers:: -include::partial$misc/supported-application-servers.adoc[] - -Minimum Hardware Requirements:: -* CPU: Dual Core Processor ~ 2Ghz. For higher loads, a quad core or higher is recommended. +Host System Requirements:: +* Operating System: +** Linux +** macOS +** Windows with WSL 2 +* CPU: Dual Core Processor ~ 2Ghz. For higher loads, a quad core or higher is recommended * RAM: 4 Gigabytes of RAM available for services +* Storage: At least 10GB of free disk space for container images and data + +Container Platform Support:: +* Docker standalone +* Container orchestration platforms (such as Kubernetes) +* Cloud container services + +[NOTE] +For production deployments, we recommend using container orchestration platforms or cloud container services that provide built-in scaling and monitoring capabilities. diff --git a/modules/ROOT/pages/troubleshoot-server.adoc b/modules/ROOT/pages/troubleshoot-server.adoc index 973197b1d9..81fc806924 100644 --- a/modules/ROOT/pages/troubleshoot-server.adoc +++ b/modules/ROOT/pages/troubleshoot-server.adoc @@ -4,17 +4,21 @@ == General troubleshooting advice -. Verify that that your JavaScript configuration is correct for the relevant {productname} plugin. -. Ensure that your firewall has the appropriate ports and rules configured correctly. Be sure that the server the service is running on is accessible from the browser via the port specified in the server configuration -. Check the logs of your Java server for information. When making changes to the configuration you will need to restart the application server each time a change is made for that change to take effect. Refresh your browser window and then try the service again. +. Verify that your JavaScript configuration is correct for the relevant {productname} plugin. +. Ensure that your firewall has the appropriate ports and rules configured correctly. Be sure Docker containers are accessible from the browser via the port specified in the container configuration. +. Check the Docker container logs for information using `docker logs `. When making configuration changes, you will need to restart the containers for changes to take effect. Refresh your browser window and try the service again. == Debug server configuration If a service does not appear to be working, this is generally caused by one of the following reasons. This guide will walk you through the debugging process to identify the specific problem and how to remedy the issue. -. The `+application.conf+` file is incorrect. Please go back and follow the steps listed in the xref:introduction-to-premium-selfhosted-services.adoc#create-a-configuration-file[installation guide]. This is the most common problem - often the origins are specified without the port numbers and this can cause things to fail, eg: use `+http://localhost:8080+` instead of `+http://localhost+`. After making changes to the `+application.conf+` file, please restart your Java web server (e.g. Jetty or Tomcat). -. The `+application.conf+` file is correct, but something is wrong with one of the services. See the section below to debug the services. -. The `+application.conf+` file is correct, and the services are working, but the server-side component URLs that the editor uses are not quite right. Refer to the xref:introduction-to-tiny-spellchecker.adoc[Spell Checker], xref:editimage.adoc[Image Editing], xref:introduction-to-mediaembed.adoc[Enhanced Media Embed] and xref:linkchecker.adoc[Link Checker] plugin pages for help. +. The `+application.conf+` configuration file is incorrect. Please go back and follow the steps listed in the individual service setup guides: +* xref:individual-spelling-container.adoc[Spelling service configuration] +* xref:individual-image-proxy-container.adoc[Image Proxy service configuration] +* xref:individual-hyperlinking-container.adoc[Hyperlinking service configuration] +This is most commonly due to incorrect origin configuration - make sure to include port numbers (e.g., use `+http://localhost:8080+` instead of `+http://localhost+`). After making configuration changes, restart the Docker containers. +. The configuration is correct, but one of the services is not responding properly. See the section below to debug the services. +. The services are working, but the component URLs that the editor uses are not quite right. Refer to the xref:introduction-to-tiny-spellchecker.adoc[Spell Checker], xref:editimage.adoc[Image Editing], xref:introduction-to-mediaembed.adoc[Enhanced Media Embed] and xref:linkchecker.adoc[Link Checker] plugin pages for help. . The browser is sending a different origin than expected (and configured in `+application.conf+`). Refer to step 6 of xref:using-browser-tooling-to-investigate-services-issues[Using browser tooling to investigate services issues] == Browser-specific issues @@ -42,73 +46,46 @@ If the server is not running on a standard HTTP or HTTPS port (80 or 443) then C image::spell-checking-browser-tools.png[Using browser tools to investigate services issues] -NOTE: The value of the Origin header sent by the must match the origin specified in the `+application.conf+` server configuration. If it does not match, you must make the server configuration match the browser. +NOTE: The value of the Origin header sent by the browser must match the origin specified in the `+application.conf+` for your Docker container configuration. If it does not match, you must update your container configuration to match the browser. == Windows Server specific issues Sometimes the Origin header is never sent to the services, which results in the editor and services not working as intended. Refer to step 6 of xref:using-browser-tooling-to-investigate-services-issues[Using browser tooling to investigate services issues] and determine what the origin is - if you do not see an Origin header at all, please do the following: . Try accessing the editor web page using your machine's fully qualified domain name (FQDN) and keep the network tools open so you can see if the Origin header is sent back to the services. For example, if you have been testing on port 8080 on your local machine and the editor is instantiated on a page with path `+tinymce/index.html+`, navigate to `+http://myserver.example.com:8080/tinymce/index.html+` rather than `+http://localhost:8080/tinymce/index.html+`. -. If you now see an Origin header being sent across, alter your `+application.conf+` and replace all instances of 'localhost' with the domain name of your machine. -. Restart the Tomcat / Jetty service. +. If you now see an Origin header being sent across, update your Docker container `+application.conf+` to replace all instances of 'localhost' with the domain name of your machine. +. Restart the Docker containers. . Reload the browser page and all should work well. -[[out-of-memory-errors]] -== Out of memory errors +[[container-troubleshooting]] +== Container Troubleshooting -=== The Java application server throws "Out of Memory" errors +=== Debugging Service Issues -Even though you may have a large amount of RAM available, the Java Virtual Machine doesn't get to see all of that - by default it is limited to only 256Mb. +If you encounter issues with the containerized services: -For example, if you are using Tomcat, you can view how much memory is being consumed by apps. To do this you need to have the management console enabled. - -On a vanilla install this is done by editing the file /tomcat/install/directory/conf/tomcat-users.xml adding these lines in: - -[source,xml] +. Check the container status: ++ +[source,sh] ---- - - +docker ps ---- -Then, restart the server and go to a browser and open the default tomcat page `+http://localhost:8080+`. On the top right hand side are three buttons, the first of which should be "Server Status". Click that link, login with the details you set above and you should be able to see the memory consumption (see the figure below for an example). - -image::spell-checking-server-status.png[Spell Checking Server Status] - -=== To increase the amount of memory - -==== Tomcat - -Edit the setenv.sh (Unix) or setenv.bat (Windows) to read as follows: - -On Windows, please prefix each line with 'set' and remove the quotes . So the configuration would look like: - +. View service logs for errors or warnings: ++ [source,sh] ---- -set CATALINA_OPTS= -Dephox.config.file=/config/file/location/application.conf -set JAVA_OPTS= -Xms2048m -Xmx2048m -XX:PermSize=64m -XX:MaxPermSize=512m -Dfile.encoding=utf-8 -Djava.awt.headless=true -XX:+UseParallelGC -XX:MaxGCPauseMillis=100 - -CATALINA_OPTS=" -Dephox.config.file=/config/file/location/application.conf" -JAVA_OPTS=" -Xms2048m -Xmx2048m -XX:PermSize=64m -XX:MaxPermSize=512m -Dfile.encoding=utf-8 -Djava.awt.headless=true -XX:+UseParallelGC -XX:MaxGCPauseMillis=100" +docker logs ---- -==== Jetty - -Edit the start.ini file to read as follows: - +. For persistent issues, collect logs for support: ++ [source,sh] ---- -#=========================================================== -# Jetty start.jar arguments -# Each line of this file is prepended to the command line -# arguments # of a call to: -# java -jar start.jar [arg...] -#=========================================================== --Xms2048m -Xmx2048m -XX:PermSize=64m -XX:MaxPermSize=512m -Dephox.config.file=/config/file/location/application.conf +docker logs > service-logs.txt ---- -Restart the service and confirm the settings have been applied like so: - -image::spell-checking-jetty-settings.png[Spell Checking Server Settings on Jetty] +TIP: When contacting support, include the service logs and details about your deployment configuration to help diagnose the issue. == Troubleshooting tools: curl diff --git a/modules/ROOT/partials/configuration/autocorrect_service_url.adoc b/modules/ROOT/partials/configuration/autocorrect_service_url.adoc index 3af2c91102..bf730be43f 100644 --- a/modules/ROOT/partials/configuration/autocorrect_service_url.adoc +++ b/modules/ROOT/partials/configuration/autocorrect_service_url.adoc @@ -3,7 +3,7 @@ This option specifies the URL of the server-side `+ephox-spelling+` service. -For instructions on how to set up a Spellchecking server-side component, see: the xref:introduction-to-premium-selfhosted-services.adoc[server-side component installation guide]. +For instructions on how to set up a Spellchecking server-side component, see: the xref:individual-spelling-container.adoc[Deploy the {productname} spelling service server-side component using Docker]. NOTE: `autocorrect_service_url` is *not* required when enabling this plugin via xref:editor-and-features.adoc[{cloudname}]. @@ -17,4 +17,4 @@ tinymce.init({ selector: 'textarea', // change this value according to your HTML autocorrect_service_url: 'http://example.com/ephox-spelling/' }); ----- \ No newline at end of file +---- diff --git a/modules/ROOT/partials/configuration/image_proxy_service_url.adoc b/modules/ROOT/partials/configuration/image_proxy_service_url.adoc index 6787a6c76d..6227d3dba5 100644 --- a/modules/ROOT/partials/configuration/image_proxy_service_url.adoc +++ b/modules/ROOT/partials/configuration/image_proxy_service_url.adoc @@ -11,7 +11,7 @@ endif::[] == `{proxy_setting_name}` -This option configures the URL to the server-side proxy service which allows remote images hosted on different domains to be retrieved by the {pluginname} plugin. If a proxy is not configured, then remote images may not be able to be {plugin_proxy_action}. Check the xref:introduction-to-premium-selfhosted-services.adoc[Install Server-side Components] guide for details on configuring the self-hosted Java proxy service. +This option configures the URL to the server-side proxy service which allows remote images hosted on different domains to be retrieved by the {pluginname} plugin. If a proxy is not configured, then remote images may not be able to be {plugin_proxy_action}. Check the xref:individual-image-proxy-container.adoc[Deploy the {productname} image proxy server-side component using Docker] guide for details on configuring the Docker container that you will get as a part of your link:{pricingpage}/[{enterpriseversion} subscription]. NOTE: `{proxy_setting_name}` is *not* required when enabling this plugin via xref:editor-and-features.adoc[{cloudname}]. diff --git a/modules/ROOT/partials/configuration/mediaembed_service_url.adoc b/modules/ROOT/partials/configuration/mediaembed_service_url.adoc index 6c448daa60..09b04dc09c 100644 --- a/modules/ROOT/partials/configuration/mediaembed_service_url.adoc +++ b/modules/ROOT/partials/configuration/mediaembed_service_url.adoc @@ -1,7 +1,7 @@ [[mediaembed_service_url]] == `+mediaembed_service_url+` -This option specifies the URL to the service that will handle your requests and return the embeddable snippets used by the *Media Embed* plugin. Please follow these xref:introduction-to-premium-selfhosted-services.adoc[instructions] to configure the *WAR* file that you will get as a part of your link:{pricingpage}/[{enterpriseversion} subscription]. This option is not required for xref:editor-and-features.adoc[{cloudname}]. +This option specifies the URL to the service that will handle your requests and return the embeddable snippets used by the *Media Embed* plugin. The service is available as a Docker container with your link:{pricingpage}/[{enterpriseversion} subscription]. For deployment instructions, see xref:individual-hyperlinking-container.adoc[Deploy the {productname} hyperlinking server-side component using Docker]. This option is not required for xref:editor-and-features.adoc[{cloudname}]. *Type:* `+String+` diff --git a/modules/ROOT/partials/configuration/spellchecker_rpc_url.adoc b/modules/ROOT/partials/configuration/spellchecker_rpc_url.adoc index a64ba2f882..bd29189f79 100644 --- a/modules/ROOT/partials/configuration/spellchecker_rpc_url.adoc +++ b/modules/ROOT/partials/configuration/spellchecker_rpc_url.adoc @@ -1,7 +1,7 @@ [[spellchecker_rpc_url]] == `+spellchecker_rpc_url+` -This option specifies the URL of the server-side `+ephox-spelling+` service. For instructions on how to set up a Spell Checker server-side component, see: the xref:introduction-to-premium-selfhosted-services.adoc[server-side component installation guide]. +This option specifies the URL of the server-side `+ephox-spelling+` service. For instructions on how to set up a Spell Checker server-side component, see: the xref:individual-spelling-container.adoc[Deploy the {productname} spelling service server-side component using Docker]. NOTE: `+spellchecker_rpc_url+` is *not* required when enabling this plugin via xref:editor-and-features.adoc[{cloudname}] @@ -16,4 +16,4 @@ tinymce.init({ plugins: 'tinymcespellchecker', spellchecker_rpc_url: 'localhost/ephox-spelling' }); ----- +---- \ No newline at end of file diff --git a/modules/ROOT/partials/docker/common/docker-configuration.adoc b/modules/ROOT/partials/docker/common/docker-configuration.adoc new file mode 100644 index 0000000000..dbe94a175b --- /dev/null +++ b/modules/ROOT/partials/docker/common/docker-configuration.adoc @@ -0,0 +1,12 @@ +=== Specify Configurations + +After completing the previous steps, run the Docker container from the pulled image: + +[source, sh, subs="attributes+"] +---- +docker run -p {service-port}:{service-port} registry.containers.tiny.cloud/{service-name}: +---- + +This triggers `-p {service-port}:{service-port}`, exposing the service on `localhost:{service-port}`. The service runs on port `{service-port}` inside the Docker container, and this maps it to the same port on your localhost. + +If set up correctly, the logs should display output similar to the following: diff --git a/modules/ROOT/partials/docker/common/docker-image-retrieval.adoc b/modules/ROOT/partials/docker/common/docker-image-retrieval.adoc new file mode 100644 index 0000000000..9a2020acad --- /dev/null +++ b/modules/ROOT/partials/docker/common/docker-image-retrieval.adoc @@ -0,0 +1,21 @@ +=== Retrieve Docker Image + +include::partial$misc/admon-docker-access.adoc[] + +. Login into the {companyname} Cloud Docker Registry: ++ +[source, sh, subs="attributes+"] +---- +docker login -u tiny -p [access-token] registry.containers.tiny.cloud +---- + +. Pull the Docker Image from the Docker registry: ++ +[source, sh, subs="attributes+"] +---- +docker pull registry.containers.tiny.cloud/{service-name}: +---- ++ +Replace `` with `latest` or the specific version number. + +include::partial$misc/admon-available-docker-images.adoc[] diff --git a/modules/ROOT/partials/docker/common/docker-requirements.adoc b/modules/ROOT/partials/docker/common/docker-requirements.adoc new file mode 100644 index 0000000000..1483b3c163 --- /dev/null +++ b/modules/ROOT/partials/docker/common/docker-requirements.adoc @@ -0,0 +1,8 @@ +[[requirements]] +== Requirements + +* The link:https://docs.docker.com/engine/docker-overview/[Docker Engine^] is installed and running. +* The user has Administrative or Root user access to run the Docker commands. +* The user is either: +** Using a Unix-like operating system, such as Linux or macOS. +** Using Windows and has access to unix command line tools using link:https://gitforwindows.org/[Git for Windows^], link:https://www.cygwin.com/[Cygwin^], or the link:https://docs.microsoft.com/en-us/windows/wsl/install-win10[Windows Subsystem for Linux^]. diff --git a/modules/ROOT/partials/docker/common/docker-service-configuration.adoc b/modules/ROOT/partials/docker/common/docker-service-configuration.adoc new file mode 100644 index 0000000000..14e2a10918 --- /dev/null +++ b/modules/ROOT/partials/docker/common/docker-service-configuration.adoc @@ -0,0 +1,98 @@ +=== Configuring the Service + +Running this command will generate a log warning about `allowed-origins` not being configured. This is expected, as it will be set up in the next step. + +The {productname} server-side components require a configuration file to function correctly. By convention, this file is named `application.conf`. For more information, refer to link:https://www.tiny.cloud/docs/tinymce/latest/configure-required-services/[Required configuration for the server-side components]. + +This configuration file requires at least the following information: + +* `allowed-origins`: Specifies the domains allowed to communicate with server-side editor features. This is **mandatory** for all server-side components. + +=== Run with Docker Compose + +The Docker container can be run with `docker compose`. Here's an example directory structure: + +[source,sh] +---- +{service-type}-service/ +└── resources/ +└── application.conf +└── docker-compose.yaml +---- + +Here is an example `application.conf` file with basic configurations: + +[source, conf] +---- +ephox { + allowed-origins { + origins = [ + "", + " ", + "*.my.company.org" + ] + } +} +---- + +. Create the `docker-compose.yaml` file: + ++ +[source, yaml] +---- +services: + {service-name}: + image: registry.containers.tiny.cloud/{service-name}: + ports: + - "{service-port}:{service-port}" + restart: always + init: true + volumes: + - type: bind + source: ./application.conf + target: /ephox-{service-type}/ephox-{service-type}-docker-env.conf + read_only: true +---- + +. Run the service (within the same directory where `docker-compose.yaml` was placed): + ++ +[source, sh] +---- +docker compose up +---- + +=== Test the Service + +. Test via cURL command: + ++ +[source, sh] +---- +curl http://localhost:{service-port}/version +---- + +. Test the service with an allowed origin: + ++ +[source, sh] +---- +curl http://localhost:{service-port}/check -H "Origin: http://good.com" +---- + +. Test with an unauthorized origin: + ++ +[source, sh] +---- +curl http://localhost:{service-port}/check -H "Origin: http://bad.com" +---- + +If unauthorized, you should see: `{ "message": "The supplied authentication is not authorized to access this resource" }` + +=== Next Steps + +For detailed configuration options and integration with {productname}, refer to: + +* link:https://www.tiny.cloud/docs/tinymce/latest/configure-required-services/[Required configuration for the server-side components] +* The specific documentation for this service's {productname} plugin diff --git a/modules/ROOT/partials/misc/custom-dictionaries-path.adoc b/modules/ROOT/partials/misc/custom-dictionaries-path.adoc index c0197fa035..ff132a1e61 100644 --- a/modules/ROOT/partials/misc/custom-dictionaries-path.adoc +++ b/modules/ROOT/partials/misc/custom-dictionaries-path.adoc @@ -2,7 +2,7 @@ The `+ephox.spelling.custom-dictionaries-path+` element is used to define the lo Requirements: -* The directory containing the custom dictionaries must be on same server machine as the java service. +* The directory containing the custom dictionaries must be on the same server machine. * The directory should not contain subdirectories or non-dictionary files. {companyname} recommends storing the custom dictionaries in a similar location to the `+application.conf+` file. For example, if `+application.conf+` is in a directory called `+/opt/ephox+`, the dictionary files could be stored in the subdirectory `+/opt/ephox/dictionaries+`. diff --git a/modules/ROOT/partials/misc/hunspell-dictionaries-path.adoc b/modules/ROOT/partials/misc/hunspell-dictionaries-path.adoc index d335cf899a..33a0a73893 100644 --- a/modules/ROOT/partials/misc/hunspell-dictionaries-path.adoc +++ b/modules/ROOT/partials/misc/hunspell-dictionaries-path.adoc @@ -3,7 +3,7 @@ The `+ephox.spelling.hunspell-dictionaries-path+` setting is used to define the Requirements: * The directory containing the Hunspell dictionaries must conform to the file structure defined in xref:self-hosting-hunspell.adoc#hunspell-dictionary-storage-for-spell-checker[Hunspell dictionary storage for Spell Checker]. -* The directory containing the Hunspell dictionaries must be on the same server machine (or docker container) as the java service. +* The directory containing the Hunspell dictionaries must be on the same server machine. {companyname} recommends storing the Hunspell dictionaries in a similar location to the `+application.conf+` file. For example, if `+application.conf+` is in a directory called `+/opt/ephox+`, the Hunspell dictionaries should be stored in the subdirectory `+/opt/ephox/hunspell-dictionaries+`. diff --git a/modules/ROOT/partials/misc/supported-application-servers.adoc b/modules/ROOT/partials/misc/supported-application-servers.adoc index 1e8aa7c9cc..2267ed8991 100644 --- a/modules/ROOT/partials/misc/supported-application-servers.adoc +++ b/modules/ROOT/partials/misc/supported-application-servers.adoc @@ -1,14 +1,6 @@ -* Eclipse Jetty: -** 9.4+ (with extended support) -* WebSphere Application Server (WAS) 8 or later -* Apache Tomcat: -+ --- -** 10 (See note below) -** 9+ -** 8.5.12+ -** 8.0.42+ -** 7.0.76+ --- -+ -IMPORTANT: Tomcat 10 will require WAR files to be placed in the _webapp-javaee_ directory rather than the _webapps_ directory due to the change to Jakarta servlets. Jetty 11 is not currently supported due to this change. +* Docker Engine: +** 24.0 or later (latest stable version recommended) +* Docker Compose: +** 2.20.0 or later (latest stable version recommended) + +IMPORTANT: As of {productname} 8.0, server-side components are only supported via Docker containers. Java-based WAR file deployments have been deprecated and are no longer supported. From 3415a6da8f2ea340fa5e2cc028fc032af07b2d25 Mon Sep 17 00:00:00 2001 From: Karl Kemister-Sheppard Date: Fri, 13 Jun 2025 16:16:43 +1000 Subject: [PATCH 2/9] DOC-3231: Remove deprecated server-side component installation documentation duplication page. --- ...uction-to-premium-selfhosted-services.adoc | 86 ------------------- 1 file changed, 86 deletions(-) delete mode 100644 modules/ROOT/pages/introduction-to-premium-selfhosted-services.adoc diff --git a/modules/ROOT/pages/introduction-to-premium-selfhosted-services.adoc b/modules/ROOT/pages/introduction-to-premium-selfhosted-services.adoc deleted file mode 100644 index 79f5ed7482..0000000000 --- a/modules/ROOT/pages/introduction-to-premium-selfhosted-services.adoc +++ /dev/null @@ -1,86 +0,0 @@ -= Server-side component installation -:description: Server-side components for premium plugins like spelling as-you-type. -:keywords: enterprise, tinymcespellchecker, spell check, Spell Checker, editimage, server - -Some {productname} Enterprise features require server-side components. If you're using the {cloudname} solution, we've done all the hard work for you and you can skip this page. Alternatively, if you've purchased our Self-hosted solution then please read on. - -IMPORTANT: As of {productname} 8.0, server-side components are only supported using Docker containers. The older Java application server-based deployment (.war files) has been deprecated. - -The following server-side components are included in the {productname} Self-hosted package: - -[cols="<,<",options="header"] -|=== -|Component |Description -|xref:introduction-to-tiny-spellchecker.adoc[Spellchecking], xref:autocorrect.adoc[Spelling Autocorrect] |Spell checking and Autocorrect service for {productname} Enterprise -|xref:editimage.adoc[Image Editing] |Image proxy service for the Export and Image Editing plugins -|xref:introduction-to-mediaembed.adoc[Enhanced Media Embed], xref:linkchecker.adoc[Link Checker] |Link Checker and Enhanced Media Embed service for {productname} Enterprise -|=== - -NOTE: The configuration of xref:configure-required-services.adoc#allowed-origins[allowed origins] should be specified directly in the Docker container configuration file. - -[[deploy-server-side-components]] -== Deploying server-side components using Docker - -[IMPORTANT] -==== -A valid access token is required to access the {companyname} Cloud Docker registry and pull the Docker images. Contact link:https://www.tiny.cloud/contact/[{companyname} Support^] to request the access token. -==== - -=== Requirements - -* The link:https://docs.docker.com/engine/docker-overview/[Docker Engine^] is installed and running -* Administrative or Root user access to run Docker commands -* Either: -** A Unix-like operating system (Linux or macOS) -** Windows with Unix command line tools via link:https://gitforwindows.org/[Git for Windows^], link:https://www.cygwin.com/[Cygwin^], or link:https://docs.microsoft.com/en-us/windows/wsl/install-win10[Windows Subsystem for Linux^] - -For detailed requirements and setup instructions for each service, refer to: - -* For Spellchecking and Autocorrect services, see: xref:individual-spelling-container.adoc[Deploy the Spelling server-side component using Docker] -* For Image Editing service, see: xref:individual-image-proxy-container.adoc[Deploy the Image Proxy server-side component using Docker] -* For Enhanced Media Embed and Link Checker services, see: xref:individual-hyperlinking-container.adoc[Deploy the Hyperlinking server-side component using Docker] - -=== Configuration - -Each service requires configuration to function properly. For details on configuring each service, refer to: - -* For Spellchecking and Autocorrect services, see the Configuration section in xref:individual-spelling-container.adoc[Deploy the Spelling server-side component using Docker] -* For Image Editing service, see the Configuration section in xref:individual-image-proxy-container.adoc[Deploy the Image Proxy server-side component using Docker] -* For Enhanced Media Embed and Link Checker services, see the Configuration section in xref:individual-hyperlinking-container.adoc[Deploy the Hyperlinking server-side component using Docker] - -[IMPORTANT] -.HTTP proxy -==== -If you are relying on an HTTP proxy for outgoing HTTP/HTTPS connections to the Internet, the proxy configuration can be set directly in the Docker container configuration as discussed in the documentation for each service. -==== - -[[set-up-editor-client-instances-to-use-the-server-side-functionality]] -== Set up editor client instances to use the server-side functionality - -Once you have the Docker containers deployed and running, you'll need to tell your {productname} instances where to find them: - -* Set the {productname} `+spellchecker_rpc_url+` and `+autocorrect_service_url+` configuration properties to the URL where the spelling service is running -* Set the {productname} `+editimage_proxy_service_url+` and `+export_image_proxy_service_url+` configuration properties to the URL where the image proxy service is running -* Set the {productname} `+mediaembed_service_url+` and `+linkchecker_service_url+` configuration properties to the URL where the hyperlinking service is running - -For example, if your services are exposed as follows: -- Spelling service on port 18080 -- Image proxy service on port 19040 -- Hyperlinking service on port 19100 - -Example of {productname} client configuration: - -[source,js] ----- -tinymce.init({ - selector: 'textarea', // change this value according to your HTML - toolbar: 'image', - plugins: 'tinymcespellchecker image editimage media mediaembed', - spellchecker_rpc_url: 'http://yourserver.example.com:18080', - autocorrect_service_url: 'http://yourserver.example.com:18080', - editimage_proxy_service_url: 'http://yourserver.example.com:19040', - export_image_proxy_service_url: 'http://yourserver.example.com:19040', - mediaembed_service_url: 'http://yourserver.example.com:19100', - linkchecker_service_url: 'http://yourserver.example.com:19100' -}); ----- From a0d79736bb7e49305bec0dfb4bf797700f92a8a4 Mon Sep 17 00:00:00 2001 From: Karl Kemister-Sheppard Date: Fri, 13 Jun 2025 16:28:00 +1000 Subject: [PATCH 3/9] File cleanup, removal of files not used during copy edits. --- .../docker/common/docker-configuration.adoc | 12 --- .../docker/common/docker-image-retrieval.adoc | 21 ---- .../docker/common/docker-requirements.adoc | 8 -- .../common/docker-service-configuration.adoc | 98 ------------------- 4 files changed, 139 deletions(-) delete mode 100644 modules/ROOT/partials/docker/common/docker-configuration.adoc delete mode 100644 modules/ROOT/partials/docker/common/docker-image-retrieval.adoc delete mode 100644 modules/ROOT/partials/docker/common/docker-requirements.adoc delete mode 100644 modules/ROOT/partials/docker/common/docker-service-configuration.adoc diff --git a/modules/ROOT/partials/docker/common/docker-configuration.adoc b/modules/ROOT/partials/docker/common/docker-configuration.adoc deleted file mode 100644 index dbe94a175b..0000000000 --- a/modules/ROOT/partials/docker/common/docker-configuration.adoc +++ /dev/null @@ -1,12 +0,0 @@ -=== Specify Configurations - -After completing the previous steps, run the Docker container from the pulled image: - -[source, sh, subs="attributes+"] ----- -docker run -p {service-port}:{service-port} registry.containers.tiny.cloud/{service-name}: ----- - -This triggers `-p {service-port}:{service-port}`, exposing the service on `localhost:{service-port}`. The service runs on port `{service-port}` inside the Docker container, and this maps it to the same port on your localhost. - -If set up correctly, the logs should display output similar to the following: diff --git a/modules/ROOT/partials/docker/common/docker-image-retrieval.adoc b/modules/ROOT/partials/docker/common/docker-image-retrieval.adoc deleted file mode 100644 index 9a2020acad..0000000000 --- a/modules/ROOT/partials/docker/common/docker-image-retrieval.adoc +++ /dev/null @@ -1,21 +0,0 @@ -=== Retrieve Docker Image - -include::partial$misc/admon-docker-access.adoc[] - -. Login into the {companyname} Cloud Docker Registry: -+ -[source, sh, subs="attributes+"] ----- -docker login -u tiny -p [access-token] registry.containers.tiny.cloud ----- - -. Pull the Docker Image from the Docker registry: -+ -[source, sh, subs="attributes+"] ----- -docker pull registry.containers.tiny.cloud/{service-name}: ----- -+ -Replace `` with `latest` or the specific version number. - -include::partial$misc/admon-available-docker-images.adoc[] diff --git a/modules/ROOT/partials/docker/common/docker-requirements.adoc b/modules/ROOT/partials/docker/common/docker-requirements.adoc deleted file mode 100644 index 1483b3c163..0000000000 --- a/modules/ROOT/partials/docker/common/docker-requirements.adoc +++ /dev/null @@ -1,8 +0,0 @@ -[[requirements]] -== Requirements - -* The link:https://docs.docker.com/engine/docker-overview/[Docker Engine^] is installed and running. -* The user has Administrative or Root user access to run the Docker commands. -* The user is either: -** Using a Unix-like operating system, such as Linux or macOS. -** Using Windows and has access to unix command line tools using link:https://gitforwindows.org/[Git for Windows^], link:https://www.cygwin.com/[Cygwin^], or the link:https://docs.microsoft.com/en-us/windows/wsl/install-win10[Windows Subsystem for Linux^]. diff --git a/modules/ROOT/partials/docker/common/docker-service-configuration.adoc b/modules/ROOT/partials/docker/common/docker-service-configuration.adoc deleted file mode 100644 index 14e2a10918..0000000000 --- a/modules/ROOT/partials/docker/common/docker-service-configuration.adoc +++ /dev/null @@ -1,98 +0,0 @@ -=== Configuring the Service - -Running this command will generate a log warning about `allowed-origins` not being configured. This is expected, as it will be set up in the next step. - -The {productname} server-side components require a configuration file to function correctly. By convention, this file is named `application.conf`. For more information, refer to link:https://www.tiny.cloud/docs/tinymce/latest/configure-required-services/[Required configuration for the server-side components]. - -This configuration file requires at least the following information: - -* `allowed-origins`: Specifies the domains allowed to communicate with server-side editor features. This is **mandatory** for all server-side components. - -=== Run with Docker Compose - -The Docker container can be run with `docker compose`. Here's an example directory structure: - -[source,sh] ----- -{service-type}-service/ -└── resources/ -└── application.conf -└── docker-compose.yaml ----- - -Here is an example `application.conf` file with basic configurations: - -[source, conf] ----- -ephox { - allowed-origins { - origins = [ - "", - " ", - "*.my.company.org" - ] - } -} ----- - -. Create the `docker-compose.yaml` file: - -+ -[source, yaml] ----- -services: - {service-name}: - image: registry.containers.tiny.cloud/{service-name}: - ports: - - "{service-port}:{service-port}" - restart: always - init: true - volumes: - - type: bind - source: ./application.conf - target: /ephox-{service-type}/ephox-{service-type}-docker-env.conf - read_only: true ----- - -. Run the service (within the same directory where `docker-compose.yaml` was placed): - -+ -[source, sh] ----- -docker compose up ----- - -=== Test the Service - -. Test via cURL command: - -+ -[source, sh] ----- -curl http://localhost:{service-port}/version ----- - -. Test the service with an allowed origin: - -+ -[source, sh] ----- -curl http://localhost:{service-port}/check -H "Origin: http://good.com" ----- - -. Test with an unauthorized origin: - -+ -[source, sh] ----- -curl http://localhost:{service-port}/check -H "Origin: http://bad.com" ----- - -If unauthorized, you should see: `{ "message": "The supplied authentication is not authorized to access this resource" }` - -=== Next Steps - -For detailed configuration options and integration with {productname}, refer to: - -* link:https://www.tiny.cloud/docs/tinymce/latest/configure-required-services/[Required configuration for the server-side components] -* The specific documentation for this service's {productname} plugin From d3786b03b4f4b7b1ad0dc83f02bf10c4bfaeb364 Mon Sep 17 00:00:00 2001 From: Karl Kemister-Sheppard Date: Tue, 15 Jul 2025 10:46:03 +1000 Subject: [PATCH 4/9] Update modules/ROOT/partials/misc/custom-dictionaries-path.adoc Co-authored-by: Tim Dettrick --- modules/ROOT/partials/misc/custom-dictionaries-path.adoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/modules/ROOT/partials/misc/custom-dictionaries-path.adoc b/modules/ROOT/partials/misc/custom-dictionaries-path.adoc index ff132a1e61..83af6b5dae 100644 --- a/modules/ROOT/partials/misc/custom-dictionaries-path.adoc +++ b/modules/ROOT/partials/misc/custom-dictionaries-path.adoc @@ -2,7 +2,7 @@ The `+ephox.spelling.custom-dictionaries-path+` element is used to define the lo Requirements: -* The directory containing the custom dictionaries must be on the same server machine. +* The directory containing the custom dictionaries must be mounted as a volume in the container. * The directory should not contain subdirectories or non-dictionary files. {companyname} recommends storing the custom dictionaries in a similar location to the `+application.conf+` file. For example, if `+application.conf+` is in a directory called `+/opt/ephox+`, the dictionary files could be stored in the subdirectory `+/opt/ephox/dictionaries+`. From 59ed500124b0835febb158c73712d08630f18718 Mon Sep 17 00:00:00 2001 From: Karl Kemister-Sheppard Date: Tue, 15 Jul 2025 10:46:20 +1000 Subject: [PATCH 5/9] Update modules/ROOT/partials/misc/hunspell-dictionaries-path.adoc Co-authored-by: Tim Dettrick --- modules/ROOT/partials/misc/hunspell-dictionaries-path.adoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/modules/ROOT/partials/misc/hunspell-dictionaries-path.adoc b/modules/ROOT/partials/misc/hunspell-dictionaries-path.adoc index 33a0a73893..037c70c892 100644 --- a/modules/ROOT/partials/misc/hunspell-dictionaries-path.adoc +++ b/modules/ROOT/partials/misc/hunspell-dictionaries-path.adoc @@ -3,7 +3,7 @@ The `+ephox.spelling.hunspell-dictionaries-path+` setting is used to define the Requirements: * The directory containing the Hunspell dictionaries must conform to the file structure defined in xref:self-hosting-hunspell.adoc#hunspell-dictionary-storage-for-spell-checker[Hunspell dictionary storage for Spell Checker]. -* The directory containing the Hunspell dictionaries must be on the same server machine. +* The directory containing the Hunspell dictionaries must be mounted as a volume in the container. {companyname} recommends storing the Hunspell dictionaries in a similar location to the `+application.conf+` file. For example, if `+application.conf+` is in a directory called `+/opt/ephox+`, the Hunspell dictionaries should be stored in the subdirectory `+/opt/ephox/hunspell-dictionaries+`. From 2088aec5c5d3924abdd294e408f86b68908ddbd6 Mon Sep 17 00:00:00 2001 From: Karl Kemister-Sheppard Date: Tue, 15 Jul 2025 10:47:08 +1000 Subject: [PATCH 6/9] Update modules/ROOT/partials/misc/supported-application-servers.adoc Co-authored-by: Tim Dettrick --- modules/ROOT/partials/misc/supported-application-servers.adoc | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/modules/ROOT/partials/misc/supported-application-servers.adoc b/modules/ROOT/partials/misc/supported-application-servers.adoc index 2267ed8991..94d7d12d8a 100644 --- a/modules/ROOT/partials/misc/supported-application-servers.adoc +++ b/modules/ROOT/partials/misc/supported-application-servers.adoc @@ -1,6 +1,6 @@ * Docker Engine: ** 24.0 or later (latest stable version recommended) -* Docker Compose: -** 2.20.0 or later (latest stable version recommended) +* Kubernetes: +** 1.31.x or later (latest stable version recommended) IMPORTANT: As of {productname} 8.0, server-side components are only supported via Docker containers. Java-based WAR file deployments have been deprecated and are no longer supported. From bc2ee7435241eee88d2c8e85a36f035bb01acdf8 Mon Sep 17 00:00:00 2001 From: Karl Kemister-Sheppard Date: Tue, 15 Jul 2025 10:47:23 +1000 Subject: [PATCH 7/9] Update modules/ROOT/pages/support.adoc Co-authored-by: Tim Dettrick --- modules/ROOT/pages/support.adoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/modules/ROOT/pages/support.adoc b/modules/ROOT/pages/support.adoc index 703cf90be1..13ceaab87e 100644 --- a/modules/ROOT/pages/support.adoc +++ b/modules/ROOT/pages/support.adoc @@ -34,7 +34,7 @@ include::partial$misc/support-powerpaste.adoc[leveloffset=+1] === System Requirements: Self-hosted Enterprise -The {productname} server-side components are delivered as Docker containers. The following requirements must be met: +The {productname} server-side components are delivered as Docker/OCI container images. The following requirements must be met: Docker Requirements:: * Docker Engine From 11052e6fb97d4b087f51ca9a1c5a2f4354f61162 Mon Sep 17 00:00:00 2001 From: Karl Kemister-Sheppard Date: Tue, 15 Jul 2025 10:48:32 +1000 Subject: [PATCH 8/9] Update modules/ROOT/pages/support.adoc Co-authored-by: Tim Dettrick --- modules/ROOT/pages/support.adoc | 3 --- 1 file changed, 3 deletions(-) diff --git a/modules/ROOT/pages/support.adoc b/modules/ROOT/pages/support.adoc index 13ceaab87e..88b0b3631d 100644 --- a/modules/ROOT/pages/support.adoc +++ b/modules/ROOT/pages/support.adoc @@ -36,9 +36,6 @@ include::partial$misc/support-powerpaste.adoc[leveloffset=+1] The {productname} server-side components are delivered as Docker/OCI container images. The following requirements must be met: -Docker Requirements:: -* Docker Engine -* Docker Compose Host System Requirements:: * Operating System: From db8d107cea1615a28a1618091bef0c919e3a8daf Mon Sep 17 00:00:00 2001 From: Karl Kemister-Sheppard Date: Tue, 15 Jul 2025 10:50:07 +1000 Subject: [PATCH 9/9] Update modules/ROOT/partials/misc/supported-application-servers.adoc --- modules/ROOT/partials/misc/supported-application-servers.adoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/modules/ROOT/partials/misc/supported-application-servers.adoc b/modules/ROOT/partials/misc/supported-application-servers.adoc index 94d7d12d8a..9cbf13afa7 100644 --- a/modules/ROOT/partials/misc/supported-application-servers.adoc +++ b/modules/ROOT/partials/misc/supported-application-servers.adoc @@ -3,4 +3,4 @@ * Kubernetes: ** 1.31.x or later (latest stable version recommended) -IMPORTANT: As of {productname} 8.0, server-side components are only supported via Docker containers. Java-based WAR file deployments have been deprecated and are no longer supported. +IMPORTANT: As of {productname} {productmajorversion}, server-side components are only supported via Docker containers. Java-based WAR file deployments have been deprecated and are no longer supported.