Skip to content

Commit 227d45c

Browse files
author
Sorita Heng
committed
DOC-3136: Update documentation for Spelling service using Docker (individually licensed)
1 parent 1b8c3de commit 227d45c

File tree

4 files changed

+265
-3
lines changed

4 files changed

+265
-3
lines changed

‎modules/ROOT/pages/individual-spelling-container.adoc‎

Lines changed: 8 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,11 @@
1-
= Deploy the TinyMCE Spelling server-side component using Docker (individually licensed)
1+
= Deploy the {productname} Spelling server-side component using Docker (individually licensed)
22
:navtitle: Spelling service
3-
:description: How-to deploy the TinyMCE Spelling server-side component using Docker (individually licensed).
3+
:description: How-to deploy the {productname} Spelling server-side component using Docker (individually licensed).
44
:shbundledockerfiles: false
5+
:pluginname: Spell Checker
56

6-
include::partial$docker/dockerized-spelling-service.adoc[]
7+
include::partial$docker/spelling-service/spelling-service-overview.adoc[]
8+
9+
include::partial$docker/spelling-service/spelling-service-requirements.adoc[]
10+
11+
include::partial$docker/spelling-service/spelling-service-installation.adoc[]

‎modules/ROOT/partials/docker/spelling-service/spelling-service-installation.adoc‎

Lines changed: 239 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,239 @@
1+
[[installation]]
2+
== Installation
3+
4+
[NOTE]
5+
A valid xref:license-key.adoc[License Key] is **required** in order to install {pluginname} On-Premises.
6+
link:https://www.tiny.cloud/contact/[Contact us] for a trial xref:license-key.adoc[License Key].
7+
8+
=== Retrieve Docker Image
9+
10+
. Login into the {companyname} Cloud Docker Registry:
11+
+
12+
[source, sh, subs="attributes+"]
13+
----
14+
docker login -u [username] -p [password] registry.containers.tiny.cloud
15+
----
16+
17+
. Pull the Docker Image from the Docker registry:
18+
+
19+
[source, sh, subs="attributes+"]
20+
----
21+
docker pull registry.containers.tiny.cloud/spelling-tiny:[version]
22+
----
23+
+
24+
Replace `version` with `latest` or the specific version number.
25+
26+
=== Specify Configurations
27+
28+
After completing the previous steps, run the Docker container from the pulled image:
29+
30+
[source, sh, subs="attributes+"]
31+
----
32+
docker run -p 18080:18080 registry.containers.tiny.cloud/spelling-tiny:[version]
33+
----
34+
35+
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.
36+
37+
If set up correctly, the logs should display output similar to the following:
38+
39+
[source, log]
40+
----
41+
2024-12-05 11:30:50.813Z [io-compute-9] INFO ironbark - ironbark
42+
...
43+
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)
44+
2024-12-05 11:30:51.206Z [io-compute-blocker-9] WARN c.e.d.config.AllowedOriginsConfig$ - No allowed-origins specified in config!
45+
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)
46+
2024-12-05 11:30:51.275Z [io-compute-blocker-9] INFO com.ephox.nectar.data.Bees$ - Loading all dictionaries from WinterTree
47+
2024-12-05 11:30:51.677Z [io-compute-blocker-6] INFO com.ephox.nectar.data.Bees$ - Loading all dictionaries from WinterTree
48+
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
49+
2024-12-05 11:30:52.131Z [io-compute-7] INFO o.h.blaze.server.BlazeServerBuilder -
50+
_ _ _ _ _
51+
| |_| |_| |_ _ __| | | ___
52+
| ' \\ _| _| '_ \\_ _(_-<
53+
|_||_\\__|\\__| .__/ |_|/__/
54+
|_|
55+
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/
56+
----
57+
58+
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.
59+
60+
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].
61+
62+
This configuration file requires at least the following information:
63+
64+
* `allowed-origins`: Specifies the domains allowed to communicate with server-side editor features. This is **mandatory** for all server-side components.
65+
66+
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:
67+
68+
==== Configure Custom Dictionaries
69+
70+
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:
71+
72+
* `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.
73+
* `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`.
74+
75+
==== Configure Extra Hunspell Dictionaries
76+
77+
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:
78+
79+
* `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.
80+
81+
This is an example `application.conf` file with the basic configurations:
82+
83+
[source, conf]
84+
----
85+
ephox {
86+
87+
allowed-origins {
88+
origins = [
89+
"<http://example.com>",
90+
"<http://good.com> ",
91+
"*.my.company.org"
92+
]
93+
}
94+
95+
spelling {
96+
custom-dictionaries-path = "/app/resources/custom-dictionaries"
97+
hunspell-dictionaries-path = "/app/resources/hunspell-dictionaries"
98+
}
99+
}
100+
----
101+
102+
=== Launch the Docker Container
103+
104+
Once the application configuration file is ready, proceed with the Docker Compose setup to configure and run the service.
105+
106+
. Create the `docker-compose.yml` file:
107+
108+
+
109+
[source, yml]
110+
----
111+
services:
112+
spelling-tiny:
113+
image: registry.containers.tiny.cloud/spelling-tiny:<VERSION>
114+
ports:
115+
- "18080:18080"
116+
restart: always
117+
init: true
118+
volumes:
119+
- type: bind
120+
source: <PATH_TO_APPLICATION_CONF_FILE_IN_HOST_MACHINE>
121+
target: /ephox-spelling/ephox-spelling-docker-env.conf
122+
read_only: true
123+
- type: bind
124+
source: <HOST_PATH_TO_CUSTOM_DICT_FOLDER>
125+
target: /app/resources/custom-dictionaries
126+
read_only: true
127+
- type: bind
128+
source: <HOST_PATH_TO_HUNSPELL_DICT_FOLDER>
129+
target: /app/resources/hunspell-dictionaries
130+
read_only: true
131+
----
132+
133+
. Run the service (within the same directory where docker-compose.yaml was placed):
134+
135+
+
136+
[source, sh]
137+
----
138+
docker compose up
139+
----
140+
141+
+
142+
If the allowed origins, Hunspell, and custom dictionaries folders are configured correctly, the initiation logs should appear as follows:
143+
144+
+
145+
[source, log]
146+
----
147+
[+] Running 2/2
148+
✔ Network spelling-tiny_default Created 0.0s
149+
✔ Container spelling-tiny-spelling-tiny-1 Created 0.1s
150+
Attaching to spelling-tiny-1
151+
spelling-tiny-1 | 2025-02-11 09:51:10.332Z [io-compute-5] INFO ironbark - ironbark
152+
...
153+
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)
154+
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:
155+
spelling-tiny-1 | - example.com
156+
spelling-tiny-1 | - good.com
157+
spelling-tiny-1 | - my.company.org
158+
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)
159+
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
160+
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
161+
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
162+
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
163+
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
164+
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
165+
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
166+
...
167+
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
168+
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
169+
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
170+
spelling-tiny-1 | 2025-02-11 09:51:14.146Z [io-compute-9] INFO o.h.blaze.server.BlazeServerBuilder -
171+
spelling-tiny-1 | _ _ _ _ _
172+
spelling-tiny-1 | | |_| |_| |_ _ __| | | ___
173+
spelling-tiny-1 | | ' \\ _| _| '_ \\_ _(_-<
174+
spelling-tiny-1 | |_||_\\__|\\__| .__/ |_|/__/
175+
spelling-tiny-1 | |_|
176+
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/
177+
----
178+
179+
=== Next Steps
180+
181+
. Test the service via `cURL` command
182+
183+
+
184+
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.
185+
186+
+
187+
To check the service is running, use:
188+
189+
+
190+
[source, sh]
191+
----
192+
curl <http://localhost:18080/version>
193+
----
194+
195+
+
196+
An example output is: `2.127.0`
197+
198+
+
199+
To confirm that a request is being sent to the {pluginname} service, use:
200+
201+
+
202+
[source, sh]
203+
----
204+
curl <http://localhost:18080/2/check> -d '{"words": ["teh"], "language": "en_US"}' -H "Origin: <http://good.com>" -H "Content-Type: application/json"
205+
----
206+
207+
+
208+
Finally, to verify if a request is unauthorized and originates from an incorrect origin, use:
209+
210+
+
211+
[source, sh]
212+
----
213+
curl <http://localhost:18080/2/check> -d '{"words": ["teh"], "language": "en_US"}' -H "Origin: <http://bad.com>" -H "Content-Type: application/json"
214+
----
215+
216+
+
217+
If an error occurs, the expected message is: `{ "message": "The supplied authentication is not authorized to access this resource" }`.
218+
219+
. Test directly in {productname}
220+
221+
+
222+
Before deploying, it is recommended to test this service within the {productname} editor itself.
223+
224+
+
225+
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:
226+
227+
+
228+
[source, js]
229+
----
230+
tinymce.init({
231+
…,
232+
spellchecker_rpc_url: "<http://localhost:18080>"
233+
});
234+
----
235+
236+
237+
238+
239+

‎modules/ROOT/partials/docker/spelling-service/spelling-service-overview.adoc‎

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,10 @@
1+
[[overview]]
2+
== Overview
3+
4+
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.
5+
6+
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].
7+
8+
The only requirement to run these services On-Premises is a container runtime or orchestration tool e.g. Docker, Kubernetes, Podman.
9+
10+
include::partial$misc/admon-dont-push-docker-images.adoc[]

‎modules/ROOT/partials/docker/spelling-service/spelling-service-requirements.adoc‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,8 @@
1+
[[requirements]]
2+
== Requirements
3+
4+
* The link:https://docs.docker.com/engine/docker-overview/[Docker Engine] is installed and running.
5+
* The user has Administrative or Root user access to run the Docker commands.
6+
* The user is either:
7+
** Using a Linux, Unix or macOS operating system.
8+
** 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].

0 commit comments

Comments
 (0)