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)
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
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.
- When running with
--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 thepcc.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