Self-hosted

Run a docker image in your cloud to run queries against your database and power the dashboards your users see.

The fastest way to get started with the self-hosted docker image, is to use our Vizzly CLI, which you can install by running the following command;

npm i @vizzly/cli -g

To see all available commands, run vizzly -h.

Creating a key-pair

To create a private and public certificate key-pair to use with Vizzly, you can run the following command

vizzly create-key-pair

Creating a Vizzly config template

After creating your key-pair, you can run the following command to create a template of the Vizzly config:

vizzly init-config -i <<integration>>

Remember, you can run vizzly init-config --help to see how to use this command, and see a list of all available integrations.

Config file

The query engine requires some configuration to allow it to connect to your database, and to define virtual tables which are exposed to your users from which they can build their own dashboards.

In our examples repo (opens in a new tab), we have Vizzly config examples for each of our integrations (opens in a new tab).

We're using our CLI tool to validate these example configs, which you can read more about here should you wish to add this to your setup too.

File location

The Vizzly config file will need to be mounted into the Vizzly docker image, in the default location of /etc/vizzly/vizzly.config.json.

If you wish to customize the location of your Vizzly config file, you can do so using the VIZZLY_CONFIG_FILE runtime environment variable.

Connection credentials

The Vizzly docker image will need read-only access to your database. These credentials are specified in the Vizzly config file, and therefore the entire config file should be treated as a secret.

The typescript definition of the credentials is as follows:

{
  client: "postgres";
  connection: {
    password: string;
    database: string;
    user: string;
    host: string;
    port: number;
  }
}

Data sets

You'll need to define the available data sets for your users. You'll be able to define which data sets the user has access to in the identity callback.

The typescript definition of a data set is as follows:

{
  /*
    ID of the data set that remains constant.
  */
  id: string;
 
  /*
    A public name that describes this data set to your users.
  */
  name: string;
 
  /*
    Fields that define the flat schema of the data set.
  */
  fields: Array<{
    /*
      A unique reference to this field, and should remain constant.
    */
    id: string;
 
    /*
      The name of the field. For example, this would be the column
      name if you're running a postgres database.
    */
    name: string;
 
    /*
      What type of data does this field contain?
    */
    dataType: "number" | "boolean" | "string" | "date_time";
 
    /*
      The name of this field that your users will see.
    */
    publicName: string;
 
    /*
      The name of the table in the database
    */
    table: string;
  }>;
 
  joins: Array<{
    type:
      | "rightJoin"
      | "leftJoin"
      | "innerJoin"
      | "outerJoin"
      | "leftOuterJoin"
      | "rightOuterJoin";
    left: {
      field: string;
      table: string;
    };
    right: {
      field: string;
      table: string;
    };
  }>;
}

Joins

If you're using an integration with a SQL database, then in the Vizzly config file, it is possible to join fields that reside across multiple tables.

{
  "connection": {
    // ...
  },
  "dataSets": [
    {
      "id": "weather-by-city",
      "name": "Weather by city",
      "fields": [
        {
          "id": "field_1",
          "publicName": "City ID",
          "name": "id",
          "table": "cities",
          "dataType": "number"
        },
        {
          "id": "field_2",
          "publicName": "City",
          "name": "name",
          "table": "cities",
          "dataType": "number"
        },
        {
          "id": "field_3",
          "publicName": "Weather record ID",
          "name": "id",
          "table": "weather",
          "dataType": "number"
        },
        {
          "id": "field_4",
          "publicName": "City ID",
          "name": "city_id",
          "table": "weather",
          "dataType": "number"
        },
        {
          "id": "field_5",
          "publicName": "High temperature",
          "name": "high_temperature",
          "table": "weather",
          "dataType": "number"
        }
      ],
      "joins": [
        {
          "type": "leftJoin",
          "left": {
            "field": "id",
            "table": "cities"
          },
          "right": {
            "field": "city_id",
            "table": "weather"
          }
        }
      ],
      "secureFilterGuards": []
    }
    // ...
  ],
  "publicKeyCertificates": [
    // ...
  ]
}

Optional secure filter guards

Secure filters are used to provide Vizzly's multi-tenancy feature, and they are defined in the identity config. However if you want to reduce the impact of your private key being compromised, you can also define "secure filter guards" for each of the data sets. The purpose of a filter guard to limit the amount of data an attacker has access too if they manage to steal your private key used for Vizzly.

The typescript definition of a secure filter guard is as follows:

type Operator =
  | ">"
  | "<"
  | "="
  | "!="
  | ">="
  | "<="
  | "is_one_of"
  | "is_not_one_of"
  | "starts_with"
  | "ends_with"
  | "contains_substring"
  | "does_not_contain_substring";
 
{
  fieldId: string; // The `id` of the field
  op: Operator;
}

Environment variables

Some environment variables can be interpolated into the Vizzly config file. To see some examples of how this is done, please check out our config examples (opens in a new tab).

Limitations

Large numbers

Currently, the self-hosted docker image supports a precision of up to 9007199254740991. The accuracy of operations performed on numbers greater than this number may be incorrect.