Reverse Proxying Highlighter

From Wikipedia: In computer networks, a reverse proxy is a type of proxy server that retrieves resources on behalf of a client from one or more servers. These resources are then returned to the client as though they originated from the server itself (or servers themselves).

There are many practical reasons why you would want to setup reverse proxy for PDF Highlighter:

It makes the highlighting service available on the same web server and default port where your application is hosted. There is no need to open port 8998 (the default port PDF Highlighter is listening on) on your server or router to allow access to Highlighter from the Internet.
Prevents cross-origin (CORS) issues when the Highlighting PDF Viewer tries to access PDF file on your main web site.
Simplifies setup if your web application is served via HTTPS.
Allows you to authorize users accessing your documents via PDF Highlighter.

Reverse proxy setup differs from one web server to another, but it generally comes down to mapping local URL-space to a remote server. Typically, you would proxy path /highlighter/ on the end-user facing HTTP server to http://localhost:8998/ (or other server where you installed the JObjects Highlighter).

Reverse Proxying in a Development Environment#

For creating an ad-hoc reverse proxy in the development environment, you can use devd - a local web server for developers. Download the latest release for your platform, extract the devd executable and you're good to go.

Assuming that your website is running on the port 8080, open a terminal (command line) window, cd to the directory where you extracted devd, and run:

devd --port=8081 /=http://localhost:8080/ /highlighter/=http://localhost:8998/

You should see something like:

29:22: Route / -> forward to http://localhost:8080/
29:22: Route /highlighter/ -> forward to http://localhost:8998/
29:22: Listening on http://devd.io:8081 (127.0.0.1:8081)

At this point you can open http://localhost:8081 and it should show your website.

As you will be accessing JObjects Highlighter on a custom path, set the serviceUrl in Highlighter's application.conf to

highlighter {
  serviceUrl = "/highlighter"
}

and restart the Highlighter service.

Now you should be able to run Highlighter demo and other examples at http://localhost:8081/highlighter/examples/

Reverse Proxying in a Production Environment#

Nginx#

Use Nginx proxy_pass directive:

location /highlighter/ {
    proxy_pass http://localhost:8998/;
}

In the context of the complete configuration file /etc/nginx/conf.d/default:

server {
    listen       80;
    server_name  localhost;
    
    location / {
      root   /usr/share/nginx/html;
      index  index.html index.htm;
    }
    
    location /highlighter/ {
      proxy_pass http://localhost:8998/;
    }
    
    #error_page  404              /404.html;
    
    # redirect server error pages to the static page /50x.html
    #
    error_page   500 502 503 504  /50x.html;
    location = /50x.html {
      root   /usr/share/nginx/html;
    }
}

Apache#

Add ProxyPass directive

ProxyPass "/highlighter/" "http://localhost:8998/"

to the VirtualHost section in your Apache HTTP Server config file.

IIS#

Kubernetes#

In the k8s environment it's more convenient, from the configuration point of view, to start JObjects Highlighter on /highlighter or other desired non-root path right away. This way ingress controller can pass along the path to the target controller without ugly path re-writes.

JObjects Highlighter internally runs on the Jetty web server. By setting the contextPath in a custom jetty-env.xml file, and mounting that over the existing one, we can control how jetty responds.

webapps/root/WEB-INF/jetty-env.xml

<Configure class="org.eclipse.jetty.webapp.WebAppContext">
        <Set name="contextPath">/highlighter</Set>
        <Call name="setAttribute">
                ...
        </Call>
</Configure>