Using Docker
This section explains how to deploy a PrizmDoc Server instance using the official PrizmDoc Server Docker image, available on Docker Hub as accusoft/prizmdoc-server.
Requirements
To run PrizmDoc Server as a Docker container, you simply need a Docker host (a machine with Docker installed). See the Docker documentation for more information.
1. Create a PrizmDoc Server config file
Before you can run PrizmDoc Server, you'll need a config file. We've included a special init-config
command in our Docker image which you can use to create an initial config file.
Windows (PowerShell)
First, make sure you've created a config
directory on your host file system. This will be the directory where your new config file will be created:
mkdir config
Then, use the Docker image's init-config
command to create a new PrizmDoc Server config file:
docker run --rm -e ACCEPT_EULA=YES --volume $pwd/config:/config accusoft/prizmdoc-server init-config
This will create a new PrizmDoc Server config file on your Windows host filesystem at .\config\prizm-services-config.yml
.
Linux (bash)
Use the init-config
command to create a new PrizmDoc Server config file:
docker run --rm -e ACCEPT_EULA=YES --volume $(pwd)/config:/config accusoft/prizmdoc-server init-config
This will create a new PrizmDoc Server config file on your host filesystem at ./config/prizm-services-config.yml
.
2. Configure your license
To start an instance of PrizmDoc Server, you need a license key from Accusoft. If you don't have a license, please contact info@accusoft.com.
To configure the license, set the values of license.solutionName
and license.key
in your PrizmDoc Server config file (prizm-services-config.yml
).
NOTE: On a Linux system, because the config file was created by a Docker container, you will need to either edit the config file as root or change the owner of the file before editing it.
For more information about configuring PrizmDoc Server, see Configuring PrizmDoc Server.
3. Start PrizmDoc Server
If you are using the default configuration, you can start PrizmDoc Server as follows:
Windows (PowerShell)
First, create a directory on your host file system to store log files:
mkdir logs
Then, start a prizmdoc-server
container:
docker run --rm --env ACCEPT_EULA=YES --publish 18681:18681 --volume $pwd/config:/config --volume $pwd/logs:/logs --name prizmdoc-server accusoft/prizmdoc-server
Linux (bash)
Start a prizmdoc-server
container:
docker run --rm --env ACCEPT_EULA=YES --publish 18681:18681 --volume $(pwd)/config:/config --volume $(pwd)/logs:/logs --volume $(pwd)/data:/data --name prizmdoc-server accusoft/prizmdoc-server
In the examples above:
--rm
ensures the container is automatically deleted when it stops.--env ACCEPT_EULA=YES
indicates you have accepted the PrizmDoc Viewer license agreement.--publish 18681:18681
publishes the container'snetwork.publicPort
port to the host. If you enable clustering (network.clustering.enabled: true
), you will also want to publish thenetwork.clustering.clusterPort
(18682
in a default configuration).--volume $(pwd)/config:/config
maps a host config directory into the container. Your local config directory must contain theprizm-services-config.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
(Linux only) maps a local data directory into the container. After the container stops, the data will remain in this directory. Because PrizmDoc Server uses memory-mapped files when writing to the data directory, and because Docker only supports memory-mapped file access to a mapped volume on a Linux host, setting up this particular volume is only supported on a Linux docker host.--name prizmdoc-server
sets the name of the running container.accusoft/prizmdoc-server
is the image that should be run.
Additionally, you can use a TZ
environment variable to control the time zone when rendering documents. For example, add the -e TZ="America/New_York"
option to use the New York time zone in the examples above.
If you want to start the Docker container in the background, add the -d
option to docker run
to run the container in disconnected mode.
4. Check PrizmDoc Server has finished starting and is healthy
It may take several minutes for PrizmDoc Server to finish starting. But, once fully started, GET /PCCIS/V1/Service/Current/Health
should return HTTP 200, indicating PrizmDoc Server is healthy (while starting, this request will return nothing or an error).
Windows (PowerShell)
Invoke-WebRequest -Uri http://localhost:18681/PCCIS/V1/Service/Current/Health
Should eventually output something like:
StatusCode : 200
StatusDescription : OK
Content : {79, 75}
RawContent : HTTP/1.1 200 OK
X-Server-Chain: 2b95007f011f
X-Server-Response-Time: 0
Connection: keep-alive
Transfer-Encoding: chunked
Date: Thu, 21 Nov 2019 17:01:04 GMT
Headers : {[X-Server-Chain, 2b95007f011f], [X-Server-Response-Time, 0], [Connection, keep-alive], [Transfer-Encoding, chunked]...}
RawContentLength : 2
NOTE: It may take several minutes for PrizmDoc Server to start. You will not get a 200 result until PrizmDoc Server has fully started.
Linux (bash)
curl -i http://localhost:18681/PCCIS/V1/Service/Current/Health
Should eventually output something like:
HTTP/1.1 200 OK
X-Server-Chain: 69a6d22f90b9
X-Server-Response-Time: 1
Date: Wed, 20 Nov 2019 20:25:31 GMT
Connection: keep-alive
Transfer-Encoding: chunked
OK
NOTE: It may take several minutes for PrizmDoc Server to start. You will not get a 200 result until PrizmDoc Server has fully started.
Troubleshooting: Check the admin status page
If you're not getting a 200 response at all, try checking the PrizmDoc Server admin status page in a browser: http://localhost:18681/admin
5. Stopping the container
You can stop your named container with:
docker stop prizmdoc-server
Adding Fonts & Packages to the Container
This section explains how to extend your current PrizmDoc Server container to include additional fonts or packages.
NOTE: During this process, the current running container will be paused when committing the changes. It is recommended to run this process during a maintenance window.
1. Log into your Docker host running the PrizmDoc Server Docker image.
2. Locate and make a note of the CONTAINER ID for the PrizmDoc Server which is currently running:
docker ps
NOTE: If you cannot find the container in the list, make sure your PrizmDoc Server Docker container is running.
For more information about starting and stopping the PrizmDoc Server Docker container, see Install Prizmdoc Server.
3. SSH into your PrizmDoc Server container:
docker exec -it CONTAINER ID /bin/bash.
NOTE: Replace the CONTAINER ID with the CONTAINER ID noted in step 2 above.
4. Download package information from all configured sources.
Once you are connected to the container, you will need to make sure you have the latest package information by running:
apt-get update
5. Install fonts or packages to your PrizmDoc Server container.
Installing fonts and packages are the same as any Ubuntu server installation.
Example of installing fonts:
apt-get install language-pack-ja
Example of installing packages:
apt-get install wget
6. Exit out of the container by typing "exit" at the command prompt.
7. Commit the PrizmDoc Server container to a new image.
Once all of the packages and fonts have been installed to the currently running container, you will need to create a new image with the changes:
docker commit CONTAINER_ID NEW IMAGE NAME
Replace the CONTAINER ID with the CONTAINER ID noted in step 2 and replace the NEW IMAGE NAME with the name and tag of your updated image. (For example: accusoft/prizmdoc-server-fonts:latest).
NOTE: The container being committed and its processes will be paused while the image is committed.
8. Verify the new image is created by running:
docker image ls
9. Restart the PrizmDoc Server Docker container using the new image:
Stop existing container:
docker container stop CONTAINER_ID
Replace the CONTAINER ID with the CONTAINER ID noted in step 2.
Start new container using new image name outlined in step 7:
docker run --rm --env ACCEPT_EULA=YES --publish 18681:18681 --volume $(pwd)/config:/config --volume $(pwd)/logs:/logs --volume $(pwd)/data:/data --name prizmdoc-server accusoft/prizmdoc-server-fonts:latest
For more information about starting and stopping the PrizmDoc Server Docker container, see Install Prizmdoc Server.