Setting Up Review for Office Documents¶

Our Document Review allows you to review:

Microsoft Office documents (Word, Excel, PowerPoint)
OpenOffice/LibreOffice documents (Writer, Calc, Impress)
Google Workspace documents (Docs, Sheets, Slides)
PDF documents

PDF review works right out of the box. For Office documents, we convert the uploaded documents to PDFs and display the PDFs for review. This requires some initial setup.

There are two components that need to be set up:

A message broker. RabbitMQ is the recommended message broker, though any of Celery’s supported brokers should work.

If you already have a message broker set up, you can use it here. Follow the steps below for using an existing RabbitMQ instance.
At least one instance of Doc Converter, our document conversion microservice.

If you’ve set up Review Bot before, this process is very similar.

There are two different ways that you can set up the components needed for reviewing Office Documents:

Launching the Doc Converter image itself using docker run.
Launching Doc Converter along with a message broker and/or other services using docker-compose.

Once the necessary components are installed, you’ll need to configure the Document Review feature.

After that, you’ll be ready to start reviewing documents!

Using Docker Run¶

Set Up a Message Broker¶

First, you need to have RabbitMQ (or another compatible message broker) configured and ready. The message broker can be installed on the Review Board server or on another system, depending on your needs. You can use an existing Docker image or install a broker manually. Refer to the broker’s documentation for installation instructions.

Here is an example of setting up and running a RabbitMQ Docker container:

$ docker pull rabbitmq:3-management
$ docker run -P \
      --hostname rabbitmq \
      --name powerpack-docconverter-rabbitmq \
      -e RABBITMQ_DEFAULT_VHOST=docconverter-vhost \
      -e RABBITMQ_DEFAULT_USER=docconverter \
      -e RABBITMQ_DEFAULT_PASS=pass123 \
      -e RABBITMQ_ERLANG_COOKIE=somecookie \
      rabbitmq:3-management

This is just an example, in practice you’ll need to set your own values. We’ll go over the configurations for these in detail below.

Use an Existing Message Broker¶

Or, if you already have a message broker (for example, if you’re using Review Bot), you can use that.

For an existing RabbitMQ instance, you will need to to create a separate virtual host that the Doc Converter workers will connect to, and optionally a separate user.

Run these steps in your RabbitMQ instance to create a new user and virtual host:

$ rabbitmqctl add_user 'docconverter' 'pass123'
$ rabbitmqctl add_vhost docconverter-vhost
$ rabbitmqctl set_permissions --vhost docconverter-vhost docconverter ".*" ".*" ".*"

You can then follow the rest of the steps below, making sure to replace the hostname and port used in the examples with the hostname and port for your RabbitMQ instance.

Set Up Doc Converter¶

To set up and run a Doc Converter Docker container, run:

$ docker pull beanbag/docconverter:latest
$ docker run -P \
      --name docconverter \
      -e BROKER_URL=amqp://docconverter:password123@rabbitmq:5672/docconverter-vhost \
      -v /path/to/fonts:/usr/local/share/fonts/custom:ro \
      beanbag/docconverter:latest

See below for how to configure the values used in the examples above.

Setting your own values¶

The values used in the examples above need to be set to your own configuration and security requirements. We’ll go through the settings and describe how they should be set:

hostname

The hostname for the RabbitMQ container.

RABBITMQ_DEFAULT_VHOST

The RabbitMQ default virtual host to use for Doc Converter.

RABBITMQ_DEFAULT_USER

The RabbitMQ default user to use for Doc Converter.

RABBITMQ_DEFAULT_PASS

The RabbitMQ default user password to use for Doc Converter. Use a strong password!

RABBITMQ_ERLANG_COOKIE

The RabbitMQ Erlang cookie to use for Doc Converter. Use a secret string of up to 255 alphanumeric characters.

BROKER_URL

The broker URL for connecting to the message broker. Change this according to your RabbitMQ and Docker variables above. The URL should be in the following format: amqp://[user]:[password]@[hostname]:[port]/[vhost]

-v /path/to/fonts:/usr/local/share/fonts/custom:ro

An optional volume mount for custom fonts.

Doc Converter ships with open-source fonts that cover most document styles. However, if your documents use proprietary fonts such as Microsoft fonts, you may notice some slight visual differences from how they appear in Microsoft Office.

You can make fonts available to Doc Converter by mounting a directory containing the font files into the container. Replace /path/to/fonts with the path to a directory that contains your font files. If you don’t need custom fonts you can remove this line entirely.

Important

Any time new fonts are put into the directory, the Doc Converter container must be restarted to apply the fonts to the font cache.

Once you’ve ran the commands with your own values, you can move on to configuring the Document Review feature.

Using Docker Compose¶

docker-compose can help you define and launch all the services needed for Document Review.

Here is an example docker-compose.yaml for launching RabbitMQ and a Doc Converter instance. There are instructions on how to tailor this file to your own configuration and security requirements provided in the comments:

docker-compose.yaml¶

# Example docker-compose configuration for Doc Converter and RabbitMQ,
# to be used with Power Pack and Review Board.
#
# Please note, this file is meant to be used as an example! You will need
# to change some settings first. See the instructions.
#
#
# Instructions
# ============
#
# 1. Copy the following to a new directory:
#
#    * docker-compose.yaml (based on this file)
#
# 2. Change some of the environment variables below to something secure.
#
#    See RABBITMQ_DEFAULT_PASS, RABBITMQ_ERLANG_COOKIE, BROKER_URL, and
#    the fonts volume.
#
# 3. Run: docker-compose up
#
# 4. Go to your Review Board site, enable the Doc Review feature in the
#    Power Pack configuration page and set the broker URL there to the
#    same BROKER_URL used here.

version: '3.7'

services:

# The message broker used for communication between Doc Converter and
# Review Board. RabbitMQ is recommended, but any Celery compatible message
# broker will work.
rabbitmq:
   image: rabbitmq:3-management
   restart: always

   # The hostname for the RabbitMQ container.
   #
   # This will be used in the broker URL.
   hostname: rabbitmq
   environment:
      # The RabbitMQ default virtual host to use for Doc Converter.
      - RABBITMQ_DEFAULT_VHOST=docconverter-vhost

      # The RabbitMQ default user to use for Doc Converter.
      - RABBITMQ_DEFAULT_USER=docconverter

      # The RabbitMQ default user password to use for Doc Converter.
      #
      # CHANGEME: Use a strong password!
      - RABBITMQ_DEFAULT_PASS=pass123

      # The RabbitMQ Erlang cookie to use for Doc Converter.
      #
      # CHANGEME: Use a secret string of up to 255 alphanumeric characters.
      - RABBITMQ_ERLANG_COOKIE=somecookie

   ports:
      # The port for connecting to the RabbitMQ service.
      - 5672:5672

   healthcheck:
      test: ['CMD', 'rabbitmqctl', 'status']
      interval: 5s
      timeout: 20s
      retries: 5

# The Doc Converter service.
docconverter:
   image: beanbag/docconverter:latest
   restart: always
   depends_on:
      rabbitmq:
      condition: service_healthy

   # The broker URL for connecting to the message broker.
   #
   # CHANGEME: Change this according to your RabbitMQ and Docker variables
   #           above. The URL should be in the following format:
   #           amqp://[user]:[password]@[hostname]:[port]/[vhost]
   environment:
      - BROKER_URL=amqp://docconverter:pass123@rabbitmq:5672/docconverter-vhost

   # [Optional] Mount custom fonts.
   #
   # If your documents use proprietary fonts, such as Microsoft fonts,
   # you can make them available to Doc Converter by mounting a directory
   # containing the font files into the container.
   #
   # IMPORTANT: Any time new fonts are put into the directory, the Doc
   #            Converter container must be restarted to apply the fonts to
   #            the font cache.
   #
   # CHANGEME: Replace /path/to/fonts with the path to a directory that
   #           contains your font files. If you don't need custom fonts
   #           you can remove this volume entirely.
   volumes:
      - /path/to/fonts:/usr/share/fonts/custom:ro

Note

Make sure to use the publicly-resolvable domain and exposed RabbitMQ port for the server running this Docker environment! The internal broker URLs shown above are only valid within the Docker environment.

To bring up the environment, run:

$ docker-compose up

You could also launch these services alongside your Review Board server. See our other sample docker-compose.yaml files for an example.

Once you’ve tailored the docker-compose.yaml to your own values and brought up the environment, you can then move on to configuring the Document Review feature.

Configure the Document Review Feature¶

This is the last bit of setup needed to get Document Review for Office documents going:

Go to the Extensions page.

This can be found in Administration UI -> Extensions.
Go to the Power Pack configuration page.

Look for Review Board Power Pack and click Configure.
Under Manage Features, click on Set up document review to go to its settings page.

Admin UI for configuring Document Review, showing the AMQP broker URL field, service connection status, and a list of running Doc Converter instances.

You’ll need to set the Broker URL to the URL of your RabbitMQ or other Celery broker. The URL should be in the following format and configured to your RabbitMQ and Docker variables: amqp://[user]:[password]@[hostname]:[port]/[vhost]

Following the examples above, you would set the broker url to: amqp://docconverter:pass123@rabbitmq:5672/docconverter-vhost
Click Save.

The page will attempt to contact the message broker and check for any Doc Converter instances. If everything has been set up correctly, the Broker Status box should now list the available Doc Converter instances and indicate that the Document Review feature is ready.

Now you are all set to start reviewing Office documents!