Installing and running DataLens On-premises

System requirementsSystem requirements

1. Operating systems:

   • Ubuntu 20.04/22.04/24.04
   • Debian 10/11/12
   • CentOS 7
   • Astra Linux 1.7
   • Oracle Linux 8/9
   • RedHat Linux 8/9
   • CentOS Stream 8/9

   Note

   The solution was checked for operability only with Debian-based distributions.

2. Minimum system requirements for deployment:

   • vCPUs: 8
   • RAM: 16 GB
   • SSD: 40 GB

3. Managed Service for PostgreSQL cluster requirements:

   Note

   We recommend using a separate Managed Service for PostgreSQL cluster in a fault-tolerant configuration (master + one replica).

   • Minimum requirements for the cluster:

     • vCPUs: 4
     • RAM: 8 GB
     • SSD: 100 GB

   • When deploying a high load cluster, you should calculate the consumption based on the number of users.

   • The following extensions are required for the United Storage PostgreSQL database:

     • pg_trgm
     • btree_gin
     • btree_gist
     • uuid-ossp

     They are installed automatically if the user has the relevant permissions.

   • When deploying a Managed Service for PostgreSQL DB cluster in Yandex Cloud for United Storage:

     • Specify the above-listed extensions in the management console manually.
     • Set the Collation (sorting) locale (LC_COLLATE) and Character set locale (LC_CTYPE) parameters to en_US.UTF-8. This will ensure effective indexing to search for users.

Deploying DataLens On-premisesDeploying DataLens On-premises

1. Use the provided link to download the DataLens On-premises distribution archive, e.g., like this:

   URL="..."
   curl -L -o datalens-enterprise.tar "${URL}"
   

2. Unpack the distribution into the datalens-enterprise directory.

   mkdir -p ./datalens-enterprise && tar -xvf datalens-enterprise.tar --directory ./datalens-enterprise
   

3. Navigate to the distribution directory:

   cd ./datalens-enterprise
   

   If deploying on a remote VM, consider executing all these commands at once:

   URL="..."
   curl -L "${URL}" -o datalens-enterprise.tar
   mkdir -p ./datalens-enterprise && tar -xvf datalens-enterprise.tar --directory ./datalens-enterprise
   cd ./datalens-enterprise
   

4. The distribution is deployed using the ./init.sh script residing in the root of the archive. The script allows you to deploy DataLens On-premises in your existing Kubernetes cluster. If you do not have a Kubernetes cluster, the script is able to deploy it on your VM.

   You can run deployment from the linux/amd64 server the installation will take place on. You can also do so from a remote VM with access to a linux/amd64 or mac/arm64 Kubernetes cluster.

   Example of using the script:

   ./init.sh [arguments]
   

   How the script works:

   • The script checks the distribution for integrity each time by verifying checksums and saves the resulting values into deployment variables.

   • When the script is run with the --k3s-install argument, a K3S Kubernetes cluster is installed automatically without access to the public network.

   • When launched with the --atomic argument, the entire deployment (or update) operation is treated as a single transaction that either completes successfully or is rolled back entirely.

   • RSA keys for the authentication and authorization service are generated automatically on first installation if not explicitly specified otherwise.

   • Use the --values argument to specify the values.yaml custom file for redefinition of Helm chart deployment parameters and a more accurate environment set-up.

     Note

     Do not edit the original ./helm/values.yaml file. Use a copy of the original file or a copy of the ./help/values.example.yaml example file.

   • If you set the KUBECONFIG environment variable before running the script, the script will connect to an already existing Kubernetes cluster for deployment.

   • The Helm chart does not specify CPU limits for application containers to prevent throttling of the whole application, as recommended in the Kubernetes documentation.

After each deployment, a file named ./values.debug.yaml is generated to store all parameters other than the secrets. This file can help you diagnose the system when contacting support.

Specifics of deployment on Oracle LinuxSpecifics of deployment on Oracle Linux

To run a K3s Kubernetes cluster on Oracle Linux 8/9, you must either disable firewalld completely or configure the relevant rules for correct operation of the Kubernetes network.

sudo firewall-cmd --permanent --zone=trusted --add-interface=cni0
sudo firewall-cmd --permanent --zone=trusted --add-interface=flannel.1
sudo firewall-cmd --reload

Main ports used by K3s:

Examples for firewalld:

sudo systemctl stop firewalld
sudo systemctl disable firewalld

# traffic between k8s pod network subnets
sudo firewall-cmd --permanent --zone=trusted --add-source=10.42.0.0/16
sudo firewall-cmd --permanent --zone=trusted --add-source=10.43.0.0/16
# or
sudo firewall-cmd --permanent --zone=trusted --add-interface=cni0
sudo firewall-cmd --permanent --zone=trusted --add-interface=flannel.1


# k8s api server access for all nodes (optional)
sudo firewall-cmd --permanent --add-port=6443/tcp
# client requests to etcd and peer communication between etcd members (optional)
sudo firewall-cmd --permanent --add-port=2379-2380/tcp
# kubelet api port on each node (optional)
sudo firewall-cmd --permanent --add-port=10250/tcp
# flannel vxlan pod network communication (optional)
sudo firewall-cmd --permanent --add-port=8472/udp
# node port external traffic (optional)
sudo firewall-cmd --permanent --add-port=30000-32767/tcp

sudo firewall-cmd --reload

If the firewall does not interfere with cluster operation, you may only want to configure the required ports rather than disable it entirely. This will help ensure basic system security with settings acceptable for Kubernetes.

Available deployment argumentsAvailable deployment arguments

Available script deployment arguments with examples for typical configurations:

Deployment processDeployment process

Updating a distributionUpdating a distribution

Kubernetes (K3s) configurationKubernetes (K3s) configuration

Helm chart configurationHelm chart configuration

Docker image managementDocker image management

Configuration of the authentication and authorization serviceConfiguration of the authentication and authorization service

Ingress configurationIngress configuration

Self-signed root certificatesSelf-signed root certificates

Key featuresKey features

PostgreSQL database managementPostgreSQL database management

Performance and scalingPerformance and scaling

Command line toolsCommand line tools

Examples of typical deployment commandsExamples of typical deployment commands

• Basic installation with K3s on a VM with automatic generation of self-signed certificates:

  ./init.sh \
  --k3s-install \
  --ingress-domain <domain> \
  --ingress-tls \
  --ingress-tls-gen
  

• Deployment on a domain with custom TLS certificates:

  ./init.sh \
  --k3s-install \
  --ingress-domain <domain> \
  --ingress-tls-crt <crt-file> \
  --ingress-tls-key <key-file>
  

• Mirroring images to a private Docker image registry:

  ./init.sh \
  --docker-image-load \
  --docker-image-push \
  --docker-registry <registry-url> \
  --docker-config <docker-config-json-file>
  

• Deployment with custom authentication providers configured:

  ./init.sh --auth-providers-config <auth-provider-config-json-file>
  

• Deployment with parameters configured via a custom values.yaml file:

  ./init.sh --values <values-file>
  

• Getting the administrator password from secrets after deployment:

  ./init.sh --get-admin-password
  

• Deployment with AI Assistant setup:

  ./init.sh --ai-endpoint <ai-endpoint> --ai-model-name <ai-model-name> --ai-api-token <ai-api-token> 
  

  e.g., for Yandex Cloud AI Studio:

  ./init.sh --ai-endpoint https://ai.api.cloud.yandex.net/v1 --ai-model-name gpt://<folder_id>/deepseek-v4-flash/latest --ai-api-token <API_key> 
  

Examples of auxiliary commandsExamples of auxiliary commands

• Getting all logs from all DataLens pods for debugging:

  ./init.sh --stern . -o extjson > datalens.enterprise.log
  

• Getting all Kubernetes cluster events for deployment error debugging:

  ./init.sh --kubectl events
  

Description of all parametersDescription of all values.yamlparameters

The values.yaml file contains a configuration for DataLens On-premises deployment via Helm charts. The following parameters are available:

• Docker image registry configuration
• Release version
• Ingress resource configuration
• Infrastructure
• Application configuration
• Secrets
• PostgreSQL configuration
• Visible connectors
• Key features
• Checksum

Docker image registry configurationDocker image registry configuration

registry:
  private: true
  url: ''

Release versionRelease version

release_version: '25.6.0'

Ingress resource configurationIngress resource configuration

ingress:
  enabled: true
  domain: datalens.enterprise
  np: false
  tls:
    enabled: false
    secret:
      crt: null
      key: null

InfrastructureInfrastructure

infra:
  postgres:
    enabled: true
    extra_envs: []
    resources:
      requests:
        cpu: 1
        memory: 512Mi
        storage: 1Gi
      limits:
        memory: 1024Mi
    tls:
      enabled: false
      secret:
        ref: null
        ca: null
  clickhouse:
    enabled: false
    extra_envs: []
    resources:
      requests:
        cpu: 1
        memory: 512Mi
        storage: 10Gi
      limits:
        memory: 1024Mi
    tls:
      enabled: false
      secret:
        ref: null
        ca: null
  redis:
    enabled: false
    extra_envs: []
    resources:
      requests:
        cpu: 0.5
        memory: 128Mi
        storage: 512Mi
      limits:
        memory: 256Mi
    tls:
      enabled: false
      secret:
        ref: null
        ca: null
  s3:
    enabled: false
    extra_envs: []
    resources:
      requests:
        cpu: 0.5
        memory: 128Mi
        storage: 1Gi
      limits:
        memory: 256Mi
  temporal:
    enabled: false
    extra_envs: []
    resources:
      requests:
        cpu: 0.5
        memory: 256Mi
      limits:
        memory: 512Mi
  fluent_bit:
    enabled: false
    extra_envs: []
    resources:
      requests:
        cpu: 0.1
        memory: 128Mi
      limits:
        memory: 128Mi

Using the extra_envs parameter, you can override or expand environment variables, e.g., for PostgreSQL:

  postgres:
    enabled: true
    extra_envs: 
      - name: MY_VAR
        value: test123
      - name: MY_VAR_SECRET
        valueFrom: 
          secretKeyRef:
            name: test-secret
            key: test-secret-key

Application configurationApplication configuration

application:
  control_api:
    replicas: 1
    version: '...'
    maxSurge: 50%
    maxUnavailable: 0
    extra_envs: []
    resources:
      requests:
        cpu: 1
        memory: 2048Mi
      limits:
        memory: 4096Mi
  data_api:
    replicas: 1
    version: '...'
    maxSurge: 50%
    maxUnavailable: 0
    extra_envs: []
    resources:
      requests:
        cpu: 1
        memory: 2048Mi
      limits:
        memory: 4096Mi
  ui:
    replicas: 1
    version: '...'
    maxSurge: 50%
    maxUnavailable: 0
    extra_envs: []
    resources:
      requests:
        cpu: 1
        memory: 512Mi
      limits:
        memory: 1024Mi
  ui_api:
    replicas: 1
    version: '...'
    maxSurge: 50%
    maxUnavailable: 0
    extra_envs: []
    resources:
      requests:
        cpu: 0.5
        memory: 256Mi
      limits:
        memory: 512Mi
  us:
    replicas: 1
    version: '...'
    maxSurge: 50%
    maxUnavailable: 0
    extra_envs: []
    resources:
      requests:
        cpu: 1
        memory: 512Mi
      limits:
        memory: 1024Mi
  auth:
    replicas: 1
    version: '...'
    maxSurge: 50%
    maxUnavailable: 0
    extra_envs: []
    resources:
      requests:
        cpu: 1
        memory: 512Mi
      limits:
        memory: 1024Mi
  meta_manager:
    replicas: 1
    version: '...'
    maxSurge: 50%
    maxUnavailable: 0
    extra_envs: []
    resources:
      requests:
        cpu: 0.5
        memory: 256Mi
      limits:
        memory: 512Mi
  file_secure_reader:
    replicas: 1
    version: '...'
    maxSurge: 50%
    maxUnavailable: 0
    extra_envs: []
    resources:
      requests:
        cpu: 0.5
        memory: 256Mi
      limits:
        memory: 512Mi
  file_uploader_worker:
    replicas: 1
    version: '...'
    maxSurge: 50%
    maxUnavailable: 0
    extra_envs: []
    resources:
      requests:
        cpu: 0.5
        memory: 256Mi
      limits:
        memory: 512Mi
  file_uploader_api:
    replicas: 1
    version: '...'
    maxSurge: 50%
    maxUnavailable: 0
    extra_envs: []
    resources:
      requests:
        cpu: 1
        memory: 256Mi
      limits:
        memory: 512Mi

Each app component has the following parameters:

Available application components:

• control_api: Connection and dataset management service.
• data_api: Source query processing service.
• ui: User interface.
• ui_api: Utility service for private API of dashboards and charts.
• us: United Storage to manage the storage of all the system's operating data.
• auth: Authentication service.
• meta_manager: Deferred task processing manager.
• file_secure_reader: File secure reading service.
• file_uploader_worker: File uploading and processing service.
• file_uploader_api: File uploading API service.

Using the extra_envs parameter, you can allow override or expand the environment variables of an application component, e.g., for the control_api component:

application:
  control_api:
    replicas: 1
    version: '...'
    maxSurge: 50%
    maxUnavailable: 0
    extra_envs: 
      - name: MY_VAR
        value: test123
      - name: MY_VAR_SECRET
        valueFrom: 
          secretKeyRef:
            name: test-secret
            key: test-secret-key
    resources:
      requests:
        cpu: 1
        memory: 2048Mi
      limits:
        memory: 4096Mi

SecretsSecrets

secrets:
  ref: null
  #
  AUTH_TOKEN_PRIVATE_KEY: null
  AUTH_TOKEN_PUBLIC_KEY: null
  AUTH_PROVIDERS_CONFIG: null
  AUTH_ADMIN_PASSWORD: null
  AUTH_CALLBACK_COOKIE_SECRET: null
  #
  CSRF_SECRET: null
  #
  AUTH_MASTER_TOKEN: null
  US_MASTER_TOKEN: null
  FILE_UPLOADER_MASTER_TOKEN: null
  EXPORT_DATA_VERIFICATION_KEY: null
  #
  CONTROL_API_CRYPTO_KEY: null
  #
  DOCKER_CONFIG_JSON: null
  #
  POSTGRES_PASSWORD_ROOT: null
  POSTGRES_PASSWORD_US: null
  POSTGRES_PASSWORD_COMPENG: null
  POSTGRES_PASSWORD_AUTH: null
  POSTGRES_PASSWORD_TEMPORAL: null
  POSTGRES_PASSWORD_META_MANAGER: null
  POSTGRES_PASSWORD_DEMO: null
  #
  TEMPORAL_AUTH_PRIVATE_KEY: null
  TEMPORAL_AUTH_PUBLIC_KEY: null
  #
  CLICKHOUSE_PASSWORD: null
  #
  REDIS_PASSWORD: null
  #
  S3_ACCESS_KEY_ID: null
  S3_SECRET_ACCESS_KEY: null

PostgreSQL configurationPostgreSQL configuration

postgres:
  POSTGRES_HOST: postgres-cip
  POSTGRES_PORT: '5432'
  POSTGRES_USER_AUTH: pg-auth-user
  POSTGRES_DB_AUTH: pg-auth-db
  POSTGRES_USER_COMPENG: pg-compeng-user
  POSTGRES_DB_COMPENG: pg-compeng-db
  POSTGRES_USER_US: pg-us-user
  POSTGRES_DB_US: pg-us-db
  POSTGRES_USER_META_MANAGER: pg-meta-manager-user
  POSTGRES_DB_META_MANAGER: pg-meta-manager-db
  POSTGRES_USER_DEMO: pg-demo-user
  POSTGRES_DB_DEMO: pg-demo-db
  POSTGRES_USER_TEMPORAL: pg-temporal-user
  POSTGRES_DB_TEMPORAL: pg-temporal-db
  POSTGRES_DB_TEMPORAL_VISIBILITY: pg-temporal-visibility-db

ClickHouse® configurationClickHouse® configuration

clickhouse:
  CLICKHOUSE_HOST: clickhouse-cip
  CLICKHOUSE_PORT: '8123'
  CLICKHOUSE_USER: ch-user
  CLICKHOUSE_DB_USAGE_TRACKING: ch-usage-tracking-db
  CLICKHOUSE_TABLE_USAGE_TRACKING: ch-usage-tracking-table

Valkey™ configurationValkey™ configuration

redis:
  REDIS_HOSTS:
    - redis-cip
  REDIS_PORT: '6379'
  REDIS_CLUSTER_NAME: null
  REDIS_DB_CACHE_DATA: '0'
  REDIS_DB_CACHE_MUTATIONS: '1'
  REDIS_DB_FILE_API: '9'
  REDIS_DB_FILE_WORKER: '11'

S3 configurationS3 configuration

s3:
  S3_ENDPOINT: http://s3-cip:9000
  S3_BUCKET_TEMPORARY: dl-file-uploader-tmp
  S3_BUCKET_PERSISTENT: dl-file-uploader

Temporal configurationTemporal configuration

temporal:
  TEMPORAL_ENDPOINT: temporal-cip:7233

Available connectorsAvailable connectors

visible_connectors:
  - clickhouse
  - postgres
  - chyt
  - ydb
  - mysql
  - greenplum
  - mssql
  - oracle
  - trino
  - metrika_api
  - appmetrica_api

Key featuresKey features

features:
  auth:
    enabled: true
    local: true
    skip_local: false
    force_redirect_open_id: false
  meta_manager:
    enabled: false
  ui_api:
    enabled: false
  demo:
    enabled: true
  hc:
    enabled: true
    endpoint: ''
    protocol: ''
  yandex_map:
    enabled: false
    token: ''
  editor:
    enabled: false
  export:
    enabled: false
  background_exports:
    enabled: false
  compeng_sidecar:
    enabled: false
  usage_tracking:
    enabled: false
  files:
    enabled: false
  cache:
    enabled: false
  sec_embeds: 
    enabled: false
  auth_cookie:
    enabled: false
    domain: ''
  ai:
    enabled: false
    api_token: ''
    model_name: ''
    endpoint: ''
    model_context_window_size: ''
    extra_headers: ''

System configurationSystem configuration

config:
  cpu_request_scale: 1.0

ChecksumChecksum

checksum: null

NotesNotes

1. If the Highcharts library is disabled in DataLens On-premises, the Gravity Charts library is used instead.

2. After each deployment, a file named ./values.debug.yaml is generated with all deployment parameters saved in it except for secrets. This file may be of use for initial system performance diagnostics when you contact support.

3. If ?full_login_page=true is sent to the URL, all authentication methods available by default are displayed.

4. To use the Usage Tracking features with an external ClickHouse® database, create tables in the target cluster using the following query:

   CREATE TABLE $CLICKHOUSE_DB_USAGE_TRACKING.$CLICKHOUSE_TABLE_USAGE_TRACKING
   ON CLUSTER '{cluster}' (
       event_time DateTime64(9),
       event_date Date,
       source_entry_id String,
       dash_id Nullable(String),
       dash_tab_id Nullable(String),
       chart_id Nullable(String),
       chart_kind Nullable(String),
       response_status_code Nullable(UInt64),
       dataset_id Nullable(String),
       user_id Nullable(String),
       request_id Nullable(String),
       query Nullable(String),
       source Nullable(String),
       connection_id Nullable(String),
       dataset_mode Nullable(String),
       username Nullable(String),
       execution_time Int64,
       status Nullable(String),
       error Nullable(String),
       connection_type Nullable(String),
       host Nullable(String),
       cluster Nullable(String),
       clique_alias Nullable(String),
       cache_used UInt8,
       cache_full_hit UInt8,
       endpoint_code Nullable(String),
       query_type Nullable(String),
       err_code Nullable(String),
       workbook_id Nullable(String)
   ) ENGINE = ReplicatedMergeTree('/clickhouse/tables/{shard}/$CLICKHOUSE_DB_USAGE_TRACKING.$CLICKHOUSE_TABLE_USAGE_TRACKING', '{replica}')
   PARTITION BY toYYYYMM(event_date)
   ORDER BY (toStartOfHour(event_time), connection_id, dash_id, dataset_id, chart_id, user_id, event_time)
   TTL event_date + toIntervalMonth(6)
   SETTINGS index_granularity = 8192, allow_nullable_key = 1;
   

   Where $CLICKHOUSE_DB_USAGE_TRACKING and $CLICKHOUSE_TABLE_USAGE_TRACKING are the database name and the ClickHouse® table name in your cluster.