Skip to main content

Installation

Vizlib Server for Qlik Cloud (Qlik Sense SaaS) is provided as a Docker container. It is separate from the Windows installer provided for Vizlib Server with Qlik Sense Enterprise.

Note: Vizlib Server for Qlik Cloud can only be used with Qlik Cloud, and Vizlib Server for Qlik Sense Enterprise can only be used with Qlik Sense Enterprise. The two are not interchangeable.

This topic contains the following sections:

  1. Prerequisites and checklist

  2. Copy Vizlib Server license key from Vizlib Portal

  3. Download Vizlib Server docker container and extensions from Vizlib Portal

  4. Download and install Docker Engine on a Linux server

  5. Copy files to the Linux server

  6. Modify docker and haproxy configuration

  7. Start the docker containers

  8. Verify that the container is running

  9. Configure domain

  10. Sign in to Vizlib Management Console (VMC)

  11. Install/Update extensions

  12. Enable API keys and generate an API key in Qlik Cloud

  13. Create an OAuth client in Qlik Cloud

  14. Create Content Security Policy in Qlik Cloud

  15. Configure the Qlik Cloud section in VMC

  16. Create Security rules for Content Admins

  17. Create a Data Space — VizlibWritebackDemoData

  18. Add API Key user to the Data Space with edit rights

  19. Create a Shared Space — Vizlib Collaboration DEV

  20. Add API Key user to the Shared Space with edit rights

  21. Upload the Getting started demo application to Qlik Cloud

  22. Create a destination in VMC for the Update operation

  23. Configure the demo application

  24. Do writeback in the demo application

1. Prerequisites and checklist

Before you start the installation, make sure you have all the information and permissions you need. Work through every item in this checklist so you are ready to proceed.

  • Qlik Cloud tenant

    • A user with a professional license and the developer and tenant admin roles.

  • Linux server

    • A public domain with DNS configured to point to the server's IP address.

    • Windows Server (2019 and later) is supported but requires a paid Docker subscription to run Linux containers. We recommend a Linux server because it is cheaper and more stable.

  • Certificate

    • A PEM file that includes the certificate and the private key.

    • The certificate must be issued for the public domain of the server.

2. Copy the Vizlib Server license key from Vizlib Portal

  1. Open a browser and go to home.vizlib.com.

  2. Click Log in and sign in to the Vizlib Portal.

  3. Click the Vizlib Server section under Products.

  4. Click Copy Key to copy your Vizlib Server license key.

    Figure 1:  Vizlib Server section in the Vizlib Portal

  5. Store the key in a safe place. You will need it for the VIZLIB_SERVER_LICENSE environment variable when you modify the docker-compose.yml in step 6.

3. Download Vizlib Server docker container and extensions from Vizlib Portal

3.1 Download the Vizlib Server container

  1. On the Vizlib Server page in the Vizlib Portal, click Saas Versions under Download product in the panel on the right.

  2. Select the latest version of Vizlib Server for Qlik Cloud and download it.

    Figure 2:  SaaS version download pop-up

  3. Note the version number. You need it in the next step to verify extension compatibility.

3.2 Download the compatible extensions

  1. Click the Collaboration section under Products.

  2. Click Extensions under Download product in the panel on the right. The Extensions pop-up opens.

    Figure 3:  Extensions pop-up

  3. Type Table in the search field to filter for Vizlib Writeback Table versions.

  4. Find the latest version compatible with the Server version you downloaded and click Offline download.

  5. Replace Table with Input in the search field to filter for Vizlib Input Form versions.

  6. Find the latest compatible version and click Offline download.

Note: Always download the offline version of the extensions. The online version updates automatically and can become incompatible with the installed Vizlib Server version. Extensions and Vizlib Server must be upgraded at the same time to keep versions compatible.

4. Download and install Docker Engine on a Linux server

Before you can run the Vizlib Server for Qlik Cloud container, install the Docker Engine on a Linux server.

Note: The steps below use Google Cloud Platform (GCP) as an example. The same general process applies to Amazon Web Services (AWS), Azure, or a private cloud, although procedures differ by platform. Running Docker Engine on Windows Server (2019+) requires a paid subscription and is not covered in this guide. We recommend Linux for cost and stability.

4.1 Create the VM instance

  1. Log in to the Google Cloud console at console.cloud.google.com.

  2. Navigate to Compute Engine > VM Instances.

  3. Click CREATE INSTANCE.

  4. Configure the instance:

    • Give the instance a Name.

    • Select the Region where you want to host it.

    • Select the e2-micro machine type. We recommend starting small (1 GB) and upgrading only if usage requires more CPU or memory. Vizlib Server is single-threaded and does not benefit from additional cores.

    • Check Allow HTTP traffic.

    • Check Allow HTTPS traffic.

  5. Click CREATE.

    Figure 4:  New VM instance configuration

  6. Once the instance is running, click the SSH button (or click the caret in the Connect column and select Open in browser window) to connect.

Note: If multiple administrators manage this instance, we recommend using a service account or configuring the instance with a shared SSH key. Setting up a shared SSH key is not covered in this guide.

4.2 Install Docker Engine and configure permissions

  1. Enter root mode:

    sudo sh -

  2. Run the following command to install Docker. If you are using a distribution other than Debian, modify the command accordingly.

    apt update && apt install --yes apt-transport-https ca-certificates curl gnupg2 software-properties-common && curl -fsSL https://download.docker.com/linux/debian/gpg | sudo apt-key add - && add-apt-repository "deb [arch=amd64] https://download.docker.com/linux/debian $(lsb_release -cs) stable" && apt update && apt install --yes docker-ce && curl -L "https://github.com/docker/compose/releases/download/1.26.2/docker-compose-$(uname -s)-$(uname -m)" -o /usr/local/bin/docker-compose && chmod +x /usr/local/bin/docker-compose

    Note: Vizlib Server has been tested on GCP with Debian 5.10.106-1.

  3. Press Ctrl + D to exit root mode.

  4. Add the current user to the docker user group:

    sudo usermod -aG docker $USER

  5. Close the browser window and reconnect with SSH for the group change to take effect.

4.3 Verify the Docker Engine installation

  1. Run the following command:

    docker run hello-world

  2. If the installation was successful, the output confirms that Docker is working correctly.

    Figure 5:  Successful execution of docker run hello-world

  3. If errors appear, resolve them before proceeding.

5. Copy files to the Linux server

  1. Unzip the VizlibServer-QlikCloud-Docker-vX.Y.Z archive downloaded from the Vizlib Portal.

  2. From the extracted files, you need only three:

    • docker-compose.yml — Rename the file docker-compose-example to docker-compose.yml, or run the provided setup file (which also generates this file). Only one of these options is necessary.

    • haproxy.cfg

    • vizlib-server.tar.gz

  3. In the SSH terminal, click the Upload file icon and upload the three files listed above.

  4. Upload the PEM certificate file (for example, cert.pem) to the same location. This file is required for HAProxy to serve Vizlib Server over HTTPS.

    Note: The certificate must be issued by a third-party certificate authority (for example, DigiCert or GoDaddy).

6. Modify docker and haproxy configuration

The provided configuration files are examples and must be modified before use.

6.1 Modify haproxy.cfg

  1. Open the file in the nano editor:

    nano haproxy.cfg

  2. Replace YOUR_DOMAIN_HERE with the fully qualified domain name (FQDN) of your server. The certificate must be issued for this same domain.

  3. Press Ctrl + X, then Y, then Enter to save and exit.

6.2 Modify docker-compose.yml

  1. Open the file in the nano editor:

    nano docker-compose.yml

    Figure 6:  docker-compose.yml in nano editor

  2. Update the following values:

    IMAGE

    Append the version number to the image name (for example, vizlib-server:4.7.0).

    Note: If the container is registered in a container registry (such as GCP Artifact Registry), set the image name to the registry URL with the correct version.
    CERTIFICATE_LOCATION_HERE

    Replace with the path to your PEM file. For example, if the file is named cert.pem, set the value to ./cert.pem:/etc/ssl/cert.pem. Only the left-hand side (before the colon) should match your file name; the right-hand side must remain unchanged.
    SERVER_LOGS_LOCATION_HERE

    Specify the log file location (for example, ./log:/log to store logs in a log subfolder next to docker-compose.yml).
    VIZLIB_VMC_PASSWORD

    Replace the default value (admin) with a strong password for the VMC root admin user.
    VIZLIB_DATABASE_URL

    This value must match the Postgres environment variables defined at the bottom of the file. If you leave the defaults unchanged, set this to postgres://sa:Pass123@postgres:5432/collaboration. If you use an external database, see section 6.3.
    PUT YOUR LICENSE HERE

    Paste only the eyJ... portion of the license key. Exclude the first line (for example, OwnerName=...).
    POSTGRES environment variables

    These define the database root-user credentials and the database name. If you change any of these from the defaults, update VIZLIB_DATABASE_URL to match.

  3. Press Ctrl + X, then Y, then Enter to save and exit.

6.3 (Optional) Use an external PostgreSQL server

The example docker-compose.yml includes a built-in Postgres container. We recommend using an external PostgreSQL server that is maintained and backed up regularly.

To switch to an external database:

  1. Remove the postgres service block and all lines below it from docker-compose.yml.

  2. Update the VIZLIB_DATABASE_URL connection string with values for your external server:

    USERNAME The database user for Vizlib Server.
    PASSWORD The password for that user.
    HOSTNAME The hostname or IP of the database server. Replace the default port (5432) if your server uses a different port.
    DATABASE_NAME The database name. The specified user must have write access and the ability to create tables.

  3. Save and exit.

7. Start the docker containers

  1. Load the Vizlib Server image into Docker Engine:

    docker load < vizlib-server.tar.gz

  2. Start the containers in detached mode:

    docker-compose up -d

8. Verify that the container is running

  1. Check the container logs for errors:

    docker logs vizlib-server

  2. If the container is running correctly, the output shows that Vizlib Server has started without errors.

    Figure 7:  Docker logs for vizlib-server container when running

9. Configure domain

Point your domain to the server's IP address.

  • If you use a GCP VM instance with Google Cloud DNS, follow the Google guide from step 4.

  • If your certificate is issued by a third-party provider, follow their instructions for setting up a DNS zone and connecting the server IP to the domain.

Note: Use a reserved (static) IP address so the IP does not change when the instance restarts.

10. Sign in to Vizlib Management Console (VMC)

  1. Open a browser and navigate to https://yourdomain.com/vmc.

  2. Enter the credentials configured in docker-compose.yml: the Username matches the VIZLIB_VMC_USERNAME variable and the Password matches VIZLIB_VMC_PASSWORD.

  3. Click Login.

    Figure 8:  Dashboard view after login

  4. Verify that the URL shows a padlock icon, confirming that HAProxy is serving the VMC securely over HTTPS. If HTTPS is not active, users will not be able to connect to Vizlib Server.

11. Install/Update extensions

Install the extensions downloaded from the Vizlib Portal. If you already have a previous version of the extensions installed, skip to 11.2 Update extensions.

11.1 Install extensions

  1. In the Qlik Cloud Management Console, navigate to the Extensions section.

  2. Click Add.

  3. Drop the Vizlib Input Form zip file into the upload area. Only one extension can be added at a time.

  4. After the Input Form is added, click Add again.

  5. Drop the Vizlib Writeback Table zip file into the upload area.

    Both extensions should now appear in the extensions list. Continue to section 12.

11.2 Update extensions

If you have a previous version of Vizlib Writeback Table or Vizlib Input Form installed, update them in place.

  1. In the Extensions section, click ... on the extension you want to update.

  2. Select Edit.

  3. Drop the new zip file into the upload area and click Save.

Note: Updating extensions preserves any tags applied to them. Deleting and re-installing removes tags.

11.3 Ensuring Extensions Connection with Vizlib Server

To ensure the connection between the extensions and Vizlib Server, you need to follow these steps:

  1. Navigate to Vizlib Management Console (VMC) > Dashboard. The software displays sections for extensions from each Vizlib product bundle and status for extension-to-Server connection.

    Figure 9:  No connection with Vizlib Server

  2. Click on the tile with an extension name and the status indicator for the extension-to-Server connection. The software adds a custom property allowing for connection of the extension with Vizlib Server.

    Figure 10:  The success icon indicating connection with Server

The connection of the extension to Vizlib Server has been established.

12. Enable API keys and generate an API key in Qlik Cloud

Vizlib Server uses the Qlik Cloud APIs to perform reloads and store data to QVDs. You must generate an API key for Vizlib Server to authenticate. The API key inherits the permissions of the user who generates it.

  1. In the Qlik Cloud Management Console, navigate to Configuration > Settings and scroll to the API keys section.

  2. If Enable API keys is not already on, enable it.

  3. We recommend extending the Maximum token expiration to 1000 days.

  4. Make sure you are signed in with the user who will own the API key. This user must have a professional license and the developer and tenant admin roles.

  5. Click Generate new.

  6. Fill in the API key description and select 3 years from the Expires in drop-down.

    Figure 11:  Generate a new API key

  7. Click Generate.

  8. Click Copy and close and store the API key in a secure place (for example, a password manager). You will need it when configuring the Qlik Cloud section in the VMC.

13. Create an OAuth client in Qlik Cloud

An OAuth client allows users to authenticate with Vizlib Server.

  1. In the Qlik Cloud Management Console, navigate to Integration > OAuth.

  2. Click Create new.

  3. Configure the OAuth client:

    • Enter a Name and Description.

    • Leave Redirect URLs empty — Vizlib Server populates them automatically when you save the Qlik Cloud configuration in the VMC.

    • Under Scopes, enable the user_default and offline_access checkboxes.

    Figure 12:  Create a new OAuth client

  4. Click Create.

  5. Click Copy to clipboard and store the Client ID and Client secret securely. You will need them in step 15.

  6. After the new OAuth client appears in the list, select it and configure the following additional settings:

    • Enable Allow Machine-to-Machine (M2M).

    • Enable Allow M2M user impersonation.

    • Change the Consent method to Trusted.

14. Create Content Security Policy in Qlik Cloud

A Content Security Policy (CSP) entry allows Qlik Cloud to communicate with Vizlib Server.

  1. In the Qlik Cloud Management Console, navigate to Integration > Content Security Policy.

  2. Click Add.

  3. Configure the policy:

    • Set the Name to Vizlib Server.

    • Enter the domain of your Vizlib Server in the Origin field (for example, vizlib-server.yourdomain.com).

    • Enable the connect-src, connect-src (WebSocket), and img-src checkboxes.

  4. Click Add to create the policy.

15. Configure the Qlik Cloud section in VMC

  1. In the VMC, navigate to System Settings > Qlik Cloud.

  2. Fill in the following fields:

    Tenant The URL of your Qlik Cloud tenant. Use the actual hostname, not an alias.
    API Key The API key generated in section 12.
    OAuth Client Id The Client ID created in section 13.
    OAuth Client Secret The Client Secret created in section 13.

  3. Click Save Changes. The OAuth client's Redirect URI is updated automatically.

  4. If an error appears, resolve the issue and save again.

  5. To confirm a successful connection, go to the Dashboard section in the VMC. A green check mark should appear next to Qlik Cloud API.

    Figure 13:  VMC

16. Create Security rules for Content Admins

To allow users to sign in to the VMC and create their own Writeback destinations, create a security rule.

  1. In the VMC, navigate to Security Rules.

  2. Click New Rule.

  3. Configure the rule:

    Field Value Description
    Description Content Admins A description of the security rule.
    Resource Type User Role Grants users the ability to sign in to the VMC with Qlik Cloud.
    Resource Id ContentAdmin

    Vizlib Server supports these user roles:

    • Content Admin — Can edit public settings and create integrations, streams, destinations, security rules, and workflows. Cannot edit settings created by other users or access Server Settings (except Integrations). Cannot restart the server or update the license.

    • Root Admin — Full access to all VMC sections (same as the account created during installation).

    • Admin — Full access to all sections except Server Settings and Qlik Sense settings. Can manage public and private integrations, streams, destinations, security rules, and workflows, including changing visibility.
    Attribute groups Use the groups attribute. If groups are not mapped in your Identity Provider, use email or name instead.
    Operator Equal Select Equal.
    Value for example, VMCContentAdmins The AD group whose members should receive Content Admin access.

  4. Click Create Security Rule.

Note: If more than one group needs Content Admin access, add additional conditions using the OR operator.

17. Create a Data Space — VizlibWritebackDemoData

Create a Data space to store the QVD files used by the demo application for writeback.

  1. In the Qlik Cloud Management Console, navigate to Spaces.

  2. Click Create new.

  3. Select Data from the Type drop-down.

  4. Name the space VizlibWritebackDemoData.

  5. Click Create.

18. Add API Key user to the Data Space with edit rights

Grant Vizlib Server write access to the new Data space by adding the API key user as a member. If the API key user is the owner of the space, skip this step.

  1. In the Spaces table, click ... on the VizlibWritebackDemoData row and select Manage members.

  2. Click Add members.

  3. Select the API key user and assign the Can edit role.

  4. Click Add members.

The API key user now has the permissions required to perform writeback to this space.

19. Create a Shared Space — Vizlib Collaboration DEV

Applications uploaded to a personal space are not accessible to the API key user. Use a Shared space so the API key user can open and reload the application.

  1. In the Qlik Cloud Management Console, navigate to Spaces.

  2. Click Create new.

  3. Select Shared from the Type drop-down.

  4. Name the space Vizlib Collaboration DEV.

  5. Click Create.

20. Add API Key user to the Shared Space with edit rights

Grant Vizlib Server access to the Shared space. If the API key user is the owner, skip this step.

  1. In the Spaces table, click ... on the Vizlib Collaboration DEV row and select Manage members.

  2. Click Add members.

  3. Select the API key user and assign the Can edit or Can manage role.

  4. Click Add members.

21. Upload the Getting started demo application to Qlik Cloud

  1. Download the demo application Getting started with Vizlib Writeback in Qlik Cloud.qvf from this link or from the attachments at the bottom of this page.

  2. In Qlik Cloud, go to the home section under Analytics Services.

  3. Click + Add new and select Upload app.

  4. Drag the .qvf file into the upload area.

  5. Select Vizlib Collaboration DEV from the Space drop-down.

  6. Click Upload.

22. Create a destination in VMC for the Update operation

Configure a Writeback destination for the demo application's Update operation.

  1. In the VMC, navigate to Writeback Settings > Destinations.

  2. Click Add Destination.

  3. Configure the destination:

    • Set the Id to VizlibWritebackDemoData.

    • Under Reload Options, select Reload App.

    • Add the dynamic tag APP.ID by clicking the + icon inside the App input and selecting Id. This ensures the destination reloads whichever application triggered the writeback, which is useful when multiple apps share the same destination.

    • In the Space input, select VizlibWritebackDemoData.

    • Enable File name set by the extension. The demo application uses multiple Writeback Tables and Input Forms that write to different QVD files, so the extension must control the file name.

  4. To restrict which file names the destination accepts, add a whitelist. Copy all of the following values and paste them into the Add new File Name input (all 14 values are added at once):

    Settings
    ColumnShowcase
    ScatterSalesDate
    EmployeeForm
    EventLog
    LiveTotals
    IconOptions
    CountryOptions
    UserDirectoryOptions
    DropdownOptions
    Variables
    ColorVariables
    InsertAuditData
    RequiredIf

    Note: If the whitelist is left empty, all file names are allowed.

  5. Click Add Destination.

23. Configure the demo application

  1. In Qlik Cloud, go to Catalog and filter by the Vizlib Collaboration DEV space.

  2. Hover over the application and click Open App.

  3. Open the Data load editor.

  4. Review the README section of the load script and update the configuration values as instructed.

    Figure 14:  README section of the load script

  5. Click Load data to reload the application.

  6. After a successful reload, verify that the QVD files were created. In the Add data panel on the right, select the VizlibWritebackDemoData space and click Select data to open the file explorer.

    Figure 15:  Generated files in the VizlibWritebackDemoData space

Note: Qlik Cloud does not support folders. File names can contain / characters, but this does not create a folder structure as it does in Qlik Sense Enterprise.

24. Do writeback in the demo application

  1. Navigate to the application's sheets. An OAuth pop-up window may be blocked by the browser.

    If the pop-up is blocked, click the blocked pop-up icon in the browser address bar and select Always allow pop-ups and redirects for your Qlik Cloud tenant.

  2. Authenticate in the OAuth window using the Identity Provider configured with your tenant.

  3. On the consent screen, click Approve to grant the OAuth client offline_access for your user.

    Note: If the authentication process times out, reload the page and try again.

  4. After successful sign-in, the Input Form displays on the first sheet. Navigate to the next sheet — you will not be prompted to authenticate again because Vizlib Server has created a session cookie.

  5. Make some changes in the Vizlib Writeback Table and click Update to perform your first writeback.

    Figure 16:  Vizlib Writeback Table with updated values

  6. Wait for the export and reload to complete. Once finished, the updated values are reflected in the data model and in the Writeback Table.

    Figure 17:  Successful writeback

Note: Writeback in Qlik Cloud is slower than in Qlik Sense Enterprise because of architectural differences. Reloads can be delayed if Qlik Cloud needs to start a reload pod or if reloads are queued. On Qlik Cloud Business, reload pods are shared across tenants, which can cause additional queuing. For shorter reload times, consider upgrading to Qlik Cloud Enterprise and purchasing dedicated reload pods from Qlik. Note that an Enterprise license alone does not eliminate queuing — dedicated pods are required.

Congratulations — you have completed your first writeback using Vizlib Server for Qlik Cloud!

Attachments

Was this article helpful?

We're sorry to hear that.