Skip to content

Commit

Permalink
DOC-2339: On-premises documentation for document converters. (#3180)
Browse files Browse the repository at this point in the history 
* DOC-2339: On-premises documentation for document converters.

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

* Update modules/ROOT/pages/individual-export-to-word-on-premises.adoc

* Update modules/ROOT/pages/individual-import-from-word-on-premises.adoc

* DOC-2351: On-premises `Export to PDF` documentation. (#3182)

* DOC-2351: On-premises export to pdf documentation.

* Update modules/ROOT/partials/individually-licensed-components/export-to-pdf/export-to-pdf-nightly-releases.adoc

* DOC-2351: update docker img with variable replacement.

* Update antora.yml

* DOC-2351: remove nightly builds, update variable for docker.

* DOC-2351: copy edits, and initial cleanup.

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

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

* Updating antora.yml - Added another parameter

Co-authored-by: Karl Kemister-Sheppard <[email protected]>

* Update export-to-pdf-fonts.adoc - corrected the file name

* Update export-to-pdf-fonts.adoc - image name correction

* Update export-to-pdf-installation.adoc - content changes

* Update export-to-pdf-installation.adoc - change in instructions

* Update export-to-pdf-installation.adoc - updated image name

* Update export-to-pdf-installation.adoc - corrections made to yml file

* Update export-to-pdf-installation.adoc - removed <> for license key

* Update modules/ROOT/partials/individually-licensed-components/export-to-pdf/export-to-pdf-requirements.adoc

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

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

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

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

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

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

* Update modules/ROOT/partials/individually-licensed-components/export-to-pdf/export-to-pdf-logs.adoc

* Update modules/ROOT/partials/individually-licensed-components/export-to-pdf/export-to-pdf-overview.adoc

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

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

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

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

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

* Update modules/ROOT/partials/individually-licensed-components/export-to-pdf/export-to-pdf-requirements.adoc

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

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

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

---------

Co-authored-by: shirqa <[email protected]>

* DOC-2352: On-premises `Import from Word and Export to Word` documentation. (#3187)

* DOC-2352: On-premises Import from Word and Export to Word documentation.

* Apply suggestions from code review

Updated content to reflect correct image names and also added login prerequisite details

* Update import-from-word-and-export-to-word-overview-on-premises.adoc - content alignment

* Update modules/ROOT/partials/individually-licensed-components/import-from-word-and-export-to-word/import-from-word-and-export-to-word-logs-on-premises.adoc

* Update modules/ROOT/partials/individually-licensed-components/import-from-word-and-export-to-word/import-from-word-and-export-to-word-overview-on-premises.adoc

* Update modules/ROOT/partials/individually-licensed-components/import-from-word-and-export-to-word/import-from-word-and-export-to-word-overview-on-premises.adoc

* Update modules/ROOT/partials/individually-licensed-components/import-from-word-and-export-to-word/import-from-word-and-export-to-word-requirements-on-premises.adoc

* Update modules/ROOT/partials/individually-licensed-components/import-from-word-and-export-to-word/import-from-word-and-export-to-word-installation-on-premises.adoc

* Update modules/ROOT/partials/individually-licensed-components/import-from-word-and-export-to-word/import-from-word-and-export-to-word-logs-on-premises.adoc

* Update modules/ROOT/partials/individually-licensed-components/import-from-word-and-export-to-word/import-from-word-and-export-to-word-installation-on-premises.adoc

* Update modules/ROOT/partials/individually-licensed-components/import-from-word-and-export-to-word/import-from-word-and-export-to-word-logs-on-premises.adoc

* Update modules/ROOT/partials/individually-licensed-components/import-from-word-and-export-to-word/import-from-word-and-export-to-word-api-usage-on-premises.adoc

* Update modules/ROOT/partials/individually-licensed-components/import-from-word-and-export-to-word/import-from-word-and-export-to-word-api-usage-on-premises.adoc

* Update modules/ROOT/partials/individually-licensed-components/import-from-word-and-export-to-word/import-from-word-and-export-to-word-autorization-on-premises.adoc

* Update modules/ROOT/partials/individually-licensed-components/import-from-word-and-export-to-word/import-from-word-and-export-to-word-autorization-on-premises.adoc

* Update modules/ROOT/partials/individually-licensed-components/import-from-word-and-export-to-word/import-from-word-and-export-to-word-overview-on-premises.adoc

* Update modules/ROOT/partials/individually-licensed-components/import-from-word-and-export-to-word/import-from-word-and-export-to-word-overview-on-premises.adoc

---------

Co-authored-by: shirqa <[email protected]>

---------

Co-authored-by: shirqa <[email protected]>
  • Loading branch information
@kemister85 @ShiridiGandham
kemister85 and ShiridiGandham authored Apr 15, 2024
1 parent 1d592ef commit 93d7ffe
Show file tree
Hide file tree
Showing 19 changed files with 1,145 additions and 0 deletions.
6 changes: 6 additions & 0 deletions antora.yml
View file
Original file line number Diff line number Diff line change
Expand Up @@ -16,6 +16,12 @@ 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
dockerimageimportfromwordexporttoword: registry.containers.tiny.cloud/docx-converter-tiny
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
Expand Down
2 changes: 2 additions & 0 deletions modules/ROOT/nav.adoc
View file
Original file line number Diff line number Diff line change
Expand Up @@ -136,6 +136,8 @@
**** Individually licensed plugin services
***** xref:individual-hyperlinking-container.adoc[Hyperlinking 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]
*** Configure the server-side components
**** xref:configure-required-services.adoc[Required configuration]
**** xref:configure-common-settings-services.adoc[Optional common settings]
Expand Down
21 changes: 21 additions & 0 deletions modules/ROOT/pages/individual-export-to-pdf-on-premises.adoc
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,21 @@
= 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

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[]
19 changes: 19 additions & 0 deletions modules/ROOT/pages/individual-import-from-word-and-export-to-word-on-premises.adoc
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,19 @@
= Deploy the {productname} {pluginname} service server-side component using Docker (individually licensed)
:navtitle: Import from Word and Export to Word
:description: Setting up Import from Word and Export to Word using Docker.
:keywords: server-side, docker, import-from-word, export-to-word, on-premises
:pluginname: Import from Word and Export to Word

include::partial$individually-licensed-components/import-from-word-and-export-to-word/import-from-word-and-export-to-word-overview-on-premises.adoc[]

include::partial$individually-licensed-components/import-from-word-and-export-to-word/import-from-word-and-export-to-word-requirements-on-premises.adoc[]

include::partial$individually-licensed-components/import-from-word-and-export-to-word/import-from-word-and-export-to-word-installation-on-premises.adoc[]

include::partial$individually-licensed-components/import-from-word-and-export-to-word/import-from-word-and-export-to-word-autorization-on-premises.adoc[]

include::partial$individually-licensed-components/import-from-word-and-export-to-word/import-from-word-and-export-to-word-api-usage-on-premises.adoc[]

include::partial$individually-licensed-components/import-from-word-and-export-to-word/import-from-word-and-export-to-word-ssl-communication-on-premises.adoc[]

include::partial$individually-licensed-components/import-from-word-and-export-to-word/import-from-word-and-export-to-word-logs-on-premises.adoc[]
42 changes: 42 additions & 0 deletions ...als/individually-licensed-components/export-to-pdf/export-to-pdf-api-usage.adoc
View file
Original file line number Diff line number Diff line change
@@ -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.
97 changes: 97 additions & 0 deletions .../individually-licensed-components/export-to-pdf/export-to-pdf-autorization.adoc
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,97 @@
[[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.


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.
65 changes: 65 additions & 0 deletions ...artials/individually-licensed-components/export-to-pdf/export-to-pdf-fonts.adoc
View file
Original file line number Diff line number Diff line change
@@ -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-tiny` 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]
----
98 changes: 98 additions & 0 deletions .../individually-licensed-components/export-to-pdf/export-to-pdf-installation.adoc
View file
Original file line number Diff line number Diff line change
@@ -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-tiny:
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.
Loading

0 comments on commit 93d7ffe

Please sign in to comment.