DOC-2351: On-premises Export to PDF documentation.

antora.yml

@@ -16,6 +16,11 @@ asciidoc:
     webcomponent_url: https://cdn.jsdelivr.net/npm/@tinymce/tinymce-webcomponent@2/dist/tinymce-webcomponent.min.js
     jquery_url: https://cdn.jsdelivr.net/npm/@tinymce/tinymce-jquery@2/dist/tinymce-jquery.min.js
     default_meta_keywords: tinymce, documentation, docs, plugins, customizable skins, configuration, examples, html, php, java, javascript, image editor, inline editor, distraction-free editor, classic editor, wysiwyg
+    # product docker variables
+    dockerimageexporttopdf: registry.containers.tiny.cloud/pdf-converter-tiny
+    dockerimageexporttopdfwindows: registry.containers.tiny.cloud/pdf-converter-windows-tiny
+    # document converter placeholder variables
+    exportpdf_service_url: exportpdf_service_url placeholder 
     # product variables
     productname: TinyMCE
     productmajorversion: 7

modules/ROOT/pages/individual-export-to-pdf-on-premises.adoc

@@ -1,5 +1,21 @@
-= Deploy the {productname} Export to Word service server-side component using Docker (individually licensed)
+= Deploy the {productname} {pluginname} service server-side component using Docker (individually licensed)
 :navtitle: Export to PDF
 :description: Setting up Export to PDF using Docker.
 :keywords: server-side, docker, export-to-pdf, on-premises
-:pluginname: Export to PDF
+:pluginname: Export to PDF
+
+include::partial$individually-licensed-components/export-to-pdf/export-to-pdf-overview.adoc[]
+
+include::partial$individually-licensed-components/export-to-pdf/export-to-pdf-requirements.adoc[]
+
+include::partial$individually-licensed-components/export-to-pdf/export-to-pdf-installation.adoc[]
+
+include::partial$individually-licensed-components/export-to-pdf/export-to-pdf-fonts.adoc[]
+
+include::partial$individually-licensed-components/export-to-pdf/export-to-pdf-autorization.adoc[]
+
+include::partial$individually-licensed-components/export-to-pdf/export-to-pdf-api-usage.adoc[]
+
+include::partial$individually-licensed-components/export-to-pdf/export-to-pdf-ssl-communication.adoc[]
+
+include::partial$individually-licensed-components/export-to-pdf/export-to-pdf-logs.adoc[]

modules/ROOT/partials/individually-licensed-components/export-to-pdf/export-to-pdf-api-usage.adoc

@@ -0,0 +1,42 @@
+[[api-usage]]
+== API Usage
+
+The {pluginname} On-Premises converter provides the ability to convert an HTML document to a PDF file via Restful API.
+
+The API is available on `+http://localhost:[port]+` (by default the `port` is `8080`).
+
+[NOTE]
+The REST API documentation is available at `http://localhost:[port]/docs`.
+Alternatively, refer to the specifications in link:https://exportpdf.converter.tiny.cloud/docs[https://exportpdf.converter.tiny.cloud/docs^].
+
+If the authorization for the API is enabled, provided an authorization token. More instructions can be found in the xref:individual-export-to-pdf-on-premises.adoc#authorization[authorization] section.
+
+=== Using additional HTTP headers
+
+If fetching some resources (e.g. images) used in a generated PDF requires passing an additional authorization factor in the form of additional HTTP headers:
+
+. It can be defined on the application startup by setting `EXTRA_HTTP_HEADERS` environmental variable where the value is a stringified JSON object with required headers.
+. It can be defined in a request sent to the PDF Converter API in `options`:
+
+[source, js, subs="attributes+"]
+----
+const data = {
+  html: '<p>I am a teapot</p><img src="https://secured-example-website.com/image.jpg">',
+  css: 'p { color: red; }',
+  options: {
+    extra_http_headers: {
+      authorization: 'Bearer <replace_with_your_auth_key>'
+    }
+  }
+};
+
+axios.post( '{exportpdf_service_url}', data, config )
+  .then( response => {
+    fs.writeFileSync('./file.pdf', response.data, 'binary')
+  }).catch( error => {
+    console.log( error );
+  });
+----
+
+[TIP]
+Headers defined in the application config and from the request are merged. If the same header is defined in both places, a header value from PDF options is prioritized over the value from the application config.

modules/ROOT/partials/individually-licensed-components/export-to-pdf/export-to-pdf-autorization.adoc

@@ -0,0 +1,98 @@
+[[authorization]]
+== Authorization
+
+To enable authorization, set the `SECRET_KEY` environment variable during the xref:individual-export-to-pdf-on-premises.adoc#installation[installation].
+
+If the `SECRET_KEY` variable is set, then all requests must have a header with a JWT (JSON Web Token) signed with this key. The token should be passed as a value of the `Authorization` header for each request sent to the {pluginname} REST API.
+
+[NOTE]
+If the `SECRET_KEY` is not setup during the installation, then {pluginname} On-Premises will not require any headers with tokens when sending requests to the {pluginname} REST API. However, this it is not recommend to skip the authorization when running {pluginname} On-Premises in a public network.
+
+=== Generating the token
+
+{companyname} recommends using the libraries listed on link:http://jwt.io/[jwt.io] to generate the token. The token is considered valid, when:
+
+* it is signed with the same `SECRET_KEY` as passed to the {pluginname} On-Premises instance,
+* it was created within the last 24 hours,
+* it is not issued in the future (e.i. the iat timestamp cannot be newer than the current time),
+* it has not expired yet.
+
+Tokens for the {pluginname} On-Premises do not require any additional claims such as the environment ID (which is specific for Collaboration Server On-Premises), the token can be created with an empty payload.
+
+If the specific use case involves sending requests from a backend server, then JWT tokens can be generated locally, as shown in the below request example.
+
+In the case of editor plugins or other frontend usages, a token endpoint should be created, that returns a valid JWT token for authorized users.
+
+.Example of a endpoint implementation.
+[source, js]
+----
+const express = require( 'express' );
+const jwt = require( 'jsonwebtoken' );
+
+const SECRET_KEY = 'secret_key';
+
+const app = express();
+
+app.use( ( req, res, next ) => {
+  res.setHeader( 'Access-Control-Allow-Origin', '*' );
+  res.setHeader( 'Access-Control-Allow-Methods', 'GET' );
+
+  next();
+});
+
+app.get( '/', ( req, res ) => {
+  const result = jwt.sign( {}, SECRET_KEY, { algorithm: 'HS256' } );
+
+  res.send( result );
+});
+
+app.listen( 8080, () => console.log( 'Listening on port 8080' ) );
+----
+
+=== Using editor plugins
+
+Plugins for {productname} will automatically request the token from the given `tokenUrl` variable and set the `Authorization` header when making an export request.
+
+[NOTE]
+Refer to the xref:exportpdf.adoc[{pluginname}] plugin documentation for details on adding the {pluginname} feature to the editor.
+
+=== Request example with an Authorization header
+
+The following example presents a request that generates valid JWT token and sets it as `Authorization` header:
+
+[source, js]
+----
+const fs = require( 'fs' );
+const jwt = require( 'jsonwebtoken' );
+const axios = require( 'axios' );
+
+const SECRET_KEY = 'secret';
+
+const token = jwt.sign( {}, SECRET_KEY, { algorithm: 'HS256' } );
+
+const data = {
+  html: "<p>I am a teapot</p>",
+  css: "p { color: red; }",
+};
+
+const config = {
+  headers: {
+    'Authorization': token
+  },
+  responseType: 'arraybuffer',
+};
+
+axios.post( 'http://localhost:8080/v1/convert', data, config )
+  .then( response => {
+    fs.writeFileSync('./file.pdf', response.data, 'binary');
+  }).catch( error => {
+    console.log( error );
+   });
+----
+
+`SECRET_KEY` it’s the key which has been passed to the {pluginname} On-Premises instance
+
+Please refer to the link:https://exportpdf.converter.tiny.cloud/docs[{pluginname} REST API documentation] to start using the service.
+
+[NOTE]
+If API clients like Postman or Insomnia are used, then set the JWT token as an `Authorization` header in the `Headers` tab. Do not use the built-in token authorization as this will generate invalid header with a `Bearer` prefix added to the token.

modules/ROOT/partials/individually-licensed-components/export-to-pdf/export-to-pdf-fonts.adoc

@@ -0,0 +1,65 @@
+[[fonts]]
+== Fonts
+
+During document writing, the possibility of using many different fonts can be very important to users.
+
+Using the appropriate font can change the appearance of the document and emphasize its style.
+
+{pluginname} Converter allows link:https://exportpdf.converter.tiny.cloud/docs#section/Web-Fonts[Web Fonts^] to be used, which provided the integrator with the ability to use standard operating system fonts or use custom fonts without the need to import them using CSS.
+
+Below is a list of the basic fonts included in the image:
+
+[source]
+----
+OpenSans-Bold.ttf
+OpenSans-BoldItalic.ttf
+OpenSans-ExtraBold.ttf
+OpenSans-ExtraBoldItalic.ttf
+OpenSans-Italic.ttf
+OpenSans-Light.ttf
+OpenSans-LightItalic.ttf
+OpenSans-Regular.ttf
+OpenSans-Semibold.ttf
+OpenSans-SemiboldItalic.ttf
+----
+
+However, additional fonts can be added to {pluginname} Converter in two ways:
+
+* Use Unix-like PDF-Converter image `{dockerimageexporttopdf}` and mount fonts directory to it.
+** See xref:individual-export-to-pdf-on-premises.adoc#add-custom-fonts-to-pdf-converter[Add custom fonts to PDF Converter] section.
+* Use Windows PDF-Converter image `{dockerimageexporttopdf}` and mount to it fonts directory from the Windows operating system on which the container is running.
+** See Use Windows fonts in PDF Converter section.
+
+[NOTE]
+The fonts inside the mounted volume will be installed on the docker image operating system. Only the `.ttf` and `.otf` font formats are supported. If other font formats are used, these will need to be converted to the supported format prior or use fonts such as link:https://exportpdf.converter.tiny.cloud/docs#section/Web-Fonts[Web Fonts^].
+
+[TIP]
+Ensure that the converted fonts can be installed and used on your local machine first, before installing them on the docker container.
+
+[[add-custom-fonts-to-pdf-converter]]
+=== Add custom fonts to PDF Converter
+
+If custom fonts are being used in PDF files, use the `pdf-converter` Docker image and mount the directory with the custom fonts for the PDF Converter application running on a machine with a Unix-like system (this includes Docker on Windows with a WSL backend).
+
+The `{dockerimageexporttopdf}` Docker image need to be run on a Unix-like operating system and mount the `~/your_fonts_dir:/usr/share/fonts/your_fonts_dir` volume.
+
+Launch the Docker container on Unix-like operating system example:
+
+[source, bash, subs="attributes+"]
+----
+docker run --init -v ~/your_fonts_dir:/usr/share/fonts/your_fonts_dir -p 8080:8080 -e LICENSE_KEY=[your_license_key] {dockerimageexporttopdf}:[version]
+----
+
+[[use-windows-fonts-in-pdf-converter]]
+=== Use Windows fonts in PDF Converter
+
+If using Windows fonts like Arial, Verdana, etc. in PDF files, use `pdf-converter-windows-tiny` Docker image that allows you to run the application on a machine with Windows operating system and mount fonts from the system.
+
+You just need to run `{dockerimageexporttopdf}` Docker image on Windows operating system and mount `C:\Windows\Fonts:C:\Windows\Fonts` volume.
+
+Launch the Docker container on Windows operating system example:
+
+[source, bash, subs="attributes+"]
+----
+docker run -v C:\Windows\Fonts:C:\Windows\Fonts -p 8080:8080 --env LICENSE_KEY=[your_license_key] {dockerimageexporttopdfwindows}:[version]
+----

modules/ROOT/partials/individually-licensed-components/export-to-pdf/export-to-pdf-installation.adoc

@@ -0,0 +1,98 @@
+[[installation]]
+== Installation
+
+[NOTE]
+A valid license key is needed in order to install {pluginname} On-Premises.
+link:https://www.tiny.cloud/contact/[Contact us] for a trial license key.
+
+=== Supported technologies
+
+The application is provided as a docker image by default.
+
+It can be run with any Open Container runtime tool e.g. link:https://kubernetes.io/[Kubernetes], link:https://www.redhat.com/en/technologies/cloud-computing/openshift[OpenShift], link:https://podman.io/[Podman], link:https://docs.docker.com/[Docker] and many others.
+
+Refer to the xref:individual-export-to-pdf-on-premises.adoc#requirements[Requirements guide] for more information about the hardware and software requirements to run the {pluginname} On-Premises.
+
+=== Setting up the application using a Docker container
+
+. The username and password credentials supplied by Tiny are utilized for logging into the Docker registry and retrieving the Docker image.
+. Containerize the application using `docker` or `docker-compose`.
+. Use a demo page to verify if the application works properly.
+
+==== Containerize example using docker
+
+Login to Docker registry:
+
+[source, sh, subs="attributes+"]
+----
+docker login -u [username] -p [password] registry.containers.tiny.cloud
+----
+
+Launch the Docker container:
+
+[source, sh, subs="attributes+"]
+----
+docker run --init -p 8080:8080 -e LICENSE_KEY=[your_license_key] {dockerimageexporttopdf}:[version]
+----
+
+If using authorization provide the SECRET_KEY:
+
+[source, sh, subs="attributes+"]
+----
+docker run --init -p 8080:8080 -e LICENSE_KEY=[your_license_key] -e SECRET_KEY=[your_secret_key] {dockerimageexporttopdf}:[version]
+----
+
+Read more about using authorization in the xref:individual-export-to-pdf-on-premises.adoc#authorization[authorization] section.
+
+==== Containerize example using docker-compose
+
+. Create the docker-compose.yml file:
++
+[source, yml, subs="attributes+"]
+----
+version: "3.8"
+services:
+  pdf-converter:
+    image: {dockerimageexporttopdf}:[version]
+    ports:
+      - "8080:8080"
+    restart: always
+    init: true
+    environment:
+      LICENSE_KEY: "license_key"
+      # Secret Key is optional
+      SECRET_KEY: "secret_key"
+      # Custom request origin is optional
+      CUSTOM_REQUEST_ORIGIN: "https://your_custom_origin"
+----
++
+For details on `SECRET_KEY` usage check the xref:individual-export-to-pdf-on-premises.adoc#authorization[authorization] section.
++
+. Run:
+
+[source, bash]
+----
+docker-compose up
+----
+
+[NOTE]
+====
+* Without a correct `LICENSE_KEY` the application will not start.
+** If the license is invalid, a wrong license key error will display in the logs and the application will not run.
+* It is advisable to override the SECRET_KEY variable using a unique and hard to guess string for security reasons.
+* If the specific infrastructure has strict CORS enabled, then use the `CUSTOM_REQUEST_ORIGIN` variable to set the origin of requests made by the converter. The default value is `https://pdf-internal`.
+====
+
+=== Windows fonts support
+
+If using Windows fonts like Calibri, Verdana, etc. in PDF files, use the `pdf-converter-windows-tiny` Docker image and run it on a Windows operating system.
+
+See xref:individual-export-to-pdf-on-premises.adoc#fonts[Fonts] section for more details.
+
+=== Next steps
+
+Use the link:http://localhost:8080/v1/convert[http://localhost:8080/v1/convert] endpoint to export PDF files. Check out the xref:individual-export-to-pdf-on-premises.adoc#authorization[authorization] section to learn more about tokens and token endpoints.
+
+Use the demo page available on link:http://localhost:8080/demo[http://localhost:8080/demo] to generate an example PDF file.
+
+Refer to the {pluginname} REST API documentation on link:http://localhost:8080/docs[http://localhost:8080/docs] for more details.