Skip to main content

Setting up the database

We provide a script to generate all the tables needed to use Webviewer Collaboration, as well as to start a local docker instance.


Before using these scripts, please make sure you are in the root directory for this module.

cd node_modules/@pdftron/collab-db-postgresql

Starting up a local database#

If you already have a postgres database running, you can skip this step.

If you do not have a local postgres database running, you can use the following script to start one using docker.

Docker must be installed on your machine for this to work.

yarn start-local-db [--options]

If you are using the standalone package you can run the included script like so

node lib/collab-db-postgresql/scripts/start-local-db.js [--options]


--directory, -dfalseLocal mount point for Postgres data files{homedir}/docker/volumes/postgres
--name, -nfalseName of the docker containerpg-docker
--port, -pfalsePort to run the database on5432
--passwordtrueA password for the database
--noMount, -nfalseDisables volume mounting. More infofalse

This will spin up a docker container with a postgres database installed.

Initializing the database#

To set up the required tables and relations in your database, run the following script.

The operation is not destructive, however, we recommend running it against an empty database

yarn init-db [--options]

If you are using the standalone package you can run the included script like so

node lib/collab-db-postgresql/scripts/init-db.js [--options]


--host, -hfalseThe host to connect to127.0.0.1
--port, -pfalseThe port to connect on5432
--username, -ufalseThe username to log in withpostgres
--passwordtrueThe password to log in with
--dbNametrueThe name of the database to create
--sslKeyfalseThe file path of SSL private keys
--sslCertfalseThe file path of SSL certificate chains

If the operation is successful, all the required tables should be created in your database!

Viewing the database#

If you wish to view the schema and data inside your database, you will need to use a database client to connect to your database.

We recommend Beekeeper Studio. It is open source, free, and very simple to use.

When setting up the database connection in whichever client you choose, you can use this information:

Setting nameValue
Connection TypePostgres
Enable SSLNo
Password{The password you entered when running the startup script}
Default Database{The dbName you provided in the initialize script}


The above scripts are intended to work on any OS, however, sometimes Docker does not play nicely on certain systems (looking at you, Windows).

Below are some issues users have come across, and some potential steps to fixing them. We will keep this list up to date as problems & solutions arise.

Cannot start Docker container - errors mounting volume#

There are plenty of reports (#77, #44, #10693) of users having issues mounting Docker volumes on Windows. This causes the Docker container to fail when starting up.

Since this is such a widespread issue with many different solutions, we recommend trying the solutions people have proposed in the links above.

If none of these works, the last resort is to not mount the volume when starting the database. This works fine for testing purposes, but your data will not be persisted if the container shuts down.

To start the database with no volume mounting, pass --noMount as a parameter to the start-local-db script.

Next steps#