Asset Storage

PSPDFKit Server supports multiple storage backends for PDFs and other assets, as detailed below.

Built-In Asset Storage

By default, PSPDFKit Server stores assets as Binary Large OBjects (BLOBs) in the database. If you have PDFs that are bigger than 1GB in size, we recommend using S3-Compatible Object Storage.

Set ASSET_STORAGE_BACKEND to built-in to use the Built-In Asset Storage.

S3-Compatible Object Storage

PSPDFKit Server can also store your assets in any Amazon S3-compatible object storage service.

Set ASSET_STORAGE_BACKEND to S3 and use ASSET_STORAGE_S3_BUCKET, ASSET_STORAGE_S3_ACCESS_KEY_ID, ASSET_STORAGE_S3_SECRET_ACCESS_KEY, and ASSET_STORAGE_S3_REGION to determine how PSPDFKit Server can access the external storage.

When using an object storage provider other than Amazon S3, you can set the ASSET_STORAGE_S3_SCHEME, ASSET_STORAGE_S3_HOST, and ASSET_STORAGE_S3_PORT.

For more details about using Google Cloud Storage as the storage backend, take a look at the Google Cloud Storage interoperability guide.

Docker Volume (Deprecated)

Storing assets in a (local) Docker volume was the default in older versions of PSPDFKit Server, but this was deprecated in 2017.7 and will be removed in a future version of PSPDFKit Server.

We recommend updating to the built-in asset storage.

To upgrade to the built-in asset storage, see the migration section.

With this backend, all assets are stored locally at the path configured in ASSET_STORAGE_PATH.

Make sure to mount this path as a Docker volume. Otherwise, recreating your Docker container will destroy all uploaded PDFs and other assets!

All options for the storage backend are set with environment variables.

Minio

Our recommended solution when using an S3-compatible object storage in production is to use Minio in development, in order to get closer to dev/prod parity.

To run the Minio Docker container, run the following:

1
2
docker pull minio/minio
docker run -p 9000:9000 minio/minio server /export

After running these commands, you should see the AccessKey and SecretKey printed out in the terminal, which you can use to access the Minos web interface at http://localhost:9000/minio.

You can now configure docker-compose.yml, like this:

Copy
1
2
3
4
5
6
7
8
environment:
  ASSET_STORAGE_BACKEND: S3
  ASSET_STORAGE_S3_BUCKET: <minio bucket name>
  ASSET_STORAGE_S3_ACCESS_KEY_ID: <minio access key>
  ASSET_STORAGE_S3_SECRET_ACCESS_KEY: <minio secret access key>
  ASSET_STORAGE_S3_SCHEME: http://
  ASSET_STORAGE_S3_HOST: pssync_minio
  ASSET_STORAGE_S3_PORT: 9000

Minio supports emulating different regions. It defaults to us-east-1. If you have changed your Minio configuration to a different region, make sure to set ASSET_STORAGE_S3_REGION accordingly.

Migration between Asset Storage Options

It is possible to migrate from one storage backend to another one by executing the migration command as described below. To prevent data loss, a migration does not delete files from the original storage backend.

Warning

When doing these migrations, please make sure you disable access to the server while the migration is in progress, in order to prevent race conditions where data gets stored in the old backend before the server gets restarted with the new asset storage configuration. You can avoid this problem entirely by stopping the server before you do the migrations.

Migrating with Docker Compose

Use the following commands if you want to migrate your asset storage to another one and you use docker-compose to run your application.

Migrating to Built-In Storage from Docker Volume (from Older Versions of PSPDFKit Server)

To migrate from a local Docker volume to built-in asset storage, make sure you have set ASSET_STORAGE_PATH to the path where the assets currently reside.

In the same directory, in the place where you have your docker-compose file, run the following:

1
docker-compose run pspdfkit pspdfkit assets:migrate:from-local-to-built-in
Migrating to S3 from Built-In Storage

To migrate from the built-in asset storage to S3, make sure you have set all S3 options.

In the same directory, in the place where you have your docker-compose file, run the following:

1
docker-compose run pspdfkit pspdfkit assets:migrate:from-built-in-to-s3
Migrating to Built-In Storage from S3

To migrate from S3 asset storage to built-in storage, make sure you have set all S3 options.

In the same directory, in the place where you have your docker-compose file, run the following:

1
docker-compose run pspdfkit pspdfkit assets:migrate:from-s3-to-built-in

Migrating without Docker Compose

Use the following commands if you want to migrate your asset storage to another one and you don’t use docker-compose to run your application. Make sure to replace <container-name> with the name of your Docker container in the migration command. To list all containers and their names on your machine, run the following:

1
docker ps -a
Migrating to Built-In Storage from Docker Volume (from Older Versions of PSPDFKit Server)

To migrate from a local Docker volume to built-in asset storage, make sure you have set ASSET_STORAGE_PATH to the path where the assets currently reside:

1
docker exec <container-name> pspdfkit assets:migrate:from-local-to-built-in
Migrating to S3 from Built-In Storage

To migrate from the built-in asset storage to S3, make sure you have set all S3 options:

1
docker exec <container-name> pspdfkit assets:migrate:from-built-in-to-s3
Migrating to Built-In Storage from S3

To migrate from S3 asset storage to built-in storage, make sure you have set all S3 options:

1
docker exec <container-name> pspdfkit assets:migrate:from-s3-to-built-in