Skip to content
Backstage

Backstage

Backstage is the cloud for products that move money. Push your code, and Backstage builds, tests and releases the whole product together: application, engine, admin console, storefront and database. Every change is checked before it reaches production, and every change leaves a record.

Overview

A project is a complete product, not a single container. (In the Box CLI a project is called a box, and the two words mean the same thing here.) Its five components are built, tested and released as one unit, so they never drift apart.

ComponentWhat it does
ApplicationThe customer facing app
EnginePayments and ledger logic
Admin consoleThe console your staff use
StorefrontWhere customers buy
DatabaseMigrated with each release

You run your box from the Box CLI on your machine, and you release and watch it from the Backstage app at backstage.boxspace.io.

Who it is for

  • Financial institutions running digital products for their customers or merchant networks, under their own brand and domains.
  • Fintech teams building payments, wallets and other money products who want reliable releases without assembling the infrastructure.
  • Merchants and developers who want a managed path from code to production.

How a release moves

Code goes into a sandbox first. When you are happy, you promote it to production. Promotion runs release checks, and the whole thing is recorded.

Text
push  ->  build  ->  test  ->  live in sandbox  ->  checks  ->  promote  ->  live in production

Quickstart

This walkthrough takes you from nothing to a running box on your machine. You need a license key from Box Space.

Install the CLI

Shell
brew install withpotter/tap/box

The CLI runs on the Node.js 20 or newer you already have. Other platforms are covered in the Box CLI documentation.

Create your project

Shell
box create acme-bank

box create scaffolds a new project with a box.json manifest and a .gitignore, then prints the next steps. Move into the folder before the next command.

Activate your license

Shell
box auth --org acme-bank --key <license-key>
box status

box auth checks your license and prepares the software included in your plan. box status shows whether the box is activated and what your license entitles it to.

Install the engine and start it

Shell
box install
box start

box install pulls the engine packages your license includes. box start runs the engine and the console on your machine.

Go live

Shell
box deploy
box deploy --register-domains

box deploy generates the files you need to run the box anywhere: a Dockerfile, a docker-compose file, an example environment file, a CI/CD workflow and Railway configuration. With --register-domains it registers your public domains with Box Space and writes a dns.txt file with the DNS records to add.

Ask your editor to do it

Prompt
Create a Box called acme-bank, activate it with my license key, install the engine and start it locally. Do not register any domains without my approval.

Deployments

A deployment starts when you push to a branch, or when you ask for one. Every deployment is explicit about where it is and why.

States

StateWhat it means
buildPackages are installing and the five components are compiling.
testYour tests are running against the release.
liveTraffic has switched to the new release.
failedA stage broke. The deployment names the stage and links its log.
stuckA stage is running longer than it should. It is flagged, not left spinning.

Each stage is timed, and each one links to its logs.

NoteA failed deployment never takes traffic. Your last good release keeps serving until the new one passes every stage.

Rolling back

If a release misbehaves, go back one step from the Backstage app. The previous release is kept warm, so there is nothing to rebuild.

Preview environments

Open a pull request and Backstage builds a preview environment for it, so changes are reviewed running, not just read. Each preview has its own address.

Previews are removed when the pull request merges or closes. They use sandbox data, never production data.

Environments and promotion

Sandbox is for building and trying things. Production is where real money moves. They are separate in every way that matters: addresses, secrets, data and access.

Promotion is the controlled step between them. When you promote, Backstage runs the release checks, moves the same build that passed in sandbox, and records who did it and when.

NotePromotion moves a release that already exists. It never rebuilds from source, so what you tested is exactly what ships.

Release checks

Before anything reaches production, Backstage checks three things.

CheckWhat it looks at
Access rulesWho is allowed to release, and whether this person is one of them.
PackagesWhich packages changed since the last production release.
SecretsWhether any secret is exposed in the code that is about to ship.

A blocked release stays in sandbox, and production is never touched. Move the secret into your project secrets, run the check again, and promote.

Roles and access

Roles are set per project and applied to every session.

CapabilityEngineerSupportOperator
Deploy to sandboxyesnono
Promote to productionwith approvalnono
Read logs and metricsyesyesno
Browse data (read only)yesyesno
Use the admin consoleyesyesyes
View the audit trailnonoyes
Read or change secretsyesnono

Session policy

Institutions sign in with their own identity. Sessions end when idle, and access follows the role you set for the project.

Audit trail

Releases, promotions, rollbacks and role changes are recorded, with who did what and when. The trail is exportable.

Logs, metrics and alerts

Application logs are searchable in either environment, and you can follow response time and usage for each project.

Alerts

Set an alert on latency or errors, and Backstage tells you when a line is crossed, for example when the slowest five percent of requests take longer than 800 milliseconds for five minutes.

You can also browse your data read only, and see each project's usage and projected monthly cost.

Where to go next

This page is the short version. The full Box documentation covers the CLI, the engine, plans and tiers, and troubleshooting.

Read the full Box documentationThe Box CLI, the engine, plans and tiers, recipes and troubleshooting.
Was this page helpful?