Textbox.io 2.x Documentation : Installation and Setup

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:

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.

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

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:

• Enhanced Media Embed

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.

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.

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.

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.

link-checking.enabled (optional)

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

link-checking.cache (optional)

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.

timeToLiveInSeconds

timeToIdleInSeconds

 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.

http.proxyPort

http.nonProxyHosts

https.proxyHost

https.proxyPort

http.proxyUser

http.proxyPassword

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) 

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.

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.

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.

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

4. Pass the configuration file to the Java application server

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:

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:

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

After editing setenv.bat, run the following command to start 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:

-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:

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

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:

;-Dconfig.file="C:\config\file\location\application.conf"

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.

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:

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:

/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:

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:

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

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