Introduction

This section explains how to deploy a PAS instance using the official PAS Docker image, available on Docker Hub as accusoft/prizmdoc-application-services.

PAS requires a connection to PrizmDoc Server. If you haven't done so already, you will need to deploy a PrizmDoc Server instance as well. Please see our PrizmDoc Server Docker installation guide.

NOTE: If you would like to evaluate our product, you can use the PrizmDoc Eval Docker image instead.

Recommended Hardware Requirements

To run PAS as a Docker container, you simply need a Docker host (a machine with Docker installed). See the Docker documentation for more information.

Before running this Docker image, you MUST configure Docker to use the appropriate hardware resources. If you try to run the image with fewer CPUs or less memory, it may not function correctly. For detailed information, please review the guidance provided in our Server Sizing guide.

A database connection is recommended in order to use PAS. See PAS Database Admin and Maintenance for more information.

Deploying PAS

1. Get the latest image

Run the following command to pull in the latest PrizmDoc Application Services image:

docker pull accusoft/prizmdoc-application-services

2. Initialize a Default Config File

Before you can run PAS, you'll need a config file (if you already have a config file defined which you want to use, you can skip to step 4). You can create a default config file using this Docker image's init-config command. This section explains how to do that.

Windows (PowerShell)

First, make sure you've created a config directory on your host file system:

mkdir config

Then, use the init-config command to create a new pcc.nix.yml file:

docker run --rm -e ACCEPT_EULA=YES --volume $pwd/config:/config accusoft/prizmdoc-application-services init-config

This will create a new PAS config file on your Windows host filesystem at .\config\pcc.nix.yml.

Mac or Linux (bash)

Use the init-config command to create a new pcc.nix.yml file:

docker run --rm -e ACCEPT_EULA=YES --volume $(pwd)/config:/config accusoft/prizmdoc-application-services init-config

This will create a new PAS config file on your host filesystem at ./config/pcc.nix.yml.

3. Customize your PAS Config File

You will need to customize the contents of the pcc.nix.yml file for your PAS deployment.

Typically, you need to:

Change the secretKey to your own value.

Configure your connection to PrizmDoc Server by updating the pccServer properties:

If you are using self-hosted PrizmDoc Server, this might look something like:

pccServer.hostName: my-prizmdoc-server-host
pccServer.port: 18681
pccServer.scheme: http

If you are using PrizmDoc Cloud:

pccServer.hostName: api.accusoft.com
pccServer.port: 443
pccServer.scheme: https
pccServer.apiKey: YOUR_API_KEY

Configure your database connection.

NOTE: A database is recommended for use with PAS as of v14.1.

If you do not already have a database for PrizmDoc to connect to, you can use the MySQL Docker image to easily create a database. If both containers are in the same user-defined Docker network, the PrizmDoc container can reference the database container by its name in the connection string.

A database user with rights to add or mutate tables and their records must be specified, this might look something like:
```
database.adapter: mysql
database.connectionString: "mysql://username:password@localhost:3306/prizmdb"
```
Configure your other storage options.

For more information, see the product documentation about configuring PAS.

4. Initialize Database for use with PAS (recommended as of v14.1)

NOTE: This step is recommended as of v14.1, as initialization of the database is done automatically on PAS startup.

If you want to manually initialize a database for use with PAS before starting the product, use the following steps:

Ensure that you have a database connection configured within the pcc.nix.yml file.
If the database user specified in the config file does not have rights to add or mutate tables and their records, you must supply an alternate user (with rights enabled) and password in the form of environment variables.

For more information on the user rights requirements and how the DATABASE_USER and DATABASE_PASSWORD environment variables affect that, see the documentation on how to run the database scripts manually for PAS.

Windows (PowerShell)

In order to initialize the database with a user other than what is provided in the config file, supply both a DATABASE_USER and a DATABASE_PASSWORD environment variable within the command like so:

docker run --rm --env ACCEPT_EULA=YES --env DATABASE_USER="prizm-user" --env DATABASE_PASSWORD="password" --volume $pwd/config:/config accusoft/prizmdoc-application-services init-database

In order to initialize the database with the user provided in the config file, run the following command:

_NOTE: If the DATABASE_USER and DATABASE_PASSWORD environment variables have been set previously, they will be used instead of the database user provided in the config file._

docker run --rm --env ACCEPT_EULA=YES --volume $pwd/config:/config accusoft/prizmdoc-application-services init-database

Mac and Linux (bash)

docker run --rm --env ACCEPT_EULA=YES --env DATABASE_USER="prizm-user" --env DATABASE_PASSWORD="password" --volume $(pwd)/config:/config accusoft/prizmdoc-application-services init-database

In order to initialize the database with the user provided in the config file, run the following command:

_NOTE: If the DATABASE_USER and DATABASE_PASSWORD environment variables have been set previously, they will be used instead of the database user provided in the config file._

docker run --rm --env ACCEPT_EULA=YES --volume $(pwd)/config:/config accusoft/prizmdoc-application-services init-database

5. Start PAS

Assuming you have configured PAS to run on port 3000 and use ./config, ./logs, and ./data directories, this section explains how to start a PAS Docker container.

Windows (PowerShell)

First, create directories for logs and data:

mkdir logs
mkdir data

Then, start a pas container:

docker run -d --env ACCEPT_EULA=YES --publish 3000:3000 --volume $pwd/config:/config --volume $pwd/logs:/logs --volume $pwd/data:/data --name pas accusoft/prizmdoc-application-services

Mac and Linux (bash)

Start a pas container:

docker run -d --env ACCEPT_EULA=YES --publish 3000:3000 --volume $(pwd)/config:/config --volume $(pwd)/logs:/logs --volume $(pwd)/data:/data --name pas accusoft/prizmdoc-application-services

Docker Run Options

In the examples above:

-d runs the container in the background, in detached mode.
--rm ensures the container is automatically deleted when it stops.
--env ACCEPT_EULA=YES indicates you have accepted the PrizmDoc license agreement.
--env DATABASE_USER="prizm-user" --env DATABASE_PASSWORD="password" specifies the user and password to use when accessing the connected database.
- When running with init-database, the provided user must have the rights to create and alter database tables and their records.
- If PAS is running as a service, the user only requires rights to add, update, and remove records within database tables.
--publish 3000:3000 publishes the container's port to the host. This assumes PAS was configured to use port 3000. If you have configured PAS to use a different port, adjust accordingly.
--volume $(pwd)/config:/config maps a host config directory into the container. Your local config directory must contain the pcc.nix.yml config file created earlier.
--volume $(pwd)/logs:/logs maps a local logs directory into the container. After the container stops, the logs will remain in this directory.
--volume $(pwd)/data:/data maps a local data directory into the container. After the container stops, the data will remain in this directory and can be used again when restarting the container.
--name pas sets the name of the running container.
accusoft/prizmdoc-application-services is the image that should be run.

If you want to start the Docker container in the background, add the -d option to docker run to run the container in detached mode.

_NOTE: As of PrizmDoc v13.19, the Docker container starts a single PAS instance. We recommend that you run multiple containers when you need a PAS cluster. However, you can set the environment variable LEGACY_RUN_MULTIPLE_INSTANCES=YES to run multiple PAS instances in the container. The number of instances depends on the CPU cores count on the host machine._

6. Check PAS Health

GET http://localhost:3000/health should return HTTP 200, indicating PAS is healthy.

Windows (PowerShell)

Invoke-WebRequest -Uri http://localhost:3000/health

Should output something like:

StatusCode        : 200
StatusDescription : OK
Content           : {79, 75}
RawContent        : HTTP/1.1 200 OK
                    Connection: keep-alive
                    Content-Length: 2
                    Date: Thu, 21 Nov 2019 17:49:35 GMT

                    OK
Headers           : {[Connection, keep-alive], [Content-Length, 2], [Date, Thu, 21 Nov 2019 17:49:35
                    GMT]}
RawContentLength  : 2

Mac or Linux (bash)

curl -i http://localhost:3000/health

Should output something like:

HTTP/1.1 200 OK
Date: Wed, 20 Nov 2019 20:00:39 GMT
Connection: keep-alive
Content-Length: 2

OK

7. Check PAS's Connection to PrizmDoc Server

GET http://localhost:3000/servicesConnection should return HTTP 200, indicating PAS is configured correctly to make requests to PrizmDoc Server.

Windows (PowerShell)

Invoke-WebRequest -Uri http://localhost:3000/servicesConnection

Should output something like:

StatusCode        : 200
StatusDescription : OK
Content           : {79, 75}
RawContent        : HTTP/1.1 200 OK
                    Connection: keep-alive
                    Content-Length: 2
                    Date: Thu, 21 Nov 2019 17:50:11 GMT

                    OK
Headers           : {[Connection, keep-alive], [Content-Length, 2], [Date, Thu, 21 Nov 2019 17:50:11
                    GMT]}
RawContentLength  : 2

Mac or Linux (bash)

curl -i http://localhost:3000/servicesConnection

Should output something like:

HTTP/1.1 200 OK
Date: Wed, 20 Nov 2019 20:00:39 GMT
Connection: keep-alive
Content-Length: 2

OK

8. Stopping the Container

You can stop your named container with:

docker stop pas