Page tree
Skip to end of metadata
Go to start of metadata

Some features require the deployment of server-side components onto a Java Servlet 3.0 compatible application server. We currently support Jetty, Apache Tomcat, and WebSphere Application Server.

The following server-side components are packaged with the Textbox.io SDK:

ComponentFileDescription
Spell Checkingephox-spelling.warSpell checking service for JavaScript editors.
Extended Image Editing (Image Proxy)ephox-image-proxy.warImage proxy to allow editing images from the web.
Hyperlink Checkingephox-hyperlinking.warHyperlink validity checking service.
Enhanced Media Embedephox-hyperlinking.warTransform hyperlinks into rich representations of the target location.

Allowed Origins Service Deprecated

Note: The "Allowed Origins" service (ephox-allowed-origins.war) has been deprecated. Trusted domains should now be specified directly in the configuration file.

This guide will help you get these server-side components up and running.

1. Install a Java Application Server

If you've already got a Java application server like Jetty or Tomcat installed, skip to Step 2.

If you don't, pick either Tomcat or Jetty and install one of these with their default settings using the instructions on their website.

 

Memory Requirement

Please ensure that you configure your Java Server (Tomcat/Jetty etc) with a minimum of 4GB.
Please refer to the Out of Memory Errors troubleshooting page if you require instructions on how to explicitly define how much RAM will be allocated to your Java server.


2. Deploy Server-side Components

Deploy all the WAR files that came packaged with the Textbox.io SDK to your newly installed Java application server:

  • ephox-spelling.war
  • ephox-image-proxy.war
  • ephox-hyperlinking.war

The easiest way to deploy these files is to copy them into the webapps directory of your Tomcat/Jetty installation and then restart the application server.

More information can be found in the documentation of your chosen application server:

Deploying applications with Tomcat 9.0 
Deploying applications with Jetty 

3. Create a configuration file

 

Choice of editor

Use a plain text editor (such as gedit, vim, emacs or notepad) when creating or editing the application.conf file. Do not use word processors like Microsoft Word or Evernote as these can insert extra characters which make the file unreadable to the server-side components.

The Textbox.io server-side components require a configuration file to function correctly. By convention, this file is named application.conf.

The SDK comes packaged with an example configuration file (examples/sample_application.conf) that can be used as a reference guide. You can use this example file (after modifying it with your settings).  We recommend that you make a backup of the file before editing it.

This configuration file will require you to enter at least the following information:

  • allowed-origins - the domains allowed to communicate with the server-side editor features. This is required by all server-side components.

Some server-side components require additional configuration which can be found in their individual documentation:

allowed-origins (required) 

Textbox.io editor instances make use of the server-side components by performing a cross-origin HTTP request. These requests are subject to a form of HTTP access control called Cross-Origin Resource Sharing (CORS). CORS is built into web browsers and is not a feature of Textbox.io's server side components. A detailed explanation of CORS can be found on the Mozilla Developer Network.

The allowed-origins element configures a list of all values that can be expected by the server-side components in a HTTP Origin header from your Textbox.io instances (see the Mozilla Developer Network for more information on the HTTP Origin header). In short, you'll need to supply a list of all the URLs that your Textbox.io instances will be served from without the path information.

This is best illustrated with some examples:

 

If users load Textbox.io from the following URLs:

  • http://server.example.com/editor.php
  • http://server.example.com/subpage/editor.php

Add http://server.example.com to the allowed-origins list.

 

If users load Textbox.io from the following URLs:

  • https://server.example.com/editor.php
  • http://server.example.com/subpage/editor.php

Add http://server.example.com and https://server.example.com to the allowed-origins list.

 

If users load Textbox.io from the following URLs:

  • https://server.example.com/editor.php
  • https://server.example.com/

Add https://server.example.com to the allowed-origins list.

 

If users load Textbox.io from the following URLs:

  • http://oneserver.example.com/editor.php
  • http://twoserver.example.com/subpage/editor.php

Add http://oneserver.example.com and http://twoserver.example.com to the allowed-origins list.

 

Note

If some of your URLs include a port then add an entry with and without the port. The value of the Origin header may be different across browsers. Add both to be safe.

If users load Textbox.io from the following URLs:

  • http://server.example.com:8080/editor.php

Add http://server.example.com:8080 and http://server.example.com to the allowed-origins list.

 

If users load Textbox.io from the following URLs:

  • https://server.example.com:9000/editor.php

Add https://server.example.com:9000 and https://server.example.com to the allowed-origins list.

elementallowed-originsStores CORS setup information

 

attributeorigins

An array of strings containing all possible values of the HTTP Origin header the server-side components can expect.

Example:

allowed-origins example
ephox {
	allowed-origins {
		origins = [ "http://myserver", "http://myserver.example.com", "http://myserver:8080", "http://myotherserver", "http://myotherserver:9090", "https://mysecureserver" ]
	}
}

Wildcard support

The * wildcard character matches any value. Wildcards are supported in the following parts of entries in the allowed-origin list:

  1. The scheme (e.g. *://mydomain.com). Omitting the scheme entirely is equivalent (e.g. mydomain.com).
  2. The port (e.g. http://mydomain.com:*).
  3. As a prefix of the domain (e.g. http://*.mydomain.com).
  4. Any combination of scheme, port, and domain prefix (e.g. *://*.mydomain.com:*).
  5. As the only character (e.g. *). This will allow any Origin to access the server-side components.
  6. As the only character after the scheme (e.g. https://*). This will allow any Origin serving Textbox.io from a HTTPS page to access the server-side components.

 

Wildcards

Options 5 and 6 allow a broad set of origins access to the server-side components and are not recommended for production deployments.

 

 

allowed-origins with wildcards example
ephox {
	allowed-origins {
		origins = [ "http://myserver:*", "*://myotherserver.example.com", "*://*.mydomain.example.com:*" ]
	}
}

Troubleshooting Origins

If you missed an Origin or specified an Origin incorrectly, Textbox.io features that rely on the server-side components will not work from that Origin. If you observe that requests to the server-side components are failing or features are unavailable and you're not sure why, refer to the troubleshooting information about Investigating Using the Browser's Network Tools.

This element enables or disables the hyperlinking feature. Valid values are true and false. If not set, the service is enabled by default.

This element configures the hyperlinking service's built-in cache. When a hyperlink is checked and confirmed valid, the result is cached to save unnecessary network traffic in the future. Default settings are automatically configured, meaning these settings are optional.

 

The capacity attribute sets the capacity of the cache. The default setting is 500.

The timeToLiveInSeconds attribute sets the time-to-live of elements of the cache, measured in seconds. The default setting is 86400 seconds, which is one day.

The timeToIdleInSeconds attribute sets the time-to-idle of elements of the cache, measured in seconds. The default setting is 3600 seconds, which is one hour.

elementlink-checking.cacheStores cache settings for the hyperlink checker.
attributecapacity

An integer defining the maximum number of elements stored in the cache at any one time.

attribute
timeToLiveInSeconds
An integer defining the time-to-live of the cache, measured in seconds. This is the maximum total amount of time that an element is allowed to remain in the cache.
attribute
timeToIdleInSeconds
An integer defining the time-to-idle of the cache, measured in seconds. This is the maximum amount of time that an element will remain in the cache if it is not being accessed.

 Example

link-checking Example
ephox {
	link-checking {
		enabled = true
		cache {
			capacity = 500
			timeToLiveInSeconds = 86400
			timeToIdleInSeconds = 3600
		}
	}
}

proxy (optional)

This element configures use of an HTTP proxy for outgoing HTTP/HTTPS requests made by the server-side components.

Default proxy settings are picked up from JVM system properties, usually provided on the command line, as defined in "Networking Properties for Java". The system properties http.proxyHost, http.proxyPort, http.nonProxyHosts, https.proxyHost, https.proxyPort are recognized as well as http.proxyUser and http.proxyPassword to support authenticating proxies.

This optional proxy element provides an alternative to providing proxy settings as JVM system properties, or to override system properties.

elementproxyStores HTTP outgoing proxy settings for the server-side components.
attributehttp.proxyHost

A string defining the host name of the proxy for plain HTTP (not HTTPS) connections. (Mandatory)

attribute
http.proxyPort
An integer defining the port number of the proxy for plain HTTP (not HTTPS) connections. (Mandatory)
attribute
http.nonProxyHosts
A list of strings separated by vertical lines ("|") listing hosts and domains to be excluded from proxying, for both plain HTTP and HTTPS connections. The strings can contain asterisks ("*") as wildcards. (Optional, defaults to "localhost|127.*|[::1]" if not set.)
attribute
https.proxyHost
A string defining the host name of the proxy for HTTPS connections. (Optional)
attribute
https.proxyPort
An integer defining the port number of the proxy for HTTPS connections. (Optional)
attribute
http.proxyUser
Username for authenticating to both the HTTP and HTTPS proxy. (Optional)
attribute
http.proxyPassword
Password for authenticating to both the HTTP and HTTPS proxy. (Optional)

Example

proxy Example
ephox {
	proxy {
		http.proxyHost = someproxy.example.com
		http.proxyPort = 8080
		https.proxyHost = someproxy.example.com
		https.proxyPort = 8080
		http.nonProxyHosts = localhost|*.example.com
	}
}

http (optional) 

elementhttpHTTP Configuration for linkchecking and media embedding.

 

attributemax-redirects

The maximum number of redirects that will be followed to check a hyperlink or retrieve open graph details from that resource. The default value is 10 redirects before giving up on the resource.

attributerequest-timeout-secondsAn integer defining the number of seconds to allow HTTP requests to take. Default: 10
attributetrust-all-cert

A boolean indicating whether to bypass SSL security and indiscriminately trusts all SSL certificates. Default: false

Some server-side components make outbound HTTP and HTTPS connections. These include Link Checker, Enhanced Media Embed and Image Tools Proxy. In an evaluation or pre-production environment, you might want to test these features against resources with untrusted SSL certificates such as in-house servers with self-signed SSL certificates. In these circumstances, it is possible to bypass all SSL security.

This is not recommended for production environments.

trust-all-cert-example
ephox {
    http {
        trust-all-cert = true
    }
}

There are some additional http settings that apply to the hyperlinking service when it is following HTTP redirects (for link checks and open graph style embeds) as well as the image proxy service.

redirects example
ephox {
    http {
        max-redirects = 20
        request-timeout-seconds = 10
    }
}

image-proxy (optional) 

The image proxy service has some optional configuration to set a maximum size for images proxied. Images beyond this size it will not be proxied. Please note that the http.request-timeout-seconds above also applies to requests made by the image proxy service.

elementimage-proxy

Configures image proxy behaviour.

attributesize-limit

An integer defining the maximum allowed image size in bytes. Default: 10000000

redirects example
ephox {
    image-proxy {
        size-limit = 10000000
    }
}


4. Pass the configuration file to the Java application server

HTTP Proxy

If you are relying on an HTTP proxy for outgoing HTTP/HTTPS connections to the Internet, consider configuring use of the proxy by the application server by setting JVM system properties at this point. These can be set in the same manner as config.file using the instructions below (using the -D option to the java command). Please refer to "Networking Properties for Java" for details. The system properties http.proxyHost, http.proxyPort, http.nonProxyHosts, https.proxyHost, https.proxyPort are recognized as well as http.proxyUser and http.proxyPassword to support authenticating proxies.

Alternatively, use of a proxy for server-side components can be set directly in their configuration file as discussed above.

Tell the services about the configuration file by setting the config.file JVM system property to the absolute path of the configuration file. The exact method for doing this varies depending on your operating system, application server and whether the application server is being run as a system service. The authoritative reference for configuring any application server is the vendor documentation, but we'll do our best to get you started below.

Windows

All Windows examples will assume the name of your configuration file is application.conf and it is located in the directory C:\config\file\location\. You'll need to set the JVM system property -Dconfig.file=C:\config\file\location\application.conf.

Tomcat

From the command line

The following assumes you've downloaded the Tomcat 9.0 zip archive from the Tomcat website, unpacked it and you're working from the unpacked Tomcat directory.

Create or edit the script .\bin\setenv.bat to contain the following line:

Example setenv.bat
set "CATALINA_OPTS= -Dconfig.file=C:\config\file\location\application.conf"

There should only be a single line in this file defining the CATALINA_OPTS environment variable.

You may also need to add another line with the path to your Java Runtime Environment installation (replace with the actual path on your system) such as:

Example setenv.bat
set "JRE_HOME=C:\Program Files\Java\jre1.8.0_131"

After editing setenv.bat, run the following command to start Tomcat:

Starting Tomcat
.\bin\startup.bat

For further information see the documentation on running Tomcat 9.0.

As a Windows service

If you download the Windows installer, Tomcat 9.0 will always be installed as a Windows system service. See the notes on Windows setup for Tomcat 9.0 and the instructions for setting JVM system properties in the Tomcat 9.0 Windows Service HOW-TO.

As a minimal example, if the installer installed Tomcat to C:\Program Files\Apache Software Foundation\Tomcat 9.0\ (default option):

 

  • Run C:\Program Files\Apache Software Foundation\Tomcat 9.0\bin\Tomcat9w which opens the Apache Tomcat 9.0 Tomcat9 Properties dialog box
  • Select the Java tab
  • Add the following line to Java Options:
Java Options
-Dconfig.file=C:\config\file\location\application.conf

For other versions of Tomcat on Windows, check the Tomcat documentation for that version.

Jetty

From the command line

If you're following the instructions for Starting Jetty for Jetty 9.4.5, the path to the configuration file can simply be supplied as a command option:

Starting Jetty
java -D"config.file=C:\config\file\location\application.conf" -jar C:\jetty\install\directory\start.jar

For other versions of Jetty on Windows, check the Jetty documentation for that version.

As a Windows service

Follow the instructions in Startup via Windows Service for Jetty 9.4.5. Remember to append the following snippet to the line beginning with  set PR_JVMOPTIONS in your install-jetty-service.bat script:

Append "set PR_JVMOPTIONS" line in install-jetty-service.bat
;-Dconfig.file="C:\config\file\location\application.conf"

Note

Check the install-jetty-service.bat has the correct paths to your Java installation. The service will fail to start with some rather unhelpful errors if the paths are incorrect.

For other versions of Jetty on Windows, check the Jetty documentation for that version.

Linux

All Linux examples will assume the name of your configuration file is application.conf and it is located in the directory /config/file/location/. You'll need to set the JVM system property -Dconfig.file=/config/file/location/application.conf.

Note

If the path to your application.conf file has spaces in it, you must ensure you prefix each white space with an escape character (\).

Example:  -Dconfig.file=/config/file/location/with/white\ space/application.conf

Tomcat and/or Jetty can be obtained via the package manager for many Linux distributions. The commands for starting the service and the location of the configuration files will vary across distributions. If you installed an application server via the package manager, follow your distribution's documentation for configuring it.

 Tomcat

The following assumes you've downloaded Tomcat 9.0 from the Tomcat website and unpacked the archive to /opt/tomcat.

For other versions of Tomcat on Linux, check the Tomcat documentation for that version.

If you've obtained Tomcat from your distribution's package manager, refer to your distribution's documentation for Tomcat.

From the command line

Create or edit the script /opt/tomcat/bin/setenv.sh to contain the following line:

Example setenv.sh
CATALINA_OPTS=" -Dconfig.file=/config/file/location/application.conf"

There should only be a single line in this file defining the CATALINA_OPTS environment variable.

After editing setenv.sh, run the following command to start Tomcat:

Starting Tomcat
/opt/tomcat/bin/startup.sh

For further information see the documentation on running Tomcat 9.0.

Jetty

The following assumes you've downloaded Jetty 9.4.5 from the Jetty website and unpacked the archive to /opt/jetty.

For other versions of Jetty on Linux, check the Jetty documentation for that version.

If you've obtained Jetty from your distribution's package manager, refer to your distribution's documentation for Jetty.

From the command line

The path to the configuration file can simply be supplied as a command option:

Starting Jetty
java -Dconfig.file="/config/file/location/application.conf" -jar /opt/jetty/start.jar

As a Linux service

Assuming you've followed the instructions to Startup a Unix Service using jetty.sh for Jetty 9.4.5, edit /etc/default/jetty and add the line:

Example /etc/default/jetty
JETTY_ARGS=" -Dconfig.file=/config/file/location/application.conf"

There should only be a single line in this file defining the JETTY_ARGS variable.

5. Restart the Java application server

After you've completed the steps on this page to Deploy server-side components, Create a configuration file and Pass the configuration file to the Java application server, the application server may need to be restarted to pick up all your changes. Turn it off and on again now, just to be safe.

6. Set up editor client instances to use the server-side functionality

Now that the server-side components deployed and running, you'll need to tell your Textbox.io instances where to find them:

  • Set the spelling.url configuration property to the URL of the deployed server-side spelling component.
  • Set the images.editing.proxy configuration property to the URL of the deployed server-side image proxy component. Note that this URL must include the full path as shown below, including the /image path.
  • Set the links.validation.url  and links.embed.url configuration properties to the URL of the deployed server-side link-checking and enriched media embed component.

This example assume your Java application server is running on port 80 (http) on yourserver.example.com and that all the server-side components are deployed to the same Java application server. Replace yourserver.example.com with the actual domain name or IP address of your server.

Example

Textbox.io Client Config
var config = {
	spelling : {
		url: 'http://yourserver.example.com/ephox-spelling/' // Spelling service base URL
	},
	images : {
        editing : {
		    proxy: 'http://yourserver.example.com/ephox-image-proxy/image' // Image proxy service URL
        }
	},
    links : {
        validation : {
            url : 'http://yourserver.example.com/ephox-hyperlinking/' // Link-Checking service URL
        }
    },
    links : {
        embed : {
            url : 'http://yourserver.example.com/ephox-hyperlinking/' // Enriched Media Embed service URL
        }
    } 
 };
 
var editor = textboxio.replace('#id', config);

 

links.embed.url 

  • No labels