Skip to content

Commit caf6c27

Browse files
author
Sorita Heng
committed
DOC-3134: Update documentation for Hyperlinking service using Docker (individually licensed)
1 parent 1b8c3de commit caf6c27

File tree

5 files changed

+253
-4
lines changed

5 files changed

+253
-4
lines changed

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

Lines changed: 9 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,12 @@
1-
= Deploy the TinyMCE Hyperlinking server-side component using Docker (individually licensed)
1+
= Deploy the {productname} Hyperlinking server-side component using Docker (individually licensed)
22
:navtitle: Hyperlinking service
3-
:description: How-to deploy the TinyMCE Hyperlinking server-side component using Docker (individually licensed).
3+
:description: How-to deploy the {productname} Hyperlinking server-side component using Docker (individually licensed).
44
:shbundledockerfiles: false
5+
:linkcheckerplugin: Link Checker
6+
:mediaembedplugin: Enhanced Media Embed
57

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

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

Lines changed: 225 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,225 @@
1+
[[installation]]
2+
== Installation
3+
4+
[NOTE]
5+
A valid license key is needed in order to install {linkcheckerplugin} and {mediaembedplugin} On-Premises.
6+
link:https://www.tiny.cloud/contact/[Contact us] for a trial license key.
7+
8+
=== Retrieve Docker Image
9+
10+
. Login into the Tiny 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/hyperlinking-tiny:<VERSION>
22+
----
23+
+
24+
Replace `<VERSION>` with `latest` or the specific version number you’re looking for (eg: `2.109.0`)
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 19100:19100 registry.containers.tiny.cloud/hyperlinking-tiny:<VERSION>
33+
----
34+
35+
This triggers `-p 19100:19100`, exposing the service on `localhost:19100`. The service runs on port `19100` 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+
2025-01-02 11:06:45 [io-compute-8] INFO navi - navi
42+
...
43+
2025-01-02 11:06:45 [io-compute-blocker-8] INFO navi - -> Raw Config assembled from various sources: ConfigOrigin(merge of /ephox-hyperlinking/ephox-hyperlinking-docker-env.conf: 1,system properties,reference.conf @ jar:file:/ephox-hyperlinking/ephox-hyperlinking.jar!/reference.conf: 1)
44+
2025-01-02 11:06:46 [io-compute-blocker-8] WARN c.e.d.config.AllowedOriginsConfig$ - No allowed-origins specified in config!
45+
2025-01-02 11:06:46 [io-compute-blocker-8] WARN c.e.d.config.AllowedOriginsConfig$ - No allowed-origins specified in config!
46+
2025-01-02 11:06:46 [io-compute-blocker-8] INFO navi - navi config loaded successfully: NaviConfig(LinkCheckerConfig(true,ReturnUnknown),true,CacheConfig(10000,86400 seconds,3600 seconds),SdkServiceWithClientConfig(HttpConfig(100,10,10,3,HttpConfigTimeouts(10,10,10),JvmTrustModel()),None,OriginWhitelist(List(),OriginPrecision(true))),SelfHostedMediaSourcesConfig(CustomEmbedPlugins(UrlTrie(Branch(None,TreeMap()),Branch(None,TreeMap()))),None),OriginWhitelist(List(),OriginPrecision(true)),Logger[navi])
47+
2025-01-02 11:06:46 [io-compute-9] INFO o.h.b.c.nio1.NIO1SocketServerGroup - Service bound to address /0:0:0:0:0:0:0:0:19100
48+
2025-01-02 11:06:46 [io-compute-9] INFO o.h.blaze.server.BlazeServerBuilder -
49+
_ _ _ _ _
50+
| |_| |_| |_ _ __| | | ___
51+
| ' \\ _| _| '_ \\_ _(_-<
52+
|_||_\\__|\\__| .__/ |_|/__/
53+
|_|
54+
2025-01-02 11:06:46 [io-compute-9] INFO o.h.blaze.server.BlazeServerBuilder - http4s v0.23.27 on blaze v0.23.16 started at http://[::]:19100/
55+
----
56+
57+
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.
58+
59+
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].
60+
61+
This configuration file requires at least the following information:
62+
63+
* allowed-origins - Specifies the domains allowed to communicate with server-side editor features. This is mandatory for all server-side components.
64+
65+
The following settings for the premium server-side components are optional and will apply to all services that make outgoing HTTP/HTTPS requests using the configuration file.
66+
67+
* link:https://www.tiny.cloud/docs/tinymce/latest/configure-common-settings-services/#proxy[proxy configuration]
68+
* link:https://www.tiny.cloud/docs/tinymce/latest/configure-common-settings-services/#http[http configuration]
69+
70+
The following settings for the Hyperlinking premium server-side component are optional:
71+
72+
* link:https://www.tiny.cloud/docs/tinymce/latest/configure-hyperlink-service/#link-checking[link-checking configuration]
73+
* link:https://www.tiny.cloud/docs/tinymce/latest/configure-hyperlink-service/#cache[cache configuration]
74+
75+
The {mediaembedplugin} service allows the use of a custom Iframely account, configured oEmbed endpoints, or a combination of both. If a URL lacks an Iframely or oEmbed configuration, the service generates a summary card.
76+
77+
[TIP]
78+
A summary card is an embeddable snippet of code created based on the available metadata and content detected at the URL. This ensures that even if no predefined embedding method is configured, the service can still provide a structured and visually consistent media representation.
79+
80+
When media is inserted into content, the service follows this sequence:
81+
82+
. Check if the URL matches any custom link:https://www.tiny.cloud/docs/tinymce/latest/mediaembed-server-config/#configure-a-custom-endpoint[oEmbed] configuration. If that fails,
83+
. If link:https://www.tiny.cloud/docs/tinymce/latest/mediaembed-server-config/#use-your-own-iframely-account[Iframely] is configured, query the Iframely API. If Iframely is not configured,
84+
. Create a summary card.
85+
86+
The following settings for the Enhanced Media Embed service are optional:
87+
88+
* link:https://www.tiny.cloud/docs/tinymce/latest/mediaembed-server-config/#use-your-own-iframely-account[Iframely account configuration]
89+
* link:https://www.tiny.cloud/docs/tinymce/latest/mediaembed-server-config/#configure-a-custom-endpoint[oEmbed customs configuration]
90+
91+
=== Launch the Docker Container
92+
93+
Once the application configuration file is ready, proceed with the Docker Compose setup to configure and run the service.
94+
95+
. Create the `docker-compose.yml` file:
96+
+
97+
98+
[source, yml]
99+
100+
----
101+
services:
102+
hyperlinking-tiny:
103+
image: registry.containers.tiny.cloud/hyperlinking-tiny:<VERSION>
104+
ports:
105+
- "19100:19100"
106+
restart: always
107+
init: true
108+
volumes:
109+
- type: bind
110+
source: <PATH_TO_APPLICATION_CONF_FILE_IN_HOST_MACHINE>
111+
target: /ephox-hyperlinking/ephox-hyperlinking-docker-env.conf
112+
read_only: true
113+
----
114+
115+
. Run the service (within the same directory where `docker-compose.yaml` was placed):
116+
+
117+
118+
[source, sh]
119+
----
120+
docker compose up
121+
----
122+
+
123+
If the setup is correct, the initiation logs should appear as follows:
124+
125+
+
126+
[source, log]
127+
----
128+
✔ Container hyperlinking-tiny-hyperlinking-tiny-1 Recreated 0.1s
129+
Attaching to hyperlinking-tiny-1
130+
hyperlinking-tiny-1 | 2025-01-02 16:17:28 [io-compute-1] INFO navi - navi
131+
132+
...
133+
134+
-> Found value for property: /ephox-hyperlinking/ephox-hyperlinking-docker-env.conf
135+
hyperlinking-tiny-1 | 2025-01-02 16:17:28 [io-compute-blocker-1] INFO navi - * Parsing config defined by /ephox-hyperlinking/ephox-hyperlinking-docker-env.conf from property: ephox.config.file
136+
hyperlinking-tiny-1 | 2025-01-02 16:17:28 [io-compute-blocker-1] INFO navi - -> Processing file: /ephox-hyperlinking/ephox-hyperlinking-docker-env.conf
137+
hyperlinking-tiny-1 | 2025-01-02 16:17:28 [io-compute-blocker-1] INFO navi - * External application.conf => /opt/ephox/application.conf
138+
hyperlinking-tiny-1 | 2025-01-02 16:17:28 [io-compute-blocker-1] INFO navi - * Optional File (/opt/ephox/application.conf). Defaults to empty if file not found
139+
hyperlinking-tiny-1 | 2025-01-02 16:17:28 [io-compute-blocker-1] INFO navi - * Internal Configuration
140+
hyperlinking-tiny-1 | 2025-01-02 16:17:28 [io-compute-blocker-1] INFO navi - -> No extra internal configuration specified - skipping
141+
hyperlinking-tiny-1 | 2025-01-02 16:17:28 [io-compute-blocker-1] INFO navi - * Default (Reference) Configuration
142+
hyperlinking-tiny-1 | 2025-01-02 16:17:28 [io-compute-blocker-1] INFO navi - * Loading configuration files from classpath (reference.conf and integration.conf). Neither is required.
143+
hyperlinking-tiny-1 | 2025-01-02 16:17:28 [io-compute-blocker-1] INFO navi - -> Raw Config assembled from various sources: ConfigOrigin(merge of /ephox-hyperlinking/ephox-hyperlinking-docker-env.conf: 1,system properties,reference.conf @ jar:file:/ephox-hyperlinking/ephox-hyperlinking.jar!/reference.conf: 1)
144+
hyperlinking-tiny-1 | 2025-01-02 16:17:28 [io-compute-blocker-1] INFO c.e.d.config.AllowedOriginsConfig$ - Read allowed-origins config (ignoring ports = true) as:
145+
hyperlinking-tiny-1 | - localhost
146+
hyperlinking-tiny-1 | - localhost:8000
147+
hyperlinking-tiny-1 | - ephox.com
148+
hyperlinking-tiny-1 | 2025-01-02 16:17:28 [io-compute-blocker-1] INFO c.e.d.config.AllowedOriginsConfig$ - Read allowed-origins config (ignoring ports = true) as:
149+
hyperlinking-tiny-1 | - localhost
150+
hyperlinking-tiny-1 | - localhost:8000
151+
hyperlinking-tiny-1 | - ephox.com
152+
hyperlinking-tiny-1 | 2025-01-02 16:17:28 [io-compute-blocker-1] INFO navi - navi config loaded successfully: NaviConfig(LinkCheckerConfig(true,ReturnUnknown),true,CacheConfig(10000,86400 seconds,3600 seconds),SdkServiceWithClientConfig(HttpConfig(100,10,10,3,HttpConfigTimeouts(15,15,15),JvmTrustModel()),None,OriginWhitelist(List(localhost, localhost:8000, ephox.com),OriginPrecision(true))),SelfHostedMediaSourcesConfig(CustomEmbedPlugins(UrlTrie(Branch(None,TreeMap()),Branch(None,TreeMap(org -> Branch(None,TreeMap(wikipedia -> Branch(None,TreeMap(en -> Branch(Some(PathMatcher(List((wiki/.*,WikipediaEmbedPlugin(<https://en.wikipedia.org/w/api.php,10>))))),TreeMap()))))))))),None),OriginWhitelist(List(localhost, localhost:8000, ephox.com),OriginPrecision(true)),Logger[navi])
153+
hyperlinking-tiny-1 | 2025-01-02 16:17:29 [io-compute-6] INFO o.h.b.c.nio1.NIO1SocketServerGroup - Service bound to address /0:0:0:0:0:0:0:0:19100
154+
hyperlinking-tiny-1 | 2025-01-02 16:17:29 [io-compute-6] INFO o.h.blaze.server.BlazeServerBuilder -
155+
hyperlinking-tiny-1 | _ _ _ _ _
156+
hyperlinking-tiny-1 | | |_| |_| |_ _ __| | | ___
157+
hyperlinking-tiny-1 | | ' \\ _| _| '_ \\_ _(_-<
158+
hyperlinking-tiny-1 | |_||_\\__|\\__| .__/ |_|/__/
159+
hyperlinking-tiny-1 | |_|
160+
hyperlinking-tiny-1 | 2025-01-02 16:17:29 [io-compute-6] INFO o.h.blaze.server.BlazeServerBuilder - http4s v0.23.27 on blaze v0.23.16 started at http://[::]:19100/
161+
----
162+
163+
=== Next Steps
164+
165+
. Test the service via `cURL` command
166+
+
167+
168+
To verify that the Hyperlinking service is set up and functioning correctly within the container, ensure the service is running on port `19100`. 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.
169+
170+
+
171+
To check the service is running use:
172+
173+
+
174+
[source, sh]
175+
----
176+
curl <http://localhost:19100/version>
177+
----
178+
179+
+
180+
An example output is: `2.109.0`
181+
182+
+
183+
To confirm that a request is being sent to the {linkcheckerplugin} service, use:
184+
185+
+
186+
[source, sh]
187+
----
188+
curl --location '<http://localhost:19100/1/check>' \\
189+
--header 'Origin: <http://good.com>' \\
190+
--header 'Content-Type: application/json' \\
191+
--data '{ "urls": [{"url":"<http://google.com>"}, {"url": "<http://youtube.com>"}, {"url":"<http://google.com/404>"}, {"url":"<https://ephox>.."}]}'
192+
----
193+
194+
+
195+
Finally, to verify if a request is unauthorized and originates from an incorrect origin, use:
196+
197+
+
198+
[source, sh]
199+
----
200+
curl --location '<http://localhost:19100/1/check>' \\
201+
--header 'Origin: <http://bad.com>' \\
202+
--header 'Content-Type: application/json' \\
203+
--data '{ "urls": [{"url":"<http://google.com>"}, {"url": "<http://youtube.com>"}, {"url":"<http://google.com/404>"}, {"url":"<https://ephox>.."}]}'
204+
----
205+
206+
+
207+
If an error occurs, the expected message is: `{ "message": "The supplied authentication is not authorized to access this resource" }`.
208+
209+
. Test directly in {productname}
210+
+
211+
212+
Before deploying, it is recommended to test this service within the {productname} editor itself.
213+
214+
+
215+
To do this, configure the link:https://www.tiny.cloud/docs/tinymce/latest/linkchecker/[{linkcheckerplugin}] and link:https://www.tiny.cloud/docs/tinymce/latest/introduction-to-mediaembed/[{mediaembedplugin}] features in the editor and call them via `tinymce.init`. If running locally on the default port `19100`, use the following settings:
216+
217+
+
218+
[source, js]
219+
----
220+
tinymce.init({
221+
…,
222+
linkchecker_service_url: "<http://localhost:19100>",
223+
mediaembed_service_url: "<http://localhost:19100>"
224+
});
225+
----

‎modules/ROOT/partials/docker/hyperlinking-service/hyperlinking-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/link-checker/[{linkcheckerplugin}] and link:https://www.tiny.cloud/tinymce/features/enhanced-media-embed/[{mediaembedplugin}] 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 license key is required in order to install {linkcheckerplugin} and {mediaembedplugin} On-Premises. link:https://www.tiny.cloud/contact/[Contact Tiny Support] to request a trial 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/hyperlinking-service/hyperlinking-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 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 https://gitforwindows.org/[Git for Windows], https://www.cygwin.com/[Cygwin], or the https://docs.microsoft.com/en-us/windows/wsl/install-win10[Windows Subsystem for Linux].

‎modules/ROOT/partials/misc/admon-dont-push-docker-images.adoc‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
[WARNING]
22
====
3-
Do not push this docker image to a publicly accessible container registry. Doing so will constitute a breach of the {companyname} Self-Hosted Software License Agreement, _including_:
3+
Pushing this Docker image to a public container registry violates the {companyname} Self-Hosted Software License Agreement, _including_:
44
55
* link:{legalpages}/tiny-self-hosted-enterprise-agreement/[The {companyname} Self-Hosted Software License Agreement - (Enterprise Users)].
66
* link:{legalpages}/tiny-self-hosted-oem-saas-agreement/[The {companyname} Self-Hosted Software License Agreement - (OEM & SaaS Users)].

0 commit comments

Comments
 (0)