PDF Server

These instructions are for the 2.x formio-files-core release and before. If you are using pdf-server 3.x or later, please go to the new documentation

The PDF Server allows you to deploy the Form.io PDF solution into your own environment, where you can store all of the PDF files within your own storage provider. The PDF server supports any S3 Compatible storage provider, but also integrates with Minio to allow for local storage of PDF files. Here are the instructions to deploy your own PDF server.

Upgrade your project.

In order to get the PDF server connected to your project, you must first upgrade your project within the Project Plan section of your project. Your project must be at least a Team Pro project in order to enable the PDF Server capabilities. You can upgrade, by selecting more than one PDF Server within the project upgrade section.

Import the PDF Resources

Now that you have upgraded your project, you will now need to import the PDF Resources into your project. To do this, download the following PDF project.json locally to your computer.

Download PDF Project

You can now navigate to your current project, and then import this template into your project, by clicking on .

then click on the Import Project Template to Live. You will now see a new Resource in your project called PDF that will be used to keep track of all your pdf forms.

Create an API key for your project

We will now need to create an API key for your project so that the PDF server can communicate to your project and add new entries into the PDF form that was imported in the previous step. To do this, we will simply click on the settings of your project and create a new api key as follows.

Make sure you keep track of this key since we will need it later.

Create your S3 Storage

Now that our project is configured, we will now need to setup an S3 storage for our forms. The PDF Server does require an S3 compatible storage system. Obviously, we would recommend using Amazon S3. This server also support the Minio Private Cloud system, which is documented below. Within Amazon S3, you will need to create a new storage bucket which will store all of the PDF files. After you are done doing this, you will need to ensure you have an IAM account attached to the bucket policy of your S3 server. Please follow the following instructions to create an access policy to your S3 bucket. When you are done, you will have both an Access Key and a Secret Key.

Deploy the PDF Server

Now that you have your S3 storage in place, and have an Access Key and Secret Key, you can now deploy your PDF server. In order to do this, you will need to have a Docker Hub account, and send that to the Form.io team so that we can provide you read access to the PDF server repository. Once you have been given read access, you should then be able to perform the following within your Docker enabled server.

docker login
docker pull formio/formio-files-core

Once you have the server deployed, you can then navigate to your PDF Enterprise Page which can be found in the PDF section of your project as follows.

In these settings, you will see a block of code that looks like this.

docker run -itd \
  -e "FORMIO_PROJECT=[PROJECT ID]" \
  -e "FORMIO_PROJECT_TOKEN=[PROJECT TOKEN]" \
  -e "FORMIO_PDF_PROJECT=[PDF PROJECT API URL]" \
  -e "FORMIO_PDF_APIKEY=[PDF PROJECT API KEY]" \
  -e "FORMIO_S3_SERVER=[YOUR S3 SERVER]" \
  -e "FORMIO_S3_BUCKET=[YOUR S3 BUCKET NAME]" \
  -e "FORMIO_S3_REGION=[YOUR S3 REGION]" \
  -e "FORMIO_S3_KEY=[YOUR S3 AUTH KEY]" \
  -e "FORMIO_S3_SECRET=[YOUR S3 AUTH SECRET]" \
  --restart unless-stopped \
  --name formio-files-core \
  -p 80:4005 \
  formio/formio-files-core;

You will need to copy these settings. For the Minio server deployments, you will need to provide the FORMIO_S3_SERVER configuration. You will then run this within your terminal which should spin up your new server.

Remote Form.io Server + PDF Server

If you have a combination of both the remote Form.io API server formio/formio-enterprise as well as the deployed PDF server formio/formio-files-core, you will need to introduce two new Environment variables to ensure that the API server can communicate to the PDF server and vice versa. Because of this, you will need to introduce the following two Environment Variables within the API Server and PDF Server respectively.

Deployment Setting Description Example
API Server (formio/formio-enterprise) FORMIO_FILES_SERVER This is the URL of the PDF server, which is set within the API server so that it can download Submission PDF’s pointed to the PDF Server https://pdf.yourserver.com
PDF Server (formio/formio-files-core) FORMIO_SERVER This is the URL of the API server, so that the remote PDF server can communicate to the API server to authenticate certain requests. https://forms.yourserver.com

PDF Server Environment Variables

The settings for the deployed PDF Server are described as follows.

Setting Description Example
FORMIO_SERVER This is the URL to a remotely deployed server https://forms.yourserver.com
FORMIO_PROJECT This is your project ID, which can be seen by looking at your project URL and copying what comes after ```/project/…``. 5aafe4e36d2d1e3153681e2a
FORMIO_PROJECT_TOKEN This is a provided PDF server token that must be provided to start the server. OFU1XbBosvNMpses2LBTawcLrUX6K2
FORMIO_PDF_PROJECT This is the URL of your project. If you imported the pdf template into your current project, then this is the URL of your project. https://pdfexample.form.io
FORMIO_PDF_APIKEY This is the API key we generated in the previous step. XFaM2dDQyg4yWPAI8sd2Zuol3Ef7Ti
FORMIO_VIEWER The URL of a custom viewer application. See https://help.form.io/userguide/pdf/#custom-viewer for more information. https://formio.github.io/formio-viewer/dist?theme=paper
FORMIO_S3_SERVER The URL of your S3 server. You can omit this if you are using Amazon S3 localhost
FORMIO_S3_PORT The port of your S3 server. You can omit this if you are using Amazon S3 9000
FORMIO_S3_BUCKET The name of your S3 bucket pdf
FORMIO_S3_REGION The region of your S3 bucket. You can omit this if you are using Minio us-east-1
FORMIO_S3_KEY The S3 authentication key IZ3671M2GO1KTSA1Z9ZU
FORMIO_S3_SECRET The S3 authentication secret 9PkfNHuqiNtTp0f4teHIL2yOULDjKGXjFYERxVB3

Point your project to your new PDF Server

The final step is to point your project to use the new PDF server that you just deployed. Within the PDF Enterprise Page of your project, you will add the url of your server to the settings and then press Save.

You are now running a completely hosted PDF Server!

Typical Form.io Server + PDF Server scalable environment.

It is very common to setup the Form.io API Server within a scalable environment along with the PDF Server. Here are the Docker commands to configure a side-by-side API Server + PDF Server deployment.

docker run -itd \
  -e "LICENSE=YOURLICENSE" \
  -e "PORTAL_SECRET=CHANGEME" \
  -e "JWT_SECRET=CHANGEME" \
  -e "DB_SECRET=CHANGEME" \
  -e "MONGO=mongodb://:@aws-us-east-1-portal.234.dblayer.com:23423/formio?ssl=true" \
  -e "FORMIO_FILES_SERVER=https://pdfserver.yourdomain.com" \
  --restart unless-stopped \
  --name formio-server \
  -p 80:80 \
  formio/formio-enterprise;

PDF (files) Server

To run the PDF Server in a production environment, the first thing you need to do is create an external mechanism for storing files. If you are using AWS S3, then this can be pretty simple where you just connect the PDF Server to that instance of S3 using the FORMIO_S3_SERVER as follows

docker run -itd \
  -e "FORMIO_SERVER=https://formio.yourdomain.com" \
  -e "FORMIO_PROJECT=59b7b78367d7fa2312a57979" \
  -e "FORMIO_PROJECT_TOKEN=wi83DYHAieyt1MYRsTYA289MR9UIjM" \
  -e "FORMIO_PDF_PROJECT=https://formio.yourdomain.com/yourproject" \
  -e "FORMIO_PDF_APIKEY=is8w9ZRiW8I2TEioY39SJVWeIsO925" \
  -e "FORMIO_S3_KEY=[S3 KEY]" \
  -e "FORMIO_S3_SECRET=[S3 SECRET]" \
  -e "FORMIO_S3_BUCKET=[S3 BUCKET]" \
  -e "FORMIO_S3_REGION=[S3 REGION]" \
  --restart unless-stopped \
  --name formio-files-core \
  -p 80:4005 \
  formio/formio-files-core;

PDF (files) Server + Minio

If you would like to run a different file storage mechanism than S3, or maybe you would like to host your files locally, then you will need to use Minio. This allows you to connect to any external file system or a local file system if you would like. You can go to their website, and read their documentation on how to set it up.

Once you are ready to install it, you can then run it locally as follows by first creating a newtwork as follows.

formio network create formio

Then run Minio. For example, this command would connect with Minio, which is connected to an Azure Blob.

docker run -itd \
 -e "MINIO_ACCESS_KEY=myblob" \
 -e "MINIO_SECRET_KEY=[AZURE BLOB SECRET KEY]" \
 --network formio \
 --name formio-minio \
 --restart unless-stopped \
 -p 9000:9000 \
 minio/minio gateway azure;

You can now connect to Minio with the following.

docker run -itd \
  -e "FORMIO_SERVER=https://formio.yourdomain.com" \
  -e "FORMIO_PROJECT=59b7b78367d7fa2312a57979" \
  -e "FORMIO_PROJECT_TOKEN=wi83DYHAieyt1MYRsTYA289MR9UIjM" \
  -e "FORMIO_PDF_PROJECT=https://formio.yourdomain.com/yourproject" \
  -e "FORMIO_PDF_APIKEY=is8w9ZRiW8I2TEioY39SJVWeIsO925" \
  -e "FORMIO_S3_KEY=myblob" \
  -e "FORMIO_S3_SECRET=[AZURE BLOB SECRET]" \
  -e "FORMIO_S3_BUCKET=formio" \
  -e "FORMIO_S3_REGION=us-east-1" \
  -e "FORMIO_S3_SERVER=minio" \
  -e "FORMIO_S3_PORT=9000" \
  --network formio \
  --link formio-minio:minio \
  --restart unless-stopped \
  --name formio-files-core \
  -p 80:4005 \
  formio/formio-files-core;

Local Deployment: API, PDF, Minio, and Mongo

The following commands can be used to spin up a single server environment that will host all of the necessary dependencies to run the Form.io API server + PDF server all on one server. The following command can be performed on a fresh Unix based system with Docker already installed.

docker network create formio && \
docker run -itd  \
  --name formio-mongo \
  --network formio \
  --volume ~/opt/mongodb:/data/db \
  --restart unless-stopped \
  mongo && \
docker run -itd \
  -e "LICENSE=YOURLICENSE" \
  -e "FORMIO_FILES_SERVER=http://formio-files:4005" \
  -e "PORTAL_SECRET=CHANGEME" \
  -e "JWT_SECRET=CHANGEME" \
  -e "DB_SECRET=CHANGEME" \
  --restart unless-stopped \
  --network formio \
  --name formio-server \
  --link formio-files-core:formio-files \
  --link formio-mongo:mongo \
  -p 3000:80 \
  formio/formio-enterprise && \
docker run -itd \
  -e "MINIO_ACCESS_KEY=CHANGEME" \
  -e "MINIO_SECRET_KEY=CHANGEME" \
  --network formio \
  --name formio-minio \
  --restart unless-stopped \
  -p 9000:9000 \
  -v ~/minio/data:/data \
  -v ~/minio/config:/root/.minio \
  minio/minio server /data && \
docker run -itd \
  -e "FORMIO_SERVER=http://formio" \
  -e "FORMIO_PROJECT=59b7b78367d7fa2312a57979" \
  -e "FORMIO_PROJECT_TOKEN=wi83DYHAieyt1MYRsTYA289MR9UIjM" \
  -e "FORMIO_PDF_PROJECT=http://formio/yourproject" \
  -e "FORMIO_PDF_APIKEY=is8w9ZRiW8I2TEioY39SJVWeIsO925" \
  -e "FORMIO_S3_SERVER=minio" \
  -e "FORMIO_S3_PORT=9000" \
  -e "FORMIO_S3_BUCKET=formio" \
  -e "FORMIO_S3_KEY=CHANGEME" \
  -e "FORMIO_S3_SECRET=CHANGEME" \
  --network formio \
  --link formio-server:formio \
  --link formio-minio:minio \
  --restart unless-stopped \
  --name formio-files-core \
  -p 4005:4005 \
  formio/formio-files-core;

You can now run your Form.io API Server alongside your PDF Server!

Using Docker

Docker instances are run inside a Docker Engine. There are many options for where and how to run a docker instance. Depending on which Docker Engine you are using, the formio server configuration will be different. You can see our config options using Environment Variables in the Config Options section of the help.

Our docker image are located on docker hub in public repos. You will need a license in order to run the server.

https://hub.docker.com/r/formio/pdf-server/

To pull it down, run the following docker command.

docker pull formio/pdf-server

Using Node.js

The Node version of the form.io PDF Enterprise is run in a Node.js context. This can be any Node.js 12.x or above.

Accessing the GitHub image

Once on an enterprise plan, you will need to have access to the private repository. Our private repositories are located on GitHub.

https://github.com/formio/pdf-enterprise

Since the image is a private GitHub respository, you will need to log in with your GitHub account and test cloning the repository. If you are unable to clone the repository, please contact support with your username and account information.

Follow the directions in the Readme of the pdf-enterpise repository to finish the setup.

Config Options

  Variable Default Description
Core FORMIO_SERVER https://api.form.io URL of the formio-enterprise server.
  LICENSE_KEY   A license key that contains pdfServer scope.
       
Database MONGO mongodb://localhost:27017 Mongo connection string, same as formio-enterprise setting.
  DB_SECRET   The DB Secret, same as formio-enterprise setting.
  MONGO_DB_NAME formio Mongo database name, if using localhost
  MONGO_SA   SA certificate if using SSL DB connection
  FORMIO_PDF_PROJECT   If not using mongo, the url of the project containing the pdf resource.
  FORMIO_PDF_APIKEY   If not using mongo, an api key for the project containing the pdf resource.
       
Config DOCKER_SECRETS false Whether to enable using docker secrets.
  DOCKER_SECRETS_PATH /run/secrets The path to the docker secrets.
       
Rendering FORMIO_LIBURL   URL of the PDF front-end library (see formio-pdf)
  FORMIO_VIEWER   URL to a version of the pdf viewer application
  PDF2HTMLEX_PATH /usr/bin/pdf2htmlEX path to pdf to html converter
  PDFUNITE_PATH /usr/bin/pdfunite path to pdfunite
       
Storage FORMIO_S3_SERVER   S3 server URL
  FORMIO_S3_PORT 9000 S3 server port
  FORMIO_S3_BUCKET   S3 server bucket name
  FORMIO_S3_KEY   S3 access key
  FORMIO_S3_SECRET   S3 secret key

Min.io

You can setup a local S3 server using min.io. There are appropriate versions for Linux/Mac/Windows in downloads page.

Examples

docker run -itd \
  -e "MINIO_ACCESS_KEY=CHANGEME" \
  -e "MINIO_SECRET_KEY=CHANGEME" \
  --network formio \
  --name formio-minio \
  --restart unless-stopped \
  -p 9000:9000 \
  -v ~/minio/data:/data \
  -v ~/minio/config:/root/.minio \
  minio/minio server /data && \
docker run -itd \
  -e "LICENSE_KEY=YOURLICENSE" \
  -e "MONGO=mongodb://user:password@mongoserver.com/dbname" \
  -e "DB_SECRET=CHANGEME" \
  -e "FORMIO_SERVER=http://formio" \
  -e "FORMIO_S3_SERVER=minio" \
  -e "FORMIO_S3_PORT=9000" \
  -e "FORMIO_S3_BUCKET=formio" \
  -e "FORMIO_S3_KEY=CHANGEME" \
  -e "FORMIO_S3_SECRET=CHANGEME" \
  --network formio \
  --link formio-server:formio \
  --link formio-mongo:mongo \
  --link formio-minio:minio \
  --restart unless-stopped \
  --name pdf-server \
  -p 4005:4005 \
  formio/pdf-server;