Deploy and release a Cube

This guide takes a Cube from a directory on your laptop to an installed Cube in a tenant's Analytics Studio. You validate it locally, deploy it with the revenexx CLI or from a repository connected in Cockpit, follow its release round through review, and install the approved version. It is for developers who build Cubes. You need the CLI, your revenexx identity, a tenant slug, and a machine-to-machine X-Revenexx-Api-Key from Cockpit that covers Cubes (cubes.write, or a development key with full access *).

Quick start

revenexx create cube holidays --vendor acme -y
cd holidays
npm test
revenexx deploy cube

The rest of this guide explains each step and what happens after the upload.

1. Start a Cube

revenexx create cube <name> downloads the Cube template and fills in the name, vendor and titles:

revenexx create cube holidays --vendor acme --title "Public holidays" --title-de "Feiertage"

The options you are likely to use are --vendor (your vendor slug), --title and --title-de (the English and German display titles, labels in a Cube carry both), --dir (the parent directory) and -y (no prompts). See Scaffolding for how the create commands work.

A Cube is identified as {vendor}/{name}, for example acme/holidays. The name must not be the name of an App. These files sit at the root of the directory:

• cube.json — required. Identity, version, and the Apps or Cubes it requires.
• analytics.json — the datasets the Cube brings, left out when it has no data of its own.
• metrics.json, reports.json, dashboards.json — what the Cube adds to the studio.
• billing.json — free or paid, with the same fields as an App.
• data/*.csv — data for file datasets.

Inside these files, a bare key such as holidays_count is the Cube's own. A dotted key such as orders.revenue_net refers to an App or another Cube, and every package you refer to that way must be listed in requires. Refer to an App's metric by its key rather than copying its definition. A Cube does not ship SQL: metrics are aggregations over a declared dataset or formulas over other metrics.

2. Validate locally

The template ships the same checks the review runs on a release, and they run offline:

npm test

Run them before every deploy. revenexx deploy cube also runs the Cube's own node scripts/cube.mjs validate before it uploads anything, when the directory has that script. --skip-validate turns this off, which is rarely what you want.

For a new release, bump version in cube.json.

3. Sign in

Sign in once with your key and tenant. Keep REVENEXX_TENANT exported, or pass --tenant on each command:

export REVENEXX_API_KEY="rvxk_..."
export REVENEXX_TENANT="<TENANT_SLUG>"
revenexx login --token "$REVENEXX_API_KEY" --tenant "$REVENEXX_TENANT"

See Authentication for how the tenant resolves.

4. Deploy

There are two ways to get a Cube onto the platform. Pick one per Cube.

From the command line

Run deploy cube from the Cube directory, the one with cube.json:

revenexx deploy cube

The command validates the Cube, finds it by name or creates it, packs the directory and uploads it, then waits for the build. The build reads cube.json, the other Cube files and the CSV data, and submits them as a release of that version for review. Then the command reads the release round, the review of this upload, as deploy app does (see Follow the release round).

The flags you will reach for:

• --cube-id <id> — deploy to an existing Cube instead of finding one by name.
• --deployment-id <id> — pick up an existing deployment instead of uploading a new one. The command waits for its build and reports the outcome. A deploy that times out prints this resume command.
• --timeout <seconds> — how long to wait for the build. Default 600.
• --release-wait <seconds> — how long to wait after the build for the round to be approved or rejected.
• --json — print the result as a JSON document, including the list of problems when the build fails.

When the build fails, the command prints one line per problem, naming the file, the path inside it and the message, and exits with a non-zero code. Fix those and deploy again.

From a connected repository

In Cockpit, open Analytics Studio → My Cubes and connect a repository. Pick the branch and the root directory, the folder that holds cube.json relative to the repository root, then choose Create and deploy. The first deployment starts right away. After that, every push to the branch deploys the Cube, and Redeploy on the Cube's page builds it again.

To deploy a connected Cube from the command line, use --from-git. It deploys the Cube's production branch, or the ref you name:

revenexx deploy cube --from-git
revenexx deploy cube --from-git --ref v1.2.0 --ref-type tag

--ref-type is branch (the default), tag or commit. A Cube that is not connected to a repository fails with a message to connect it in Cockpit.

A deploy from a repository, by push or with --from-git, always runs in deploy mode. To preview a version first, upload it with preview cube.

5. Follow the release round

Where the platform reviews releases, a Cube version reaches tenants only once its release round is approved. A version can have several rounds, numbered rc 1, 2 and so on. After the build, deploy cube prints a release <version> rc <n> (deploy): <state> line each time the round changes state, and waits for a decision.

• Approved. The version is released and appears in the Cube marketplace. File datasets are loaded at approval.
• Rejected. The command fails and prints the reason. Fix it, bump the version if needed, and deploy again.
• Still in review. The build is uploaded but not released. The command says so and prints the command to resume later. This is a wait, not a failure, so in CI read the JSON result rather than the exit code.

Check where a round stands at any time:

revenexx release status --cube-id <CUBE_ID>

Run from the Cube directory, the command finds the Cube by the name in cube.json, and --cube-id is not needed. It lists each round with its version, round number, mode, state, gate results, decision due date and rejection reason. The Cube's page under My Cubes in Cockpit shows the same round.

Deploy or preview

deploy cube submits a round in deploy mode: once a reviewer approves it, the version is released.

preview cube runs the same flow in preview mode:

revenexx preview cube

A preview version is a release candidate. It is available on the candidate channel, to tenants that opted in to release candidates, while every other tenant keeps the last approved version. It goes out to everyone only after two things: your go and the reviewer's approval. Give your go once you have checked the candidate:

revenexx preview accept --cube-id <CUBE_ID> --release-version <VERSION> --rc <N>

• --release-version defaults to the version in cube.json. Without one, it takes the newest preview candidate.
• --rc defaults to the version's current candidate round.
• --cube-id skips the lookup by name; run from the Cube directory, you can leave it out.

Your go does not replace the reviewer's approval. The command prints the round's state after accepting, and if a reviewer still has to approve, it says so. In Cockpit, a preview that waits for your go shows a link to accept it on the Cube's page.

6. Install the Cube

An approved Cube is listed in Analytics Studio → Cube marketplace, which shows only reviewed versions. Open the Cube, check what it adds and what it requires, fill in its settings if it has any, and choose Install.

The install is refused when an App or Cube the Cube requires is missing or installed in a version that does not fit. The Cube's page names what to install first. Once installed, the Cube appears under Installed Cubes, and its reports appear in the studio's sidebar under Cubes. When a newer version is approved, Installed Cubes offers the update.

Troubleshooting

• Validation fails before the upload. scripts/cube.mjs validate found a problem. The output names the file and the path. Run npm test and fix it there.
• The build fails with a list of problems. The review's checks rejected the release. Each line names a file, a path inside it and the message. A common one: a dotted key whose package is missing from requires.
• "is not a Cube directory". The command found no cube.json with a name. Run it from the Cube's root, or start one with revenexx create cube.
• "is not connected to a repository". You used --from-git on a Cube without a connected repository. Connect one in My Cubes, or deploy the directory without --from-git.
• The deploy ends with the release still in review. Nothing is wrong. Check with revenexx release status --cube-id <CUBE_ID>. The version reaches the marketplace once a reviewer approves it.
• "this gateway does not offer release rounds yet". The platform you deploy to does not review releases. release status and preview accept have nothing to show there.
• The Cube is missing from the marketplace. Its release has not been approved yet, or it was withdrawn.

Where to go next

• Analytics Studio — what the studio offers and how data gets into it.
• analytics.json — the dataset contract a Cube's analytics.json follows.
• Deploy and verify an App — the same release round, as it applies to Apps and Themes.
• CLI — every command in depth.