We're thrilled to share that Cube.js is releasing an official Docker image and amplifying its support for the microservices architecture.

Read more to explore the positive effects of this change on the scalability of Cube.js applications, the migration path to Docker, and the plans for the Express support.

Motivation for the Change

Historically, Cube.js has been being embedded in Express applications running on Node.js. It makes a lot of sense since Cube.js is written mostly in JavaScript and provides API endpoints that work great alongside other Express routes.

However, while the amount of Cube.js production deployments continues to grow, we kept exploring how developers approach scalability and infrastructure management issues. We learned that Cube.js should be scaled differently than Express applications and deployed as fully isolated microservices that don't share any resources with other parts of the application.

Frankly, we never designed Cube.js to share the event loop with other parts of Express applications running on Node.js. As Cube.js gets more features, it becomes even heavier on the computational side. We've observed intermittent lags appearing under load in a lot of embedded Cube.js deployments which was never the case for the microservice deployments. And while every embedded use case is different, it narrows our ability to track down such issues and work around them on a case-by-case basis.

Although small to medium deployments are able to work as a part of Express applications, this configuration adds unnecessary complexity to the infrastructure, interferes with the best practices of DevOps, and often leads to suboptimal performance for pre-aggregations which are the ultimate feature of Cube.js allowing to serve complex analytical queries with low latency.


We decided that embedding into Express will no longer be a recommended way to run and deploy Cube.js. As a more reliable and scalable alternative, we encourage developers to use Cube.js as a standalone microservice. Serverless is also a good way to deploy Cube.js applications, and we have no plans to discontinue using it. We will keep the support for Express for the next six months, until June 2021, and provide support with the transition to microservices.

Cube.js in the Microservices Architecture

We have released several features to enhance the support for using Cube.js in the microservices architecture. Since version 0.23, you're welcome to use these feature, and full details are available in the changelog and our public roadmap.

Deployment. Cube.js now has an official Docker image based on Alpine Linux.

Running Cube.js in containers makes it easier to deploy and manage installations in on-premise and cloud-based environments, such as Kubernetes, Amazon ECS, Google Compute Engine, or Cube Cloud. It also provides a straightforward way to run a dedicated refresh worker instance which is the best practice for keeping pre-aggregations up-to-date in the background. See the Deployment Guide and the Production Checklist in our documentation to learn more.

Even more importantly, official Docker images make it easier to maintain Cube.js deployments with minimal engineering effort needed to update to the latest version of Cube.js.

Development. Running npx cubejs-cli create new-application will create a Cube.js application using the new docker template which provides several new features:

  • the cube.js file for configuration options which is more concise than the former index.js file (see the Configuration Overview in our documentation to learn more)
// Cube.js configuration options: https://cube.dev/docs/config
module.exports = {
// Cube.js options go here, none by default
// Options set via environment variables take precedence
  • the docker-compose.yml file for running Cube.js installations as microservices with Docker (see the Getting Started with Docker in our documentation to learn more)
image: cubejs/cube:latest
- 4000:4000 # Cube.js API
- 3000:3000 # Developer Playground
env_file: .env
- ./dashboard-app:/cube/conf/dashboard-app
- ./cube.js:/cube/conf/cube.js
- ./schema:/cube/conf/schema

While you still can run Cube.js via npm run dev thanks to the existing package.json file, now you can also run Cube.js in Docker without npm or Node.js being present on your machine. It makes Cube.js more appealing to developers and engineering teams using different languages and ecosystems.

What's Next

We encourage you to plan the migration and move existing Cube.js applications to the microservices architecture and Docker. Use this migration guide to update the source code and the Deployment Guide for the advice on popular deployment environments.

If you have any questions or need assistance with the migration, please reach out to the Cube.js team and the community on Slack or file an issue on GitHub.