Deployment

Deploying the server to a production environment should be relatively seamless, however some issues may come up regarding some of the topics below.

We will keep this guide up to date as more questions arise!

HTTPS#

If you are directing HTTPS traffic to the server, you must tell the client module to connect via HTTPS and WSS as well.

This is as simple as changing the http and ws prefix to https and wss.

Example

Server:

import CollabServer from '@pdftron/collab-server'

const server = new CollabServer({
  ...options
})

server.start(443) // start server on https port

Client:

import { CollabClient } from '@pdftron/collab-client'

const client = new CollabClient({
  url: 'https://myserver.com',
  subscriptionUrl: 'wss://myserver.com/subscribe',
})

Deploying on an existing server#

In the scenario where you already have a NodeJS server running, and you want to deploy the Collaboration server on the same server, you can create a reverse proxy to route requests to their intended destination.

For example, pretend you have an existing Express application with an existing API, like so:

import express from 'express'

const app = express();

app.get('/api/posts', (req, res) => {
  const posts = await getPosts();
  res.send(posts);
})

app.listen(80); // listen on port 80 (HTTP)

Now, pretend we want to add the Collaboration server to the application.

The issue that arises is that we can only serve one application on port 80, meaning we can't serve both our existing API and the collab server over HTTP.

The solution is to write a simple reverse proxy using express. This reverse proxy will forward requests to either the collab server or your existing API depending on the path.

We'll be using http-proxy-middleware to write our proxy, so start off with installing that:

yarn add http-proxy-middleware

Now, we can set up our proxy. Calls to our existing API will be prefixed with /api, and our collab server will be prefixed with /collab.

Since the proxy will be running on port 80 (HTTP), we also need to change our existing API to run on a different port.

import express from 'express'
import CollabServer from '@pdftron/collab-server';

const app = express();

/*
    Your existing server
*/
app.get('/api/posts', (req, res) => {
  const posts = await getPosts();
  res.send(posts);
})

app.listen(3000); // Change to listen on port 3000


/*
    The collab server
*/
const server = new CollabServer({
  ...serverOptions
});

server.start(8000) // start the collab server on port 8000


/*
    The proxy server
*/

const proxyApp = express();

// redirect any requests starting with '/api' to our server running on port 3000
proxyApp.use('/api', proxy.createProxyMiddleware({
  target: 'http://localhost:3000',
}))


// Redirect websocket requests starting with '/collab/subscribe' to the collab server on port 8000
proxyApp.use('/collab/subscribe', proxy.createProxyMiddleware({
  target: 'http://localhost:8000',
  pathRewrite: (path) => {
    // the collab server expects websocket requests to come with the path '/subscribe', so
    // we rewrite the path to reflect that
    return path.replace('/collab/subscribe', '/subscribe')
  },
  ws: true // this is important!
}));

// redirect all other collab requests to the root of the collab server
proxyApp.use('/collab', proxy.createProxyMiddleware({
  target: 'http://localhost:8000',
  pathRewrite: (path) => {
    return path.replace('/collab', '')
  }
}))

proxyApp.listen(80) // start the reverse proxy on port 80 (HTTP)

After the changes above, our server behaves like so:

Requests to http://yourdomain.com/api/* get redirected to port 3000, which is your existing API server
Requests to http://yourdomain.com/collab/subscribe/* get redirected to port 8000, which the collab server is listening to.
Requests to http://yourdomain.com/collab/* get redirected to port 8000, which the collab server is listening to.

Now, when setting up the client, you just need to include these paths for the url and subscriptionUrl params

const client = new CollabClient({
  url: 'http://yourdomain.com/collab',
  subscriptionUrl: 'ws://yourdomain.com/collab/subscribe',
})