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.
| Component | What it does |
|---|---|
| Application | The customer facing app |
| Engine | Payments and ledger logic |
| Admin console | The console your staff use |
| Storefront | Where customers buy |
| Database | Migrated 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.
push -> build -> test -> live in sandbox -> checks -> promote -> live in productionQuickstart
This walkthrough takes you from nothing to a running box on your machine. You need a license key from Box Space.
Install the CLI
brew install withpotter/tap/boxThe CLI runs on the Node.js 20 or newer you already have. Other platforms are covered in the Box CLI documentation.
Create your project
box create acme-bankbox 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
box auth --org acme-bank --key <license-key>
box statusbox 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
box install
box startbox install pulls the engine packages your license includes. box start runs the engine and the console on your machine.
Go live
box deploy
box deploy --register-domainsbox 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
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
| State | What it means |
|---|---|
build | Packages are installing and the five components are compiling. |
test | Your tests are running against the release. |
live | Traffic has switched to the new release. |
failed | A stage broke. The deployment names the stage and links its log. |
stuck | A 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.
| Check | What it looks at |
|---|---|
| Access rules | Who is allowed to release, and whether this person is one of them. |
| Packages | Which packages changed since the last production release. |
| Secrets | Whether 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.
| Capability | Engineer | Support | Operator |
|---|---|---|---|
| Deploy to sandbox | yes | no | no |
| Promote to production | with approval | no | no |
| Read logs and metrics | yes | yes | no |
| Browse data (read only) | yes | yes | no |
| Use the admin console | yes | yes | yes |
| View the audit trail | no | no | yes |
| Read or change secrets | yes | no | no |
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.↗