Please edit the object below. Lines beginning with a '#' will be ignored,

PSPDFKit Server has been deprecated and replaced by Document Engine. To migrate to Document Engine and unlock advanced document processing capabilities, refer to our migration guide. Learn more about these enhancements on our blog.

This guide will walk you through the steps for deploying PSPDFKit Server to the Google Cloud Platform(opens in a new tab) with Kubernetes(opens in a new tab).

Creating a Google Cloud project

To create a Google Cloud project, please refer to the steps outlined in the Google Cloud Platform Documentation(opens in a new tab).

Setting up Google Cloud SDK

To be able to deploy PSPDFKit Server to the Google Cloud Platform(opens in a new tab) with Kubernetes(opens in a new tab), you have to set up the gcloud(opens in a new tab) utility in order to manage your Kubernetes(opens in a new tab) cluster in the command line.

To install gcloud(opens in a new tab), follow the installation instructions for your platform:

kubectl(opens in a new tab) is a utility for running commands against Kubernetes clusters. After installing gcloud(opens in a new tab), add the kubectl(opens in a new tab) components by running the following command:

gcloud components install kubectl

Make sure to set the compute zone(opens in a new tab) to the one you want to deploy to. In this example, we are using europe-west2-c, but you can also pick another one if you are not located in Europe. Then insert it into the example below:

gcloud config set compute/zone europe-west2-c

Now run gcloud compute zones list to get a list of all available compute zones.

Creating a Kubernetes cluster

To create a Kubernetes(opens in a new tab) cluster with the name pspdfkit-example-cluster, run the following:

gcloud container clusters create pspdfkit-example-cluster

This will create a cluster using the default settings. To get an overview of your clusters, visit the Container Engine dashboard(opens in a new tab).

Run the following command to make sure kubectl(opens in a new tab) is connected to your cluster:

kubectl get pods

This command should print No resources found. When you get an error, try to authenticate to the Google Cloud Platform with gcloud auth application-default login.

Creating a Google Cloud SQL PostgreSQL database instance

To run PSPDFKit Server, you will need to set up a Postgres database for it. To do this, go to the Google Cloud SQL Instances(opens in a new tab) page and click on Create Instance.

Then you will be able to select a database engine for Google Cloud SQL to run on. Here you need to select PostgreSQL.

Finally, you have to set an instance ID, the default user password, and the region of the database.

Make sure to choose PostgreSQL 11 for the database version.

Connecting the Kubernetes engine to the Cloud SQL instance

To enable the PSPDFKit Server deployment to connect to the Cloud SQL Instance, we will use the Cloud SQL Proxy Docker image(opens in a new tab). First you need to enable the Cloud SQL Administration API(opens in a new tab). Then you have to set up a service account with access privileges for your Cloud SQL instance.

To do this, go to the service accounts page(opens in a new tab), click on Select, select your Google Cloud project, and then click on Create Service Account. Set a service account name and an ID, and make sure to select Cloud SQL Admin as the Project role and Furnish a new private key with the key type JSON.

Click on Save to save this service account and to download the service account private key file. Be sure to save this file, because you will need it later.

Run the following command to create a user named proxyuser for the Google Cloud SQL database. This user will be used to access the database from the PSPDFKit Server deployment:

gcloud sql users create proxyuser host --instance=[INSTANCE_NAME] --password=[PASSWORD]

Make sure to replace [INSTANCE_NAME] with the name of your Google Cloud SQL instance and [PASSWORD] with a password for the user.

You also need to create two secrets for the Kubernetes Engine application to be able to access the Cloud SQL instance.

To create the secret for the service account, replace [PROXY_KEY_FILE_PATH] in the following command with the path where you saved the service accounts’ private key, and then run it:

kubectl create secret generic cloudsql-instance-credentials \
    --from-file=credentials.json=[PROXY_KEY_FILE_PATH]

The second secret you need to create provides the proxy user account and its password. Here you need to replace [PASSWORD] with the password you set for the proxy user you just created:

kubectl create secret generic cloudsql-db-credentials \
    --from-literal=username=proxyuser --from-literal=password=[PASSWORD]

Creating a ConfigMap

ConfigMaps(opens in a new tab) allow you to decouple configuration artifacts from image content. To create the pspdfkit-config ConfigMap(opens in a new tab), run the following command:

kubectl create configmap pspdfkit-config

After the ConfigMap(opens in a new tab) is created, you can edit it with the following:

kubectl edit configmap pspdfkit-config

This should open the created ConfigMap(opens in a new tab) in your editor. Edit the file to match the following file and replace activation_key with your activation key:

# Please edit the object below. Lines beginning with a '#' will be ignored,
# and an empty file will abort the edit. If an error occurs while saving,
# this file will be reopened with the relevant failures.
#
apiVersion: v1
data:
  activation_key: YOUR_ACTIVATION_KEY_GOES_HERE
  api_auth_token: secret
  dashboard_password: secret
  dashboard_username: dashboard
  jwt_algorithm: RS256
  jwt_public_key: |
    -----BEGIN PUBLIC KEY-----
    MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEA2gzhmJ9TDanEzWdP1WG+
    0Ecwbe7f3bv6e5UUpvcT5q68IQJKP47AQdBAnSlFVi4X9SaurbWoXdS6jpmPpk24
    QvitzLNFphHdwjFBelTAOa6taZrSusoFvrtK9x5xsW4zzt/bkpUraNx82Z8MwLwr
    t6HlY7dgO9+xBAabj4t1d2t+0HS8O/ed3CB6T2lj6S8AbLDSEFc9ScO6Uc1XJlSo
    rgyJJSPCpNhSq3AubEZ1wMS1iEtgAzTPRDsQv50qWIbn634HLWxTP/UH6YNJBwzt
    3O6q29kTtjXlMGXCvin37PyX4Jy1IiPFwJm45aWJGKSfVGMDojTJbuUtM+8P9Rrn
    AwIDAQAB
    -----END PUBLIC KEY-----
  pgdatabase: pspdfkit
  secret_key_base: secret-key-base
kind: ConfigMap

Don’t change anything that comes after the kind: ConfigMap line, because that part is autogenerated.

Creating the services and deployments

For the configuration of the proxy container you will use to connect to the Cloud SQL database, you will need the instance connection name of the instance. To get this, run the following command:

gcloud sql instances describe [INSTANCE_NAME]

The output of this command will contain a line like this, where pspdfkit-example-project:europe-west1:pspdfkitexampledb is the name of the instance:

connectionName: pspdfkit-example-project:europe-west1:pspdfkitexampledb

Kubernetes services(opens in a new tab) and deployments(opens in a new tab) can be configured in a file. To run PSPDFKit Server, you have to define a service and a deployment for PSPDFKit Server. To do this, create the pspdfkit.yml file in the current directory, ensure that the pspdfkit/pspdfkit image tag corresponds to the latest PSPDFKit Server version, and replace pspdfkit-example-project:europe-west1:pspdfkitexampledb with the name of the Cloud SQL database instance from the previous command:

apiVersion: v1
kind: Service
metadata:
  name: pspdfkit
spec:
  ports:
    - protocol: TCP
      port: 5000
      targetPort: 5000
  selector:
    app: pspdfkit
  type: LoadBalancer
---
apiVersion: apps/v1
kind: Deployment
metadata:
  name: pspdfkit
spec:
  template:
    metadata:
      labels:
        app: pspdfkit
    spec:
      containers:
        - name: cloudsql-proxy
          image: gcr.io/cloudsql-docker/gce-proxy:1.11
          command: ["/cloud_sql_proxy",
                    "-instances=pspdfkit-example-project:europe-west1:pspdfkitexampledb=tcp:5432",
                    "-credential_file=/secrets/cloudsql/credentials.json"]
          volumeMounts:
            - name: cloudsql-instance-credentials
              mountPath: /secrets/cloudsql
              readOnly: true
        - image: pspdfkit/pspdfkit:2024.1.2
          name: pspdfkit
          env:
            - name: PGUSER
              valueFrom:
                secretKeyRef:
                      name: cloudsql-db-credentials
                      key: username
            - name: PGPASSWORD
              valueFrom:
                secretKeyRef:
                      name: cloudsql-db-credentials
                      key: password
            - name: PGDATABASE
              valueFrom:
                configMapKeyRef:
                  name: pspdfkit-config
                  key: pgdatabase
            - name: PGHOST
              value: "127.0.0.1"
            - name: PGPORT
              value: "5432"
            - name: ACTIVATION_KEY
              valueFrom:
                configMapKeyRef:
                  name: pspdfkit-config
                  key: activation_key
            - name: API_AUTH_TOKEN
              valueFrom:
                configMapKeyRef:
                  name: pspdfkit-config
                  key: api_auth_token
            - name: SECRET_KEY_BASE
              valueFrom:
                configMapKeyRef:
                  name: pspdfkit-config
                  key: secret_key_base
            - name: JWT_ALGORITHM
              valueFrom:
                configMapKeyRef:
                  name: pspdfkit-config
                  key: jwt_algorithm
            - name: JWT_PUBLIC_KEY
              valueFrom:
                configMapKeyRef:
                  name: pspdfkit-config
                  key: jwt_public_key
            - name: DASHBOARD_USERNAME
              valueFrom:
                configMapKeyRef:
                  name: pspdfkit-config
                  key: dashboard_username
            - name: DASHBOARD_PASSWORD
              valueFrom:
                configMapKeyRef:
                  name: pspdfkit-config
                  key: dashboard_password
          ports:
            - containerPort: 5000
              name: pspdfkit
      volumes:
        - name: cloudsql-instance-credentials
          secret:
            secretName: cloudsql-instance-credentials

To create the services and deployments needed to run PSPDFKit Server, execute the following:

kubectl create -f ./pspdfkit.yml

Viewing the dashboard

To be able to access the server, you have to get the external IP address that was assigned to the server. Run the following command to view all the services in your cluster, along with their assigned external IP addresses:

kubectl get services

This will show something like the following:

NAME         TYPE           CLUSTER-IP      EXTERNAL-IP      PORT(S)          AGE
kubernetes   ClusterIP      10.15.240.1     <none>           443/TCP          54m
pspdfkit     LoadBalancer   10.15.247.197   12.345.678.910   5000:32393/TCP   1m

Copy the EXTERNAL-IP address from the pspdfkit column and access the dashboard with the port 5000 and the /dashboard path in your web browser. In this example, you would access the dashboard with http://12.345.678.910:5000/dashboard.

Limitations

Be aware that this is just an example setup, and we recommend looking deeper into the Google Cloud Platform(opens in a new tab) for a production-ready setup.