DOC-3136: Update documentation for Spelling service using Docker (ind…

…ividually licensed)
tinymce · Feb 24, 2025 · 227d45c · 227d45c
1 parent 1b8c3de
commit 227d45c
Show file tree

Hide file tree

Showing 4 changed files with 265 additions and 3 deletions.
diff --git a/modules/ROOT/pages/individual-spelling-container.adoc b/modules/ROOT/pages/individual-spelling-container.adoc
@@ -1,6 +1,11 @@
-= Deploy the TinyMCE Spelling server-side component using Docker (individually licensed)
+= Deploy the {productname} Spelling server-side component using Docker (individually licensed)
 :navtitle: Spelling service
-:description: How-to deploy the TinyMCE Spelling server-side component using Docker (individually licensed).
+:description: How-to deploy the {productname} Spelling server-side component using Docker (individually licensed).
 :shbundledockerfiles: false
+:pluginname: Spell Checker
 
-include::partial$docker/dockerized-spelling-service.adoc[]
+include::partial$docker/spelling-service/spelling-service-overview.adoc[]
+
+include::partial$docker/spelling-service/spelling-service-requirements.adoc[]
+
+include::partial$docker/spelling-service/spelling-service-installation.adoc[]
diff --git a/modules/ROOT/partials/docker/spelling-service/spelling-service-installation.adoc b/modules/ROOT/partials/docker/spelling-service/spelling-service-installation.adoc
@@ -0,0 +1,239 @@
+[[installation]]
+== Installation
+
+[NOTE]
+A valid xref:license-key.adoc[License Key] is **required** in order to install {pluginname} On-Premises.
+link:https://www.tiny.cloud/contact/[Contact us] for a trial xref:license-key.adoc[License Key].
+
+=== Retrieve Docker Image
+
+. Login into the {companyname} Cloud Docker Registry: 
++
+[source, sh, subs="attributes+"]
+----
+docker login -u [username] -p [password] registry.containers.tiny.cloud
+----
+
+. Pull the Docker Image from the Docker registry:
++
+[source, sh, subs="attributes+"]
+----
+docker pull registry.containers.tiny.cloud/spelling-tiny:[version]
+----
++
+Replace `version` with `latest` or the specific version number.
+
+=== Specify Configurations 
+
+After completing the previous steps, run the Docker container from the pulled image: 
+
+[source, sh, subs="attributes+"]
+----
+docker run -p 18080:18080 registry.containers.tiny.cloud/spelling-tiny:[version]
+----
+
+This triggers `-p 18080:18080`, exposing the service on `localhost:18080`. The service runs on port `18080` 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: 
+
+[source, log]
+----
+2024-12-05 11:30:50.813Z [io-compute-9] INFO  ironbark - ironbark
+...
+2024-12-05 11:30:51.166Z [io-compute-blocker-9] INFO  ironbark - -> Raw Config assembled from various sources: ConfigOrigin(merge of /ephox-spelling/ephox-spelling-docker-env.conf: 1,system properties,reference.conf @ jar:file:/ephox-spelling/ephox-spelling.jar!/reference.conf: 1)
+2024-12-05 11:30:51.206Z [io-compute-blocker-9] WARN  c.e.d.config.AllowedOriginsConfig$ - No allowed-origins specified in config!
+2024-12-05 11:30:51.219Z [io-compute-blocker-9] INFO  ironbark - ironbark config loaded successfully: IronbarkConfig(Logger[ironbark],SpellingConfig(None,Some(200),None,false),OriginWhitelist(List(),OriginPrecision(true)),None,None,StaticCustomDictionaryScanConfig)
+2024-12-05 11:30:51.275Z [io-compute-blocker-9] INFO  com.ephox.nectar.data.Bees$ - Loading all dictionaries from WinterTree
+2024-12-05 11:30:51.677Z [io-compute-blocker-6] INFO  com.ephox.nectar.data.Bees$ - Loading all dictionaries from WinterTree
+2024-12-05 11:30:52.127Z [io-compute-7] INFO  o.h.b.c.nio1.NIO1SocketServerGroup - Service bound to address /0:0:0:0:0:0:0:0:18080
+2024-12-05 11:30:52.131Z [io-compute-7] INFO  o.h.blaze.server.BlazeServerBuilder - 
+  _   _   _        _ _
+ | |_| |_| |_ _ __| | | ___
+ | ' \\  _|  _| '_ \\_  _(_-<
+ |_||_\\__|\\__| .__/ |_|/__/
+             |_|
+2024-12-05 11:30:52.145Z [io-compute-7] INFO  o.h.blaze.server.BlazeServerBuilder - http4s v0.23.27 on blaze v0.23.16 started at http://[::]:18080/
+----
+
+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.
+
+By default, the {pluginname} plugin comes with Hunspell dictionaries for link:https://www.tiny.cloud/docs/tinymce/latest/introduction-to-tiny-spellchecker/#supported-languages[supported languages]. For additional configurations, the service supports the following options:
+
+==== Configure Custom Dictionaries 
+
+To add custom dictionaries, create a folder on your machine and add the dictionary files. The custom dictionaries must conform to specific rules described in link:https://www.tiny.cloud/docs/tinymce/latest/custom-dictionaries-for-tiny-spellchecker/#creating-custom-dictionary-files[Adding custom dictionaries]. In the `application.conf` file, the `spelling` setting can be configured with the following parameters: 
+
+* `custom-dictionaries-path`: Takes `<HOST_PATH_TO_CUSTOM_DICT_FOLDER>` as its value. Upon running the container, the specified folder is mapped to the target folder inside the container.
+* `dynamic-custom-dictionaries`: When set to true, the {pluginname} service periodically checks the dictionary files in `<HOST_PATH_TO_CUSTOM_DICT_FOLDER>` for changes and updates the custom dictionaries at runtime without requiring a service restart. Enabling this option introduces some performance overhead, which should be considered. The default value is `false`.
+
+==== Configure Extra Hunspell Dictionaries
+
+The default Hunspell dictionaries can also be replaced or extended. To do this, create a folder on your machine to store the Hunspell dictionary files. In the `application.conf` file, specify the following in the `spelling` setting:
+
+* `hunspell-dictionaries-path`: Takes `<HOST_PATH_TO_HUNSPELL_DICT_FOLDER>` as its value. Upon running the container, the specified folder is mapped to the target folder inside the container.
+
+This is an example `application.conf` file with the basic configurations: 
+
+[source, conf]
+----
+ephox {
+
+  allowed-origins {
+    origins = [
+      "<http://example.com>",
+      "<http://good.com> ",
+      "*.my.company.org"
+    ]
+  }
+  
+  spelling {
+    custom-dictionaries-path = "/app/resources/custom-dictionaries"
+    hunspell-dictionaries-path = "/app/resources/hunspell-dictionaries"
+  }
+}
+----
+
+=== Launch the Docker Container 
+
+Once the application configuration file is ready, proceed with the Docker Compose setup to configure and run the service.
+
+. Create the `docker-compose.yml` file:
+
++
+[source, yml]
+----
+services:
+  spelling-tiny:
+    image: registry.containers.tiny.cloud/spelling-tiny:<VERSION>
+    ports:
+      - "18080:18080"
+    restart: always
+    init: true
+    volumes:
+      - type: bind
+        source: <PATH_TO_APPLICATION_CONF_FILE_IN_HOST_MACHINE>
+        target: /ephox-spelling/ephox-spelling-docker-env.conf 
+        read_only: true
+      - type: bind
+        source: <HOST_PATH_TO_CUSTOM_DICT_FOLDER>
+        target: /app/resources/custom-dictionaries
+        read_only: true
+      - type: bind
+        source: <HOST_PATH_TO_HUNSPELL_DICT_FOLDER>
+        target: /app/resources/hunspell-dictionaries
+        read_only: true
+----
+
+. Run the service (within the same directory where docker-compose.yaml was placed):
+
++
+[source, sh]
+----
+docker compose up
+----
+
++
+If the allowed origins, Hunspell, and custom dictionaries folders are configured correctly, the initiation logs should appear as follows:
+
++
+[source, log]
+----
+[+] Running 2/2
+ ✔ Network spelling-tiny_default            Created                                                                                                                                                                                               0.0s 
+ ✔ Container spelling-tiny-spelling-tiny-1  Created                                                                                                                                                                                               0.1s 
+Attaching to spelling-tiny-1
+spelling-tiny-1  | 2025-02-11 09:51:10.332Z [io-compute-5] INFO  ironbark - ironbark
+...
+spelling-tiny-1  | 2025-02-11 09:51:10.736Z [io-compute-blocker-5] INFO  ironbark - -> Raw Config assembled from various sources: ConfigOrigin(merge of /ephox-spelling/ephox-spelling-docker-env.conf: 1,system properties,reference.conf @ jar:file:/ephox-spelling/ephox-spelling.jar!/reference.conf: 1)
+spelling-tiny-1  | 2025-02-11 09:51:10.814Z [io-compute-blocker-5] INFO  c.e.d.config.AllowedOriginsConfig$ - Read allowed-origins config (ignoring ports = true) as:
+spelling-tiny-1  |  - example.com
+spelling-tiny-1  |  - good.com
+spelling-tiny-1  |  - my.company.org
+spelling-tiny-1  | 2025-02-11 09:51:10.822Z [io-compute-blocker-5] INFO  ironbark - ironbark config loaded successfully: IronbarkConfig(Logger[ironbark],SpellingConfig(None,Some(200),None,5,0.8),OriginWhitelist(List(example.com, good.com, my.company.org),OriginPrecision(true)),Some(CustomDictionaryPath(/app/resources/custom-dictionaries)),Some(HunspellDictionaryPath(/app/resources/hunspell-dictionaries)),StaticCustomDictionaryScanConfig)
+spelling-tiny-1  | 2025-02-11 09:51:11.101Z [io-compute-blocker-6] INFO  c.e.i.d.StaticCustomDictionaries$ - Using custom dictionary: [global] = 2 words in engine Hunspell
+spelling-tiny-1  | 2025-02-11 09:51:11.104Z [io-compute-blocker-6] INFO  c.e.i.d.StaticCustomDictionaries$ - Using custom dictionary: [global] = 2 words in engine WinterTree
+spelling-tiny-1  | 2025-02-11 09:51:11.161Z [io-compute-blocker-6] INFO  com.ephox.nectar.data.Bees$ - Loading all dictionaries from WinterTree
+spelling-tiny-1  | 2025-02-11 09:51:11.482Z [io-compute-blocker-5] INFO  c.e.nectar.hunspell.HunspellLoader$ - Loading hunspell dictionary from path: /app/resources/hunspell-dictionaries and locale es
+spelling-tiny-1  | 2025-02-11 09:51:11.536Z [io-compute-blocker-5] INFO  c.e.nectar.hunspell.HunspellLoader$ - Finished loading hunspell for es
+spelling-tiny-1  | 2025-02-11 09:51:11.537Z [io-compute-blocker-5] INFO  c.e.nectar.hunspell.HunspellLoader$ - Loading hunspell dictionary from path: /app/resources/hunspell-dictionaries and locale pt_BR
+spelling-tiny-1  | 2025-02-11 09:51:11.881Z [io-compute-blocker-5] INFO  c.e.nectar.hunspell.HunspellLoader$ - Finished loading hunspell for pt_BR
+...
+spelling-tiny-1  | 2025-02-11 09:51:13.593Z [io-compute-blocker-5] INFO  c.e.nectar.hunspell.HunspellLoader$ - Loading hunspell dictionary from path: /app/resources/hunspell-dictionaries and locale de_DE
+spelling-tiny-1  | 2025-02-11 09:51:13.651Z [io-compute-blocker-5] INFO  c.e.nectar.hunspell.HunspellLoader$ - Finished loading hunspell for de_DE
+spelling-tiny-1  | 2025-02-11 09:51:14.142Z [io-compute-9] INFO  o.h.b.c.nio1.NIO1SocketServerGroup - Service bound to address /0:0:0:0:0:0:0:0:18080
+spelling-tiny-1  | 2025-02-11 09:51:14.146Z [io-compute-9] INFO  o.h.blaze.server.BlazeServerBuilder - 
+spelling-tiny-1  |   _   _   _        _ _
+spelling-tiny-1  |  | |_| |_| |_ _ __| | | ___
+spelling-tiny-1  |  | ' \\  _|  _| '_ \\_  _(_-<
+spelling-tiny-1  |  |_||_\\__|\\__| .__/ |_|/__/
+spelling-tiny-1  |              |_|
+spelling-tiny-1  | 2025-02-11 09:51:14.162Z [io-compute-9] INFO  o.h.blaze.server.BlazeServerBuilder - http4s v0.23.27 on blaze v0.23.16 started at http://[::]:18080/
+----
+
+=== Next Steps 
+
+. Test the service via `cURL` command
+
++
+To verify that the {pluginname} service is set up and functioning correctly within the container, ensure the service is running on port `18080`. Once active, it should be ready to receive requests. The expected outputs below confirm proper configuration, assuming `http://good.com` is in the allowed origins and `http://bad.com` is not.
+
++
+To check the service is running, use:
+
++
+[source, sh]
+----
+curl <http://localhost:18080/version>
+----
+
++
+An example output is: `2.127.0`
+
++
+To confirm that a request is being sent to the {pluginname} service, use:
+
++
+[source, sh]
+----
+curl <http://localhost:18080/2/check> -d '{"words": ["teh"], "language": "en_US"}' -H "Origin: <http://good.com>" -H "Content-Type: application/json"
+----
+
++
+Finally, to verify if a request is unauthorized and originates from an incorrect origin, use:
+
++
+[source, sh]
+----
+curl <http://localhost:18080/2/check> -d '{"words": ["teh"], "language": "en_US"}' -H "Origin: <http://bad.com>" -H "Content-Type: application/json"
+----
+
++
+If an error occurs,  the expected message is: `{ "message": "The supplied authentication is not authorized to access this resource" }`.
+
+. Test directly in {productname}
+
++
+Before deploying, it is recommended to test this service within the {productname} editor itself.
+
++
+To do this, configure the link:https://www.tiny.cloud/docs/tinymce/latest/introduction-to-tiny-spellchecker/[{pluginname}] feature in the editor and call it via `tinymce.init`. If running locally on the default port `18080`, use the following settings:
+
++
+[source, js]
+----
+tinymce.init({
+  …,
+  spellchecker_rpc_url: "<http://localhost:18080>"
+});
+----
+
+
+
+
+
diff --git a/modules/ROOT/partials/docker/spelling-service/spelling-service-overview.adoc b/modules/ROOT/partials/docker/spelling-service/spelling-service-overview.adoc
@@ -0,0 +1,10 @@
+[[overview]]
+== Overview
+
+The On-Premises version of the link:https://www.tiny.cloud/tinymce/features/spell-checker/[{pluginname}] is an application that can be installed and run on the customer’s in-house servers and computing infrastructure, including a private cloud.
+
+A valid xref:license-key.adoc[License Key] is required in order to install {pluginname} On-Premises. link:https://www.tiny.cloud/contact/[Contact Tiny Support] to request a trial xref:license-key.adoc[License Key].
+
+The only requirement to run these services On-Premises is a container runtime or orchestration tool e.g. Docker, Kubernetes, Podman.
+
+include::partial$misc/admon-dont-push-docker-images.adoc[]
diff --git a/modules/ROOT/partials/docker/spelling-service/spelling-service-requirements.adoc b/modules/ROOT/partials/docker/spelling-service/spelling-service-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 Linux, Unix or macOS operating system.
+** 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].