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.
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.
If you are using the standalone package you can run the included script like so
Options
| Option | Required | Description | Default |
|---|---|---|---|
--directory, -d | false | Local mount point for Postgres data files | {homedir}/docker/volumes/postgres |
--name, -n | false | Name of the docker container | pg-docker |
--port, -p | false | Port to run the database on | 5432 |
--password | true | A password for the database | |
--noMount, -n | false | Disables volume mounting. More info | false |
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
If you are using the standalone package you can run the included script like so
Options
| Option | Required | Description | Default |
|---|---|---|---|
--host, -h | false | The host to connect to | 127.0.0.1 |
--port, -p | false | The port to connect on | 5432 |
--username, -u | false | The username to log in with | postgres |
--password | true | The password to log in with | |
--dbName | true | The name of the database to create | |
--sslKey | false | The file path of SSL private keys | |
--sslCert | false | The 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 name | Value |
|---|---|
| Connection Type | Postgres |
| Host | localhost |
| Port | 5432 |
| Enable SSL | No |
| User | postgres |
| Password | {The password you entered when running the startup script} |
| Default Database | {The dbName you provided in the initialize script} |
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.