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.

info

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]

Options

OptionRequiredDescriptionDefault
--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]

Options

OptionRequiredDescriptionDefault
--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!

Troubleshooting#

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#