CloudBeaver Documentation

DOWNLOAD pdf

Server configuration

Table of contents

Overview

This article provides a guide to configuring CloudBeaver, using the main server configuration file (cloudbeaver.conf) and additional runtime settings. It explains how to set up various server parameters, including database connections, authentication settings, and resource quotas.

Note: Some configuration values support variables that can be set using command line arguments, optional settings when running Docker Desktop, or defined within the Docker Compose file. For more information on running CloudBeaver within Docker, see Build and deploy and Run Docker container.

Main server configuration

The main configuration file is cloudbeaver.conf. By default, you'll find it in the /opt/cloudbeaver/ folder.
If you want to use a different file, you can specify its location with the command line parameter -web-config <config-file-path>.

The server configuration uses a JSONC format (like JSON, but with comments and no extra quotes), so it's easy for most JSON parsers to handle.

You can also set configuration options in another file: /opt/cloudbeaver/workspace/.data/.cloudbeaver.runtime.conf. This is handy if you're using a shared Docker volume for the workspace. This file works the same as cloudbeaver.conf but takes priority, meaning its settings will override those in cloudbeaver.conf.

Tip: If you're using Docker, the .cloudbeaver.runtime.conf file can be especially useful for customizing configurations across different containers easily.

Note: All paths can be absolute or relative to the server start directory (or current directory).

Example configuration:

{
    server: {
        serverName: "CloudBeaver CE Server",
        serverURL: "http://localhost:8090",
        serverPort: "${CLOUDBEAVER_SERVICE_PORT:8978}",
        workspaceLocation: "${CLOUDBEAVER_WORKSPACE_LOCATION:workspace}",
        contentRoot: "web",
        driversLocation: "drivers",
        sslConfigurationPath:"${CLOUDBEAVER_SSL_CONF_PATH:workspace/.data/ssl-config.xml}",
        rootURI: "${CLOUDBEAVER_ROOT_URI:/}",
        serviceURI: "/api/",
        expireSessionAfterPeriod: "${CLOUDBEAVER_EXPIRE_SESSION_AFTER_PERIOD:1800000}",
        develMode: "${CLOUDBEAVER_DEVEL_MODE:true}",
        productSettings: {
            "core.localization.localization": "en",
            "core.theming.theme": "light",
            "plugin.log-viewer.disabled": false,
            "plugin.log-viewer.logBatchSize": 1000.0,
            "plugin.log-viewer.maxFailedRequests": 3.0,
            "plugin.log-viewer.maxLogRecords": 2000.0,
            "plugin.log-viewer.refreshTimeout": 3000.0,
            "plugin.sql-editor.autoSave": true,
            "plugin.sql-editor.disabled": false,
            "plugin.sql-editor.maxFileSize": 10240.0,
            "sql.proposals.insert.table.alias": "PLAIN"
        },
        database: {
            driver: "${CLOUDBEAVER_DB_DRIVER:h2_embedded_v2}",
            url: "${CLOUDBEAVER_DB_URL:jdbc:h2:${workspace}/.data/cb.h2v2.dat}",
            schema: "${CLOUDBEAVER_DB_SCHEMA:''}",
            user: "${CLOUDBEAVER_DB_USER:''}",
            password: "${CLOUDBEAVER_DB_PASSWORD:''}",
            initialDataConfiguration: "${CLOUDBEAVER_DB_INITIAL_DATA:conf/initial-data.conf}",
            pool: {
                minIdleConnections: "${CLOUDBEAVER_DB_MIN_IDLE_CONNECTIONS:4}",
                maxIdleConnections: "${CLOUDBEAVER_DB_MAX_IDLE_CONNECTIONS:10}",
                maxConnections: "${CLOUDBEAVER_DB_MAX_CONNECTIONS:100}",
                validationQuery: "${CLOUDBEAVER_DB_VALIDATION_QUERY:SELECT 1}"
            },
            backupEnabled: "${CLOUDBEAVER_DB_BACKUP_ENABLED:true}"
        },
        sm: {
            enableBruteForceProtection: "${CLOUDBEAVER_BRUTE_FORCE_PROTECTION_ENABLED:true}",
            expiredAuthAttemptInfoTtl: "${CLOUDBEAVER_EXPIRED_AUTH_ATTEMPT_INFO_TTL:60}",
            maxFailedLogin: "${CLOUDBEAVER_MAX_FAILED_LOGINS:10}",
            minimumLoginTimeout: "${CLOUDBEAVER_MINIMUM_LOGIN_TIMEOUT:1}",
            blockLoginPeriod: "${CLOUDBEAVER_BLOCK_PERIOD:300}",
            passwordPolicy: {
                minLength: "${CLOUDBEAVER_POLICY_MIN_LENGTH:8}",
                requireMixedCase: "${CLOUDBEAVER_POLICY_REQUIRE_MIXED_CASE:true}",
                minNumberCount: "${CLOUDBEAVER_POLICY_MIN_NUMBER_COUNT:1}",
                minSymbolCount: "${CLOUDBEAVER_POLICY_MIN_SYMBOL_COUNT:0}"
            }
        }
    },
    qm: {
        driver: "${CLOUDBEAVER_QM_DB_DRIVER:h2_embedded_v2}",
        url: "${CLOUDBEAVER_QM_DB_URL:jdbc:h2:${workspace}/.metadata/qmdb/qmdb}",
        user: "${CLOUDBEAVER_QM_DB_USER:''}",
        password: "${CLOUDBEAVER_QM_DB_PASSWORD:''}",
        schema: "${CLOUDBEAVER_QM_DB_SCHEMA:''}",
        pool: {
            minIdleConnections: "${CLOUDBEAVER_QM_DB_MIN_IDLE_CONNECTIONS:4}",
            maxIdleConnections: "${CLOUDBEAVER_QM_DB_MAX_IDLE_CONNECTIONS:10}",
            maxConnections: "${CLOUDBEAVER_QM_DB_MAX_CONNECTIONS:100}",
            validationQuery: "${CLOUDBEAVER_QM_DB_VALIDATION_QUERY:SELECT 1}"
        },
        backupEnabled: "${CLOUDBEAVER_QM_DB_BACKUP_ENABLED:true}"
    },
    app: {
        anonymousAccessEnabled: "${CLOUDBEAVER_APP_ANONYMOUS_ACCESS_ENABLED:true}",
        supportsCustomConnections: "${CLOUDBEAVER_APP_SUPPORTS_CUSTOM_CONNECTIONS:false}",
        publicCredentialsSaveEnabled: "${CLOUDBEAVER_APP_PUBLIC_CREDENTIALS_SAVE_ENABLED:true}",
        adminCredentialsSaveEnabled: "${CLOUDBEAVER_APP_ADMIN_CREDENTIALS_SAVE_ENABLED:true}",
        enableReverseProxyAuth: false,
        forwardProxy: "${CLOUDBEAVER_APP_FORWARD_PROXY:false}",
        linkExternalCredentialsWithUser: true,
        redirectOnFederatedAuth: false,
        resourceManagerEnabled: "${CLOUDBEAVER_APP_RESOURCE_MANAGER_ENABLED:false}",
        showReadOnlyConnectionInfo: "${CLOUDBEAVER_APP_READ_ONLY_CONNECTION_INFO:false}",
        grantConnectionsAccessToAnonymousTeam: "${CLOUDBEAVER_APP_GRANT_CONNECTIONS_ACCESS_TO_ANONYMOUS_TEAM:false}",
        systemVariablesResolvingEnabled: "${CLOUDBEAVER_SYSTEM_VARIABLES_RESOLVING_ENABLED:false}",
        defaultUserTeam: "${CLOUDBEAVER_APP_DEFAULT_USER_TEAM:user}",
        resourceQuotas: {
            dataExportFileSizeLimit: "${CLOUDBEAVER_RESOURCE_QUOTA_DATA_EXPORT_FILE_SIZE_LIMIT:10000000}",
            resourceManagerFileSizeLimit: "${CLOUDBEAVER_RESOURCE_QUOTA_RESOURCE_MANAGER_FILE_SIZE_LIMIT:500000}",
            sqlMaxRunningQueries: "${CLOUDBEAVER_RESOURCE_QUOTA_SQL_MAX_RUNNING_QUERIES:100}",
            sqlResultSetRowsLimit: "${CLOUDBEAVER_RESOURCE_QUOTA_SQL_RESULT_SET_ROWS_LIMIT:100000}",
            sqlResultSetMemoryLimit: "${CLOUDBEAVER_RESOURCE_QUOTA_SQL_RESULT_SET_MEMORY_LIMIT:2000000}",
            sqlTextPreviewMaxLength: "${CLOUDBEAVER_RESOURCE_QUOTA_SQL_TEXT_PREVIEW_MAX_LENGTH:4096}",
            sqlBinaryPreviewMaxLength: "${CLOUDBEAVER_RESOURCE_QUOTA_SQL_BINARY_PREVIEW_MAX_LENGTH:261120}"
        },
        defaultNavigatorSettings: {
            showOnlyEntities: true,
            hideFolders: true,
            hideVirtualModel: true
        },
        enabledFeatures: [],
        enabledAuthProviders: [
            "local"
        ],
        enabledDrivers: [],
        disabledDrivers: [
            "h2:h2_embedded",
            "h2:h2_embedded_v2",
            "clickhouse:yandex_clickhouse",
            "generic:duckdb_jdbc",
            "sqlite:sqlite_jdbc"
        ]
    }
}

Server parameters

Configure main server settings directly in the file or using environment variables (when available).

Name Environment variable Description
serverPort CLOUDBEAVER_SERVICE_PORT Port CloudBeaver server listens on.
serverHost Not available The network interface CloudBeaver server binds to as an IP address or a hostname. If null or 0.0.0.0, it binds to all available interfaces.
serverURL Not available Server address (full URL). Used to generate links and for third-party services integration.
workspaceLocation CLOUDBEAVER_WORKSPACE_LOCATION Root folder for projects.
contentRoot Not available Path to directory with static content.
driversLocation Not available Optional path for driver .jar files.
rootURI CLOUDBEAVER_ROOT_URI Web application URI prefix. / by default.
serviceURI Not available Services API URI prefix (relative to rootURI). /api/ by default. For more information on Server API, see API explorer.
productConfiguration Not available Path to product (web interface) configuration file (JSON).
sslConfigurationPath CLOUDBEAVER_SSL_CONF_PATH Path to the SSL configuration file for HTTPS connections.
develMode CLOUDBEAVER_DEVEL_MODE When set to true, extra debug information is printed in logs, and the GraphQL console is enabled on the server.
expireSessionAfterPeriod CLOUDBEAVER_EXPIRE_SESSION_AFTER_PERIOD Maximum idle time after which the user's session will be closed.
Database configuration

Configures the database for storing users, credentials, and permissions in server.database.

Name Environment variable Description
driver CLOUDBEAVER_DB_DRIVER Database driver (e.g., h2_embedded, postgres-jdbc).
url CLOUDBEAVER_DB_URL Database JDBC URL (e.g., jdbc:postgresql://localhost:5432/cb).
schema CLOUDBEAVER_DB_SCHEMA Specifies the database schema where CloudBeaver will store its data (e.g., public).
user CLOUDBEAVER_DB_USER Database user name.
password CLOUDBEAVER_DB_PASSWORD Database user password.
initialDataConfiguration CLOUDBEAVER_DB_INITIAL_DATA Path to the admin configuration and team data file (JSON) that will be loaded the first time the server runs. For more details, see Initial data configuration guide.
backupEnabled CLOUDBEAVER_DB_BACKUP_ENABLED Whether database backups are enabled.

For more information on CloudBeaver's database, see Server Database

Database connection pool configuration

Configure the connection pool used by the CloudBeaver database in server.database.pool:

Name Environment variable Description
validationQuery CLOUDBEAVER_DB_VALIDATION_QUERY Query that checks the successful connection to the database.
minIdleConnections CLOUDBEAVER_DB_MIN_IDLE_CONNECTIONS Minimum number of idle connections that should be kept in the pool.
maxIdleConnections CLOUDBEAVER_DB_MAX_IDLE_CONNECTIONS Maximum number of idle connections that should be kept in the pool.
maxConnections CLOUDBEAVER_DB_MAX_CONNECTIONS Maximum number of idle and active connections that should be kept in the pool.

Application parameters

In the section app:

Name Environment variable Description
anonymousAccessEnabled CLOUDBEAVER_APP_ANONYMOUS_ACCESS_ENABLED Allows anonymous access. Anonymous users are assigned to the anonymousUserTeam.
supportsCustomConnections CLOUDBEAVER_APP_SUPPORTS_CUSTOM_CONNECTIONS Allows users to create custom connections to any databases. Otherwise, only the CloudBeaver administrator can create/edit connections.
publicCredentialsSaveEnabled CLOUDBEAVER_APP_PUBLIC_CREDENTIALS_SAVE_ENABLED Allows saving user database credentials in a local cache.
adminCredentialsSaveEnabled CLOUDBEAVER_APP_ADMIN_CREDENTIALS_SAVE_ENABLED Allows saving global database credentials in a local cache.
forwardProxy CLOUDBEAVER_APP_FORWARD_PROXY Identifies the originating IP address and other headers of a client connecting through an HTTP proxy.
redirectOnFederatedAuth Not available If there's only one federation authentication configuration, login attempts automatically when the application opens.
resourceManagerEnabled CLOUDBEAVER_APP_RESOURCE_MANAGER_ENABLED Enables or disables the resource manager functionality in the application.
showReadOnlyConnectionInfo CLOUDBEAVER_APP_READ_ONLY_CONNECTION_INFO Shows connection information if the user has read-only permission for it.
grantConnectionsAccessToAnonymousTeam CLOUDBEAVER_APP_GRANT_CONNECTIONS_ACCESS_TO_ANONYMOUS_TEAM Provides access to predefined shared connections for the anonymous team.
systemVariablesResolvingEnabled CLOUDBEAVER_SYSTEM_VARIABLES_RESOLVING_ENABLED Enables using environment variables in the connection configuration.
defaultUserTeam CLOUDBEAVER_APP_DEFAULT_USER_TEAM The team assigned to the anonymous user, user by default.
enabledAuthProviders Not available List of allowed authorization providers. If absent, all providers are allowed. For more information on providers, see Identity providers.
enabledDrivers Not available List of allowed drivers. If the list is empty, all drivers are allowed. For more details on drivers, see Driver management
disabledDrivers Not available List of prohibited drivers. If the list is empty, all drivers are allowed.
defaultNavigatorSettings Not available Default database navigator settings. For more information, see Navigator settings.

Resource quotas

Configure the following resource quotas in the app.resourceQuotas section:

Name Environment Variable Description
dataExportFileSizeLimit ${CLOUDBEAVER_RESOURCE_QUOTA_DATA_EXPORT_FILE_SIZE_LIMIT} Maximum file size for data export operation (in bytes).
resourceManagerFileSizeLimit ${CLOUDBEAVER_RESOURCE_QUOTA_RESOURCE_MANAGER_FILE_SIZE_LIMIT} Maximum file size saved in the resource manager (in bytes).
sqlMaxRunningQueries ${CLOUDBEAVER_RESOURCE_QUOTA_SQL_MAX_RUNNING_QUERIES} Maximum number of simultaneous queries for a single user session, including data read queries (e.g., table data view).
sqlResultSetRowsLimit ${CLOUDBEAVER_RESOURCE_QUOTA_SQL_RESULT_SET_ROWS_LIMIT} Maximum number of rows to select from a table or query.
sqlResultSetMemoryLimit ${CLOUDBEAVER_RESOURCE_QUOTA_SQL_RESULT_SET_MEMORY_LIMIT} Maximum memory limit (in bytes) for SQL result sets to manage memory usage efficiently.
sqlTextPreviewMaxLength ${CLOUDBEAVER_RESOURCE_QUOTA_SQL_TEXT_PREVIEW_MAX_LENGTH} Maximum size for a text file shown in the value panel (in bytes).
sqlBinaryPreviewMaxLength ${CLOUDBEAVER_RESOURCE_QUOTA_SQL_BINARY_PREVIEW_MAX_LENGTH} Maximum size for a binary file (affects JSON in SQLite) shown in the value panel (in bytes).

For more information on Resource Manager, see our documentation.

Navigator settings

Configure the following properties in the app.defaultNavigatorSettings section:

Name Description
showSystemObjects Show system objects.
showUtilityObjects Show "utility" objects.
showOnlyEntities Only show schemas and tables.
mergeEntities Show all types of database objects in one list (e.g., tables, sequences).
hideFolders Hide folders like "Tables", "Schemas", "Columns".
hideSchemas Do not show schemas (all tables in one list).

Example configuration:

    defaultNavigatorSettings: {
        showOnlyEntities: true,
        hideFolders: true,
        hideVirtualModel: true
    }

For more information on Database Navigator, see our documentation.

Initial data

For details on configuring initial data, see the Initial data configuration guide.

Password policy

To configure password policies, refer to the Password policy guide.

Datasource configuration

For information on configuring server datasources, visit the Datasource configuration guide.

Query manager database configuration

To learn about configuring the query manager database, see the Query manager database configuration documentation.

Automatic server configuration

When you start the CloudBeaver server for the first time, an administrator interface guides you through the server setup. However, in some cases—like when running in a Kubernetes environment—you might need to configure the server automatically.

To set up the server automatically, specify the following parameters:

Name Description Example
CB_SERVER_NAME The server’s name. Test Server
CB_SERVER_URL The base URL for the server. https://cloudbeaver.domain.com:10000/
CB_ADMIN_NAME Administrator username. administrator
CB_ADMIN_PASSWORD Administrator password. S0mePazzworD

How to specify these parameters:

  • OS environment variables: Set these variables directly in your system’s environment settings.
  • Configuration file: Add them to a .cloudbeaver.auto.conf file, located in the same directory as the cloudbeaver.conf file.