DOC-3135: Update documentation for Image Proxy service using Docker (Individually licensed) (#3630)

* DOC-3135: Update documentaiton for Image Proxy service using Docker (individually licensed) * Minor fixes and adjustment for clarity * DOC-3135: Remove License key notes from docs about Image proxy service using Docker * Update modules/ROOT/partials/docker/image-proxy-service/image-proxy-service-overview.adoc Co-authored-by: Karl Kemister-Sheppard <karlkemistersheppard@gmail.com> * Update modules/ROOT/partials/docker/image-proxy-service/image-proxy-service-requirements.adoc Co-authored-by: Karl Kemister-Sheppard <karlkemistersheppard@gmail.com> * Update modules/ROOT/partials/docker/image-proxy-service/image-proxy-service-requirements.adoc Co-authored-by: Karl Kemister-Sheppard <karlkemistersheppard@gmail.com> * Update modules/ROOT/partials/docker/image-proxy-service/image-proxy-service-requirements.adoc Co-authored-by: Karl Kemister-Sheppard <karlkemistersheppard@gmail.com> * Update modules/ROOT/partials/docker/image-proxy-service/image-proxy-service-installation.adoc Co-authored-by: Karl Kemister-Sheppard <karlkemistersheppard@gmail.com> * Update modules/ROOT/partials/docker/image-proxy-service/image-proxy-service-installation.adoc Co-authored-by: Karl Kemister-Sheppard <karlkemistersheppard@gmail.com> * Update modules/ROOT/partials/docker/image-proxy-service/image-proxy-service-installation.adoc Co-authored-by: Karl Kemister-Sheppard <karlkemistersheppard@gmail.com> * Update modules/ROOT/partials/docker/image-proxy-service/image-proxy-service-installation.adoc Co-authored-by: Karl Kemister-Sheppard <karlkemistersheppard@gmail.com> * Update modules/ROOT/partials/docker/image-proxy-service/image-proxy-service-installation.adoc Co-authored-by: Karl Kemister-Sheppard <karlkemistersheppard@gmail.com> * Update modules/ROOT/partials/docker/image-proxy-service/image-proxy-service-installation.adoc Co-authored-by: Karl Kemister-Sheppard <karlkemistersheppard@gmail.com> * Update modules/ROOT/partials/docker/image-proxy-service/image-proxy-service-installation.adoc Co-authored-by: Karl Kemister-Sheppard <karlkemistersheppard@gmail.com> * Update modules/ROOT/partials/docker/image-proxy-service/image-proxy-service-installation.adoc Co-authored-by: Karl Kemister-Sheppard <karlkemistersheppard@gmail.com> * Update modules/ROOT/partials/docker/image-proxy-service/image-proxy-service-installation.adoc Co-authored-by: Karl Kemister-Sheppard <karlkemistersheppard@gmail.com> * Update yaml file example --------- Co-authored-by: Sorita Heng <sorita.heng@tiny.cloud> Co-authored-by: Federico Rossi <federico.rossi@tiny.cloud> Co-authored-by: Karl Kemister-Sheppard <karlkemistersheppard@gmail.com>
5 months ago · 393f0f1a06
5 changed files with 265 additions and 0 deletions
--- a/modules/ROOT/nav.adoc
+++ b/modules/ROOT/nav.adoc
@ -135,6 +135,7 @@
 ***** xref:bundle-imageproxy-container.adoc[Image Proxy service]
 **** Individually licensed plugin services
 ***** xref:individual-hyperlinking-container.adoc[Hyperlinking service]
+***** xref:individual-image-proxy-container.adoc[Image Proxy service]
 ***** xref:individual-spelling-container.adoc[Spelling service]
 ***** xref:individual-export-to-pdf-on-premises.adoc[Export to PDF]
 ***** xref:individual-import-from-word-and-export-to-word-on-premises.adoc[Import from Word and Export to Word]
--- a/modules/ROOT/pages/individual-image-proxy-container.adoc
+++ b/modules/ROOT/pages/individual-image-proxy-container.adoc
@ -0,0 +1,14 @@
+= Deploy the {productname} Image Proxy service server-side component using Docker
+:navtitle: Image Proxy service
+:description: How-to deploy the {productname} Image Proxy service server-side component using Docker.
+:shbundledockerfiles: false
+:pluginname: Image Editing
+
+//include::partial$docker/dockerized-hyperlinking-service.adoc[]
+include::partial$docker/image-proxy-service/image-proxy-service-overview.adoc[]
+
+include::partial$docker/image-proxy-service/image-proxy-service-requirements.adoc[]
+
+include::partial$docker/image-proxy-service/image-proxy-service-installation.adoc[]
+
+
--- a/modules/ROOT/partials/docker/image-proxy-service/image-proxy-service-installation.adoc
+++ b/modules/ROOT/partials/docker/image-proxy-service/image-proxy-service-installation.adoc
@ -0,0 +1,232 @@
+[[installation]]
+== Installation
+
+[IMPORTANT]
+A valid access token is **required** in order to retrieve On-Premises services images from {companyname} Cloud Docker Registry.
+link:https://www.tiny.cloud/contact/[Contact {companyname} Support^] to request the access token.
+
+=== Retrieve Docker Image
+
+. 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/image-proxy-tiny:<VERSION>
+----
+
+Replace `<VERSION>` with `latest` or the specific version number.
+
+[NOTE]
+Currently, the Docker images are only supported on x86-64 (also known as AMD64) architecture processors.
+=== Specify Configurations 
+
+After completing the previous steps, run the Docker container from the pulled image: 
+
+[source, sh, subs="attributes+"]
+----
+docker run -p 19040:19040 registry.containers.tiny.cloud/image-proxy-tiny:<VERSION>
+----
+
+This triggers `-p 19040:19040`, exposing the service on `localhost:19040`. The service runs on port `19040` 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]
+----
+2025-01-08 12:03:15 [io-compute-3] INFO  emissary - emissary
+...
+2025-01-08 12:03:16 [io-compute-blocker-3] INFO  emissary - -> Raw Config assembled from various sources: ConfigOrigin(merge of /ephox-image-proxy/ephox-image-proxy-docker-env.conf: 1,system properties,reference.conf @ jar:file:/ephox-image-proxy/ephox-image-proxy.jar!/reference.conf: 1)
+2025-01-08 12:03:16 [io-compute-blocker-3] WARN  c.e.d.config.AllowedOriginsConfig$ - No allowed-origins specified in config!
+2025-01-08 12:03:16 [io-compute-blocker-3] INFO  emissary - emissary config loaded successfully: EmissaryConfig(SdkHttpConfig(HttpConfig(100,10,10,3,HttpConfigTimeouts(10,10,10),JvmTrustModel()),None),OriginWhitelist(List(),OriginPrecision(true)),Some(10000000))
+2025-01-08 12:03:17 [io-compute-1] INFO  o.h.b.c.nio1.NIO1SocketServerGroup - Service bound to address /0:0:0:0:0:0:0:0:19040
+2025-01-08 12:03:17 [io-compute-1] INFO  o.h.blaze.server.BlazeServerBuilder - 
+  _   _   _        _ _
+ | |_| |_| |_ _ __| | | ___
+ | ' \\  _|  _| '_ \\_  _(_-<
+ |_||_\\__|\\__| .__/ |_|/__/
+             |_|
+2025-01-08 12:03:17 [io-compute-1] INFO  o.h.blaze.server.BlazeServerBuilder - http4s v0.23.27 on blaze v0.23.16 started at http://[::]:19040/
+----
+
+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.
+
+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.
+
+* link:https://www.tiny.cloud/docs/tinymce/latest/configure-common-settings-services/#proxy[proxy configuration]
+* link:https://www.tiny.cloud/docs/tinymce/latest/configure-common-settings-services/#http[http configuration]
+
+The following settings for the Image Proxy service premium server-side component are optional:
+
+* link:https://www.tiny.cloud/docs/tinymce/latest/configure-imageproxy-service/#image-proxy[image-proxy configuration]
+
+=== Run the Docker Container 
+
+The Docker container can also be run with `docker compose`. In this example, the following directory structure is assumed: 
+
+[source,sh]
+----
+tiny-image-proxy/
+└── docker-compose.yaml     # Docker Compose file to define and run the service
+└── application.conf        # Configuration file for allowed origins and other settings
+----
+
+Here is an example of the `application.conf` file with the basic configurations: 
+
+[source, conf]
+----
+ephox {
+  allowed-origins {
+    origins = [
+      "<http://example.com>",
+      "<http://good.com> ",
+      "*.my.company.org"
+    ]
+  }
+}
+----
+
+Once the application configuration file is ready, proceed with the Docker Compose setup to configure and run the service.
+
+. Create the `docker-compose.yaml` file:
+
+
+[source, yaml]
+----
+services:
+  image-proxy-tiny:
+	  image: registry.containers.tiny.cloud/image-proxy-tiny:[version]
+    ports:
+      - "19040:19040"
+    restart: always
+    init: true
+    volumes:
+      - type: bind
+        source: ./application.conf #change this to the path on your local machine
+        target: /ephox-image-proxy/ephox-image-proxy-docker-env.conf 
+        read_only: true
+----
+
+. Run the service (within the same directory where `docker-compose.yaml` was placed):
+
+
+[source, sh]
+----
+docker compose up
+----
+
+
+If the setup is correct, the initiation logs should appear as follows:
+
+
+[source, log]
+----
+ ✔ Container image-proxy-tiny-image-proxy-tiny-1  Created                                                                                                                                                                                                                                                         0.0s 
+Attaching to image-proxy-tiny-1
+image-proxy-tiny-1  | 2025-01-08 15:02:36 [io-compute-8] INFO  emissary - emissary
+image-proxy-tiny-1  | 2025-01-08 15:02:36 [io-compute-8] INFO  emissary - * External Configuration
+image-proxy-tiny-1  | 2025-01-08 15:02:36 [io-compute-8] INFO  emissary -   * External configuration via System Properties
+image-proxy-tiny-1  | 2025-01-08 15:02:36 [io-compute-blocker-8] INFO  emissary -     * parseConfigSources
+image-proxy-tiny-1  | 2025-01-08 15:02:36 [io-compute-blocker-8] INFO  emissary -       * looking up property: ephox.config.url
+image-proxy-tiny-1  | 2025-01-08 15:02:36 [io-compute-blocker-8] INFO  emissary -         -> Property not set
+image-proxy-tiny-1  | 2025-01-08 15:02:36 [io-compute-blocker-8] INFO  emissary -       * looking up property: config.url
+image-proxy-tiny-1  | 2025-01-08 15:02:36 [io-compute-blocker-8] INFO  emissary -         -> Property not set
+image-proxy-tiny-1  | 2025-01-08 15:02:36 [io-compute-blocker-8] INFO  emissary -     * parseConfigSources
+image-proxy-tiny-1  | 2025-01-08 15:02:36 [io-compute-blocker-8] INFO  emissary -       * looking up property: ephox.config.file
+image-proxy-tiny-1  | 2025-01-08 15:02:36 [io-compute-blocker-8] INFO  emissary -         -> Found value for property: /ephox-image-proxy/ephox-image-proxy-docker-env.conf
+image-proxy-tiny-1  | 2025-01-08 15:02:36 [io-compute-blocker-8] INFO  emissary -       * Parsing config defined by /ephox-image-proxy/ephox-image-proxy-docker-env.conf from property: ephox.config.file
+image-proxy-tiny-1  | 2025-01-08 15:02:36 [io-compute-blocker-8] INFO  emissary -         -> Processing file: /ephox-image-proxy/ephox-image-proxy-docker-env.conf
+image-proxy-tiny-1  | 2025-01-08 15:02:36 [io-compute-blocker-8] INFO  emissary -   * External application.conf => /opt/ephox/application.conf
+image-proxy-tiny-1  | 2025-01-08 15:02:36 [io-compute-blocker-8] INFO  emissary -     * Optional File (/opt/ephox/application.conf). Defaults to empty if file not found
+image-proxy-tiny-1  | 2025-01-08 15:02:36 [io-compute-blocker-8] INFO  emissary - * Internal Configuration
+image-proxy-tiny-1  | 2025-01-08 15:02:36 [io-compute-blocker-8] INFO  emissary -   -> No extra internal configuration specified - skipping
+image-proxy-tiny-1  | 2025-01-08 15:02:36 [io-compute-blocker-8] INFO  emissary - * Default (Reference) Configuration
+image-proxy-tiny-1  | 2025-01-08 15:02:36 [io-compute-blocker-8] INFO  emissary -   * Loading configuration files from classpath (reference.conf and integration.conf). Neither is required.
+image-proxy-tiny-1  | 2025-01-08 15:02:36 [io-compute-blocker-8] INFO  emissary - -> Raw Config assembled from various sources: ConfigOrigin(merge of /ephox-image-proxy/ephox-image-proxy-docker-env.conf: 1,system properties,reference.conf @ jar:file:/ephox-image-proxy/ephox-image-proxy.jar!/reference.conf: 1)
+image-proxy-tiny-1  | 2025-01-08 15:02:36 [io-compute-blocker-8] INFO  c.e.d.config.AllowedOriginsConfig$ - Read allowed-origins config (ignoring ports = true) as:
+image-proxy-tiny-1  |  - good.com
+image-proxy-tiny-1  |  - example.com
+image-proxy-tiny-1  | 2025-01-08 15:02:36 [io-compute-blocker-8] INFO  emissary - emissary config loaded successfully: EmissaryConfig(SdkHttpConfig(HttpConfig(100,10,10,3,HttpConfigTimeouts(10,10,10),JvmTrustModel()),None),OriginWhitelist(List(good.com, example.com),OriginPrecision(true)),Some(10000000))
+image-proxy-tiny-1  | 2025-01-08 15:02:37 [io-compute-1] INFO  o.h.b.c.nio1.NIO1SocketServerGroup - Service bound to address /0:0:0:0:0:0:0:0:19040
+image-proxy-tiny-1  | 2025-01-08 15:02:37 [io-compute-1] INFO  o.h.blaze.server.BlazeServerBuilder - 
+image-proxy-tiny-1  |   _   _   _        _ _
+image-proxy-tiny-1  |  | |_| |_| |_ _ __| | | ___
+image-proxy-tiny-1  |  | ' \\  _|  _| '_ \\_  _(_-<
+image-proxy-tiny-1  |  |_||_\\__|\\__| .__/ |_|/__/
+image-proxy-tiny-1  |              |_|
+image-proxy-tiny-1  | 2025-01-08 15:02:37 [io-compute-1] INFO  o.h.blaze.server.BlazeServerBuilder - http4s v0.23.27 on blaze v0.23.16 started at http://[::]:19040/
+----
+
+=== Next Steps 
+
+. Test the service via cURL command
+
+
+To verify that the Image Proxy service is set up and functioning correctly within the container, ensure the service is running on port `19040`. 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:19040/version
+----
+
+
+An example output is: `2.111.1`
+
+
+To confirm that a request is being sent to the Image Proxy service, use:
+
+
+[source, sh]
+----
+curl --location 'http://localhost:19040/2/image?url=https%3A%2F%2Fraw.githubusercontent.com%2Fsrikomm%2FBMP-EDITING%2Frefs%2Fheads%2Fmaster%2Fsrc%2FInputs%2Ffish.bmp' \\
+--header 'Origin: http://good.com'
+----
+
+
+Finally, to verify if a request is unauthorized and originates from an incorrect origin, use:
+
+
+[source, sh]
+----
+curl --location 'http://localhost:19040/2/image?url=https%3A%2F%2Fraw.githubusercontent.com%2Fsrikomm%2FBMP-EDITING%2Frefs%2Fheads%2Fmaster%2Fsrc%2FInputs%2Ffish.bmp' \\
+--header 'Origin: http://bad.com'
+----
+
+
+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 xref:editimage.adoc[{pluginname}] feature in the editor and call it via `tinymce.init`. If running locally on the default port `19040`, use the following settings:
+
+
+[source, js]
+----
+tinymce.init({
+  selector: 'textarea',  // change this value according to your HTML
+  toolbar: 'image',
+  plugins: 'image editimage',
+  editimage_cors_hosts: [ 'example.com', 'good.com' ],
+  editimage_proxy_service_url: "http://localhost:19040"
+});
+----
--- a/modules/ROOT/partials/docker/image-proxy-service/image-proxy-service-overview.adoc
+++ b/modules/ROOT/partials/docker/image-proxy-service/image-proxy-service-overview.adoc
@ -0,0 +1,10 @@
+[[overview]]
+== Overview
+
+The On-Premises version of link:https://www.tiny.cloud/docs/tinymce/latest/editimage/[{pluginname}] is an application that can be installed and run on the customer’s in-house servers and computing infrastructure, including a private cloud.
+
+The only requirement to run this service On-Premises is a container runtime or orchestration tool e.g. Docker, Kubernetes, Podman.
+
+A valid access token is required to access the {companyname} Cloud Docker registry and pull the Docker image. Contact link:https://www.tiny.cloud/contact/[{companyname} Support^] to request the access token.
+
+include::partial$misc/admon-dont-push-docker-images.adoc[]
--- a/modules/ROOT/partials/docker/image-proxy-service/image-proxy-service-requirements.adoc
+++ b/modules/ROOT/partials/docker/image-proxy-service/image-proxy-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 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^].