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.
Expand to see an example of how you would join two tables on a foreign key city_id
.
{
"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).
PORT
The default port the query engine runs on is port 8000
. You can change this using the PORT
environment variable.
VIZZLY_QUERY_ENGINE_HOST
The protocol and host domain of the query engine. This excludes the base path which can be configured using the VIZZLY_BASE_PATH
variable.
For example https://query.example.co
would be a valid query engine host value.
This environment variable is required.
VIZZLY_BASE_PATH
This changes the base path of the Vizzly query engine. For example you might have a routing layer that matches requests for /vizzly-query-engine/*
, and forwards them too the
query engine. In which case, you'd set this value too /vizzly-query-engine
so the requests match the path matchers in the query engine.
This environment variable is not required, and defaults too ''
.
VIZZLY_CONFIG_FILE
Changes the path at which the config file resides inside the running container.
This environment variable is not required, and defaults to /etc/vizzly/vizzly.config.json
.
VIZZLY_POSTGRES_PASSWORD
Set the password to use in the connection to your postgres database.
To use this value in your Vizzly config file, set the value of the field to be "{{VIZZLY_POSTGRES_PASSWORD}}"
.
VIZZLY_POSTGRES_DATABASE
Set the name of the database to use in the connection to your postgres database.
To use this value in your Vizzly config file, set the value of the field to be "{{VIZZLY_POSTGRES_DATABASE}}"
.
VIZZLY_POSTGRES_USER
Set the username to use in the connection to your postgres database.
To use this value in your Vizzly config file, set the value of the field to be "{{VIZZLY_POSTGRES_USER}}"
.
VIZZLY_POSTGRES_HOST
Set the host to use in the connection to your postgres database.
To use this value in your Vizzly config file, set the value of the field to be "{{VIZZLY_POSTGRES_HOST}}"
.
VIZZLY_POSTGRES_PORT
Set the port to use in the connection to your postgres database.
To use this value in your Vizzly config file, set the value of the field to be "{{VIZZLY_POSTGRES_PORT}}"
.
PG_CONNECTION_STRING
Set the connection credentials using a single connection string.
To use this value in your Vizzly config file, set the value of the field to be "{{PG_CONNECTION_STRING}}"
.
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.