Administration

TODO

Cube is configured via environment variables and configuration options in a configuration file. Usually, both would be used to configure a Cube deployment in production.

Environment variables

Environment variables are mostly used for configuration that is defined statically and is not supposed to change while a Cube deployment is running.

For example, CUBEJS_DATASOURCES defines a list of data sources to connect to; changing that list would require the deployment to restart.

See the environment variables reference for all supported options.

See this recipe if you’d like to reference environment variables in code.

Cube Core

You can set environment variables in any way supported by Docker, e.g., a .env file or the environment option in the docker-compose.yml file.

Cube Cloud

You can set environment variables in Settings → Configuration:

Configuration options

Configuration options are mostly used for configuration that is defined programmatically and applied dynamically while a Cube deployment is running.

For example, query_rewrite provides a way to inspect, modify, or restrict every query that is being processed by Cube.

Configuration options take precedence over environment variables.

See the configuration options reference for all supported options.

cube.py and cube.js files

Configuration options can be defined either using Python, in a cube.py file, or using JavaScript, in a cube.js file in the root folder of a Cube project.

Python

from cube import config

# Base path for the REST (JSON) API
config.base_path = '/cube-api'

# Inspect, modify, or restrict every query
@config('query_rewrite')
def query_rewrite(query: dict, ctx: dict) -> dict:
  if 'order_id' in ctx['securityContext']:
    query['filters'].append({
      'member': 'orders_view.id',
      'operator': 'equals',
      'values': [ctx['securityContext']['order_id']]
    })
  return query

Both ways are equivalent; when in doubt, use Python.

Here is a minimal correct cube.py file. Note that the config object must be imported:

from cube import config

# Configuration goes here...

Here is a minimal correct cube.js file. Note that the module.exports object must be defined:

module.exports = {
  // Configuration goes here...
}

You can read more about Python and JavaScript support in the dynamic data modeling section of the documentation.

Cube Core

When using Docker, ensure that the configuration file and your data model folder are mounted to /cube/conf within the Docker container.

Cube Cloud

You can edit the configuration file by going into Development Mode and navigating to Data Model or Visual Modeler pages.

Runtimes and dependencies

Cube uses Python and Node.js as runtime environments for the code of configuration and dynamic data models. You can look current versions up on GitHub: Python, Node.js.

It’s recommended to use requirements.txt and package.json files to specify dependencies for your Python and JavaScript code, respectively.

Cube Core

If you have specified Python packages in the requirements.txt file, make sure to install them by running pip install -r requirements.txt inside the Docker container.

If you have specified npm packages in the package.json file, make sure to install them by running npm install inside the Docker container. Alternatively, you can run npm install on your local machine and mount the node_modules folder under /cube/conf in the Docker container; however, if your dependencies contain native extensions, they might not work when provided this way.

To automate the installation of dependencies, build and use a custom Docker image.

Cube Cloud

Cube Cloud automatically installs dependencies from requirements.txt and package.json files.

Development mode

Development mode is an authentication bypass. Cube is in development mode when CUBEJS_DEV_MODE=true, and also whenever NODE_ENV is not production. When Cube is started through the cubejs CLI — which is what the official Docker images run — setting CUBEJS_DEV_MODE=true additionally forces NODE_ENV=development, which switches off JWT verification on the REST (JSON) and GraphQL APIs: they then accept requests with no token at all.

Development mode also mounts Playground and its supporting endpoints with no authentication whatsoever. Anyone who can reach the instance is handed a ready-to-use API token, and can mint further ones carrying any security context signed with your API secret — and so query every data API as any user, bypassing member-level access control and row-level security. The same endpoints read your data model files and the table schema of every connected data source, and overwrite your data model and your .env. With CUBEJS_DEV_MODE=true and no CUBEJS_SQL_PASSWORD set, the SQL API accepts any credentials as well, allowing arbitrary SQL against connected data sources.

This is intentional. Development mode is designed to run on a developer’s local machine for ease of use and debugging. Never run it where anyone else can reach it, never expose it to the internet, and never use it in production. Using development mode in the Cube cloud platform is highly discouraged — it bypasses the platform’s security model.

To keep it off: cubejs server and the official Docker images already set NODE_ENV=production, so leaving CUBEJS_DEV_MODE unset — its default — is enough there. If you embed @cubejs-backend/server-core directly rather than starting Cube through the cubejs CLI, set NODE_ENV=production yourself, since an unset NODE_ENV puts the instance in development mode whatever the flag says.

Cube can be run in an insecure, development mode by setting the CUBEJS_DEV_MODE environment variable to true. Putting Cube in development mode does the following:

• Disables member-level access control when listing the data model.
• Enables Cube Store in single instance mode.
• Enables background refresh for in-memory cache and scheduled pre-aggregations.
• Allows another log level to be set (trace).
• Enables Playground on http://localhost:4000.
• Uses memory instead of cubestore as the default cache/queue engine.
• Logs incorrect/invalid configuration for externalRefresh /waitForRenew instead of throwing errors.