Skip to content

Commit 777f3c9

Browse files
soritahengSorita Hengkemister85frossi933
authored
DOC-3134: Update documentation for Hyperlinking service using Docker (individually licensed) (#3629)
* DOC-3134: Update documentation for Hyperlinking service using Docker (individually licensed) * Update modules/ROOT/partials/docker/hyperlinking-service/hyperlinking-service-installation.adoc Co-authored-by: Karl Kemister-Sheppard <[email protected]> * Update modules/ROOT/partials/docker/hyperlinking-service/hyperlinking-service-installation.adoc Co-authored-by: Karl Kemister-Sheppard <[email protected]> * Update modules/ROOT/partials/docker/hyperlinking-service/hyperlinking-service-installation.adoc Co-authored-by: Karl Kemister-Sheppard <[email protected]> * Update modules/ROOT/partials/docker/hyperlinking-service/hyperlinking-service-installation.adoc Co-authored-by: Karl Kemister-Sheppard <[email protected]> * Update modules/ROOT/partials/docker/hyperlinking-service/hyperlinking-service-installation.adoc Co-authored-by: Karl Kemister-Sheppard <[email protected]> * Update modules/ROOT/partials/docker/hyperlinking-service/hyperlinking-service-requirements.adoc Co-authored-by: Karl Kemister-Sheppard <[email protected]> * Update modules/ROOT/partials/docker/hyperlinking-service/hyperlinking-service-requirements.adoc Co-authored-by: Karl Kemister-Sheppard <[email protected]> * Update modules/ROOT/partials/docker/hyperlinking-service/hyperlinking-service-overview.adoc Co-authored-by: Karl Kemister-Sheppard <[email protected]> * Update modules/ROOT/partials/docker/hyperlinking-service/hyperlinking-service-installation.adoc Co-authored-by: Karl Kemister-Sheppard <[email protected]> * Add links for Iframely and oEmbed * DOC-3143: Remove dark mode detection and set skin to oxide-dark in demo examples; update release notes formatting issue. * Revert "DOC-3143: Remove dark mode detection and set skin to oxide-dark in demo examples; update release notes formatting issue." This reverts commit df31f31. * Minor fixes and adjustments for clarity * DOC-3134: Remove License key notes in docs about Hyperlinking service using Docker * minor copy edits * Update Docker access info and installation instructions * Update modules/ROOT/partials/docker/hyperlinking-service/hyperlinking-service-installation.adoc Co-authored-by: Karl Kemister-Sheppard <[email protected]> * Update modules/ROOT/partials/docker/hyperlinking-service/hyperlinking-service-installation.adoc Co-authored-by: Karl Kemister-Sheppard <[email protected]> * Fix directory structure * Update modules/ROOT/partials/docker/hyperlinking-service/hyperlinking-service-installation.adoc * Update modules/ROOT/partials/docker/hyperlinking-service/hyperlinking-service-installation.adoc --------- Co-authored-by: Sorita Heng <[email protected]> Co-authored-by: Karl Kemister-Sheppard <[email protected]> Co-authored-by: Federico Rossi <[email protected]>
1 parent efd49f9 commit 777f3c9

File tree

7 files changed

+290
-4
lines changed

7 files changed

+290
-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
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.
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: 253 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,253 @@
1+
[[installation]]
2+
== Installation
3+
4+
include::partial$misc/admon-docker-access.adoc[]
5+
6+
=== Retrieve Docker Image
7+
8+
. Login into the {companyname} Cloud Docker Registry:
9+
+
10+
[source, sh, subs="attributes+"]
11+
----
12+
docker login -u tiny -p [access-token] registry.containers.tiny.cloud
13+
----
14+
15+
. Pull the Docker Image from the Docker registry:
16+
+
17+
[source, sh, subs="attributes+"]
18+
----
19+
docker pull registry.containers.tiny.cloud/hyperlinking-tiny:<VERSION>
20+
----
21+
+
22+
Replace `<VERSION>` with `latest` or the specific version number.
23+
24+
include::partial$misc/admon-available-docker-images.adoc[]
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 xref:mediaembed-server-config.adoc#use-your-own-iframely-account[Iframely] account, configured xref:mediaembed-server-config.adoc#configure-a-custom-endpoint[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+
=== Run the Docker Container
92+
93+
The Docker container can also be run with `docker compose`. In this example, the following directory structure is assumed:
94+
95+
[source,sh]
96+
----
97+
hyperlinking-service/
98+
├── application.conf
99+
└── docker-compose.yaml
100+
----
101+
102+
Here is an example of the application.conf file with the basic configurations:
103+
104+
[source,conf]
105+
----
106+
ephox {
107+
108+
allowed-origins {
109+
origins = [
110+
"<http://example.com>",
111+
"<http://good.com> ",
112+
"*.my.company.org"
113+
]
114+
}
115+
116+
}
117+
----
118+
119+
Once the application configuration file is ready, proceed with the Docker Compose setup to configure and run the service.
120+
121+
. Create the `docker-compose.yaml` file:
122+
+
123+
124+
[source, yaml]
125+
126+
----
127+
services:
128+
hyperlinking-tiny:
129+
image: registry.containers.tiny.cloud/hyperlinking-tiny:<VERSION>
130+
ports:
131+
- "19100:19100"
132+
restart: always
133+
init: true
134+
volumes:
135+
- type: bind
136+
source: ./application.conf #change this to the path on your local machine
137+
target: /ephox-hyperlinking/ephox-hyperlinking-docker-env.conf
138+
read_only: true
139+
----
140+
141+
. Run the service (within the same directory where `docker-compose.yaml` was placed):
142+
+
143+
144+
[source, sh]
145+
----
146+
docker compose up
147+
----
148+
+
149+
If the setup is correct, the initiation logs should appear as follows:
150+
151+
+
152+
[source, log]
153+
----
154+
✔ Container hyperlinking-tiny-hyperlinking-tiny-1 Recreated 0.1s
155+
Attaching to hyperlinking-tiny-1
156+
hyperlinking-tiny-1 | 2025-01-02 16:17:28 [io-compute-1] INFO navi - navi
157+
158+
...
159+
160+
-> Found value for property: /ephox-hyperlinking/ephox-hyperlinking-docker-env.conf
161+
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
162+
hyperlinking-tiny-1 | 2025-01-02 16:17:28 [io-compute-blocker-1] INFO navi - -> Processing file: /ephox-hyperlinking/ephox-hyperlinking-docker-env.conf
163+
hyperlinking-tiny-1 | 2025-01-02 16:17:28 [io-compute-blocker-1] INFO navi - * External application.conf => /opt/ephox/application.conf
164+
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
165+
hyperlinking-tiny-1 | 2025-01-02 16:17:28 [io-compute-blocker-1] INFO navi - * Internal Configuration
166+
hyperlinking-tiny-1 | 2025-01-02 16:17:28 [io-compute-blocker-1] INFO navi - -> No extra internal configuration specified - skipping
167+
hyperlinking-tiny-1 | 2025-01-02 16:17:28 [io-compute-blocker-1] INFO navi - * Default (Reference) Configuration
168+
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.
169+
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)
170+
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:
171+
hyperlinking-tiny-1 | - localhost
172+
hyperlinking-tiny-1 | - localhost:8000
173+
hyperlinking-tiny-1 | - ephox.com
174+
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:
175+
hyperlinking-tiny-1 | - localhost
176+
hyperlinking-tiny-1 | - localhost:8000
177+
hyperlinking-tiny-1 | - ephox.com
178+
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])
179+
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
180+
hyperlinking-tiny-1 | 2025-01-02 16:17:29 [io-compute-6] INFO o.h.blaze.server.BlazeServerBuilder -
181+
hyperlinking-tiny-1 | _ _ _ _ _
182+
hyperlinking-tiny-1 | | |_| |_| |_ _ __| | | ___
183+
hyperlinking-tiny-1 | | ' \\ _| _| '_ \\_ _(_-<
184+
hyperlinking-tiny-1 | |_||_\\__|\\__| .__/ |_|/__/
185+
hyperlinking-tiny-1 | |_|
186+
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/
187+
----
188+
189+
=== Next Steps
190+
191+
. Test the service via `cURL` command
192+
+
193+
194+
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.
195+
196+
+
197+
To check the service is running use:
198+
199+
+
200+
[source, sh]
201+
----
202+
curl http://localhost:19100/version
203+
----
204+
205+
+
206+
An example output is: `2.109.0`
207+
208+
+
209+
To confirm that a request is being sent to the {linkcheckerplugin} service, use:
210+
211+
+
212+
[source, sh]
213+
----
214+
curl --location 'http://localhost:19100/1/check' \\
215+
--header 'Origin: http://good.com' \\
216+
--header 'Content-Type: application/json' \\
217+
--data '{ "urls": [{"url":"http://google.com"}, {"url": "http://youtube.com"}, {"url":"http://google.com/404"}, {"url":"https://ephox.."}]}'
218+
----
219+
220+
+
221+
Finally, to verify if a request is unauthorized and originates from an incorrect origin, use:
222+
223+
+
224+
[source, sh]
225+
----
226+
curl --location 'http://localhost:19100/1/check' \\
227+
--header 'Origin: http://bad.com' \\
228+
--header 'Content-Type: application/json' \\
229+
--data '{ "urls": [{"url":"http://google.com"}, {"url": "http://youtube.com"}, {"url":"http://google.com/404"}, {"url":"https://ephox.."}]}'
230+
----
231+
232+
+
233+
If an error occurs, the expected message is: `{ "message": "The supplied authentication is not authorized to access this resource" }`.
234+
235+
. Test directly in {productname}
236+
+
237+
238+
Before deploying, it is recommended to test this service within the {productname} editor itself.
239+
240+
+
241+
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:
242+
243+
+
244+
[source, js]
245+
----
246+
tinymce.init({
247+
selector: 'textarea', // change this value according to your HTML
248+
plugins: 'code image link linkchecker autolink code',
249+
toolbar: 'image link code',
250+
linkchecker_service_url: "http://localhost:19100",
251+
mediaembed_service_url: "http://localhost:19100"
252+
});
253+
----

‎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+
The only requirement to run these services On-Premises is a container runtime or orchestration tool e.g. Docker, Kubernetes, Podman.
7+
8+
A valid access token is required to access the Tiny Cloud Docker registry and pull the Docker image. Contact link:https://www.tiny.cloud/contact/[{companyname} Support^] to request the access token.
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 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 Unix-like operating system, such as Linux or macOS.
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].

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

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,4 @@
1+
[NOTE]
2+
====
3+
Currently, the Docker images are only supported on x86-64 (also known as AMD64) architecture processors.
4+
====

‎modules/ROOT/partials/misc/admon-docker-access.adoc‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
[IMPORTANT]
2+
====
3+
A valid access token is **required** in order to retrieve On-Premises services images from {companyname} Cloud Docker Registry.
4+
link:https://www.tiny.cloud/contact/[Contact {companyname} Support^] to request the access token.
5+
====

‎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)