PDF Server

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-server 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-server) 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_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.

API Server + Redis

Assuming that you have an external MongoDB setup, the only thing that you will need to configure in addition to a MongoDB server is a Redis instance. The PDF downloads uses a temp token feature of the API server which does require that Redis be installed. You can either setup Redis externally, or in some cases this can be managed on the actual API Server. Typically, for a production environment, you would want to have Redis running external, but it is also not considered bad practice to have Redis on the actual server since it is only used to store the temporary download tokens and the worst thing that will happen is that a token would expire if the servers reset. To accomplish this, you will execute the following commands within your terminal.

First create a newtwork that will connect Form.io Server to the local Redis Instance

docker network create formio

Now spin up a local instance of Redis on this server.

docker run -itd \
  --name formio-redis \
  --network formio \
  --restart unless-stopped \
  redis;

Next, spin up your Form.io API server connecting it to the local Redis instance.

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

Note that you would provide your own URL to the MONGO database and also provide your own domain where you are hosting the PDF server for the FORMIO_FILES_SERVER variable.

API Server Standalone

For some cases, you may wish to keep your Redis database external to your Form.io API server. This would allow for your API servers to become more ephemeral where they can autoscale. If this is the case, then you would provide the following configurations when spinning up your servers. For example, this would be what our Docker command would look like connecting to an ElasticCache instance in AWS.

docker run -itd \
  -e "PORTAL_SECRET=CHANGEME" \
  -e "JWT_SECRET=CHANGEME" \
  -e "DB_SECRET=CHANGEME" \
  -e "PROTOCOL=http" \
  -e "MONGO=mongodb://:@aws-us-east-1-portal.234.dblayer.com:23423/formio?ssl=true" \
  -e "REDIS_ADDR=production-001.2iu8pr.0001.usw2.cache.amazonaws.com" \
  -e "REDIS_PORT=6379" \
  -e "FORMIO_FILES_SERVER=https://pdfserver.yourdomain.com" \
  --restart unless-stopped \
  --name formio-server \
  -p 80:80 \
  formio/formio-server;

Notice that in this scenario, you do not need to create a formio newtork and connect your Docker container to the redis machine with the -link command.

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 \
 -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;

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