Self hosting

We offer an self hosted solution for UnoPdf, allowing you to deploy the backend component using our provided Docker image. With this option, you have the flexibility to host and manage the PDF Viewer backend within your own infrastructure, in the cloud or on-premise.

Get Docker

Follow instructions at https://docs.docker.com/get-docker/.

Obtain the Docker Image

From your github.com account, create a personal access token (classic) with scope read:packages.

Note that TallComponents must have assigned sufficient rights to your github account.

Next, run the following commands in your console of choice (replace both YOUR_TOKEN and USERNAME):

Store the token in a variable:

export CR_PAT=YOUR_TOKEN

Login to the github container registry:

echo $CR_PAT | docker login ghcr.io -u USERNAME --password-stdin

Pull (download) the image:

docker pull ghcr.io/tallcomponents/unopdf-server:latest

Run the docker image

# note: when using PowerShell, use '`' instead of '\'
docker run --rm -it \
  -p 7266:8080 \
  -v pdfviewer-data:/Data \
  -e "ApplicationPublicKey=your-public-key" \
  -e "ApplicationPrivateKey=your-private-key" \
  -e "LicensePublicKey=online-public-key" \
  -e "LicensePrivateKey=online-private-key" \
  -e "JwtSecret=insert-your-secret-here" \
  ghcr.io/tallcomponents/unopdf-server

• -p (port) specifies the port mapping. The 7266 refers to the exposed port. You can choose a different port here if desired.
• -v (volume) specifies where the data (pdfs) from the unopdf-server should be stored. This can be a docker Volume, as shown above, or a path on the local file system. For more information see https://docs.docker.com/storage/.
• ApplicationPublicKey and ApplicationPrivateKey specify the keys that the PdfApplication component must use to authenticate with the api. You are free to define any string values here.
• LicensePublicKey and LicensePrivateKey specify the keys that server must use to authenticate with the online license server. This should correspond with a valid enabled Application created at https://account.tallcomponents.com/. Also, this Application must be marked for OnPremise use by TallComponents Support.
• JwtSecret needs to be provided as signing key for the used authentication. This secret should be produced by a strong pseudo-random generator and must not be shared anywhere else. The minimum length is 64 characters.

Test by browsing to http://localhost:7266/v1/version. This should give a response similar to:

{"apiVersion":"1.0.2","minimumNpmPackageVersion":"1.0.0"}

Using HTTPS

To use Docker over HTTPS, you will need a certificate from a certificate authority (or self-signed for use with localhost). See these instructions for further details.

The following commands generate a self-signed certificate and configure the local machine, then run the Docker image.

# Note: you are defining "my-secret-password" at this point;
# use the same value in the "ASPNETCORE_Kestrel__Certificates__Default__Password" parameter below.
dotnet dev-certs https -ep $USERPROFILE/.aspnet/https/aspnetapp.pfx -p my-secret-password
dotnet dev-certs https --trust

MSYS_NO_PATHCONV=1 docker run --rm -it -p 7266:443 \
               -v pdfviewer-data:/Data \
               -e "ApplicationPublicKey=your-public-key" \
               -e "ApplicationPrivateKey=your-private-key" \
               -e "LicensePublicKey=online-public-key" \
               -e "LicensePrivateKey=online-private-key" \
               -e "JwtSecret=insert-your-secret-here" \
               -e ASPNETCORE_URLS="https://+;http://+" \
               -e ASPNETCORE_Kestrel__Certificates__Default__Password="my-secret-password" \
               -e ASPNETCORE_Kestrel__Certificates__Default__Path=/https/aspnetapp.pfx \
               -v $USERPROFILE/.aspnet/https://https \
               ghcr.io/tallcomponents/unopdf-server

If the command above above succeeds, you should be able to go to https://localhost:7266/v1/diagnostics, with no browser certificate warnings.

Docker compose

You can also use docker compose to run your container:

version: "3.0"
services:
  api:
    image: ghcr.io/tallcomponents/unopdf-server
    ports:
      - 7266:${CONTAINER_PORT}
    environment:
      - ApplicationPublicKey=${ApplicationPublicKey}
      - ApplicationPrivateKey=${ApplicationPrivateKey}
      - LicensePublicKey=${LicensePublicKey}
      - LicensePrivateKey=${LicensePrivateKey}
      - JwtSecret=${JwtSecret}
      - ASPNETCORE_URLS=${ASPNETCORE_URLS}
      - ASPNETCORE_Kestrel__Certificates__Default__Password=${ASPNETCORE_Kestrel__Certificates__Default__Password}
      - ASPNETCORE_Kestrel__Certificates__Default__Path=${ASPNETCORE_Kestrel__Certificates__Default__Path}

    volumes:
      - pdfviewer-data:/Data
      - ${CERTIFICATE_DIR}:/https

# This creates a docker volume named 'pdfviewer-data', which mounts to `/Data` inside the container.
# To use the local file system, remove below lines and provide a path instead of 'pdfviewer-data' above.
volumes:
  pdfviewer-data:

This docker compose file assumes that there is a .env file with the following settings, or that these settings are added to the environment in another way:

## Server source port
# This must be 443 to enable https and 80 to enable http.
# We recommend 443 for https.
CONTAINER_PORT=443

## Choose a random public key and private key
ApplicationPublicKey=application-public-key
ApplicationPrivateKey=application-private-key

## Specify the public key and private key for the licence
# You will receive these from TallComponents
LicensePublicKey=<tall components licence public key>
LicensePrivateKey=<tall components licence private key>

## Choose a random jwt secret.
# It needs to be provided as signing key for the used authentication.
# This secret should not be shared anywhere else. We encourage to provide an at least 64 characters long string.
JwtSecret=insert-your-secret-here

## ASP Settings
# Enable https traffic
ASPNETCORE_URLS=https://+

## Certificate password
# Use the password used to generate the certificate. See https://unopdf.tallcomponents.com/guide/self-hosting/selfhosted/#using-https
ASPNETCORE_Kestrel__Certificates__Default__Password=certificate-password

## Cerfiticate location
# You should configure a docker volume for container path /https. This is the location where the certificate is stored.
# See https://unopdf.tallcomponents.com/guide/self-hosting/selfhosted/#using-https
ASPNETCORE_Kestrel__Certificates__Default__Path=/https/aspnetapp.pfx

CERTIFICATE_DIR=~/.aspnet/https

Configure front-end

Configuration of the front-end is done by setting the api-base-url property of the pdf-application element as follows:

<pdf-application
  api-base-url="http://localhost:7266/"
  publickey="above-defined-public-key"
  privatekey="above-defined-private-key"
/>

For more information, see pdf-application.

About OnPremiseLicenseCheck

The on-premise server will periodically check for a valid license. This is done by making a request to https://api.unopdf.com/. For this to work, the on-premise server must be able to connect to this external server. For transparency, all license checking activity will be logged to the console.