Cloud UI Setup and Deployment Guide
This guide walks you through creating a new Cloud UI project — either the Variant Configuration UI (VC UI) or the Sales Document UI (SalesDoc UI) — using the create-cloud-ui scaffolding tool, and deploying it to SAP Business Technology Platform (BTP) via the Cloud Foundry (CF) CLI.
Both applications follow the same setup and deployment process. Differences between the two are clearly marked throughout.
Prerequisites:
- Node.js 18 or higher installed
pnpmpackage manager installed (npm install -g pnpm)- Access to the enosix npm registry (credentials required)
- A Cloud Foundry org and space on SAP BTP
- The CF CLI installed (
brew install cloudfoundry/tap/cf-cli@8on macOS, or see CF CLI docs)
Part 1: Create the Project
Step 1: Log in to the enosix private npm registry
Both templates depend on private packages hosted at registry.npm.enosix.io. You must log in before the scaffolding tool can install dependencies.
Need credentials? Contact your enosix representative to obtain a username and password for the registry before continuing.
Run the following command:
pnpm login --registry=https://registry.npm.enosix.io
You will be prompted for:
Username: YOUR-REGISTRY-USERNAME
Password: YOUR-REGISTRY-PASSWORD
Email: YOUR-EMAIL-ADDRESS
Enter the credentials provided by your enosix representative. When successful, you will see a confirmation message. You only need to do this once per machine.
Step 2: Run the scaffolding tool
Open a terminal and run:
npx @enosix/create-cloud-ui
Step 3: Answer the prompts
The tool will ask you a series of questions. Answer each one as described below.
Project name
Enter a short, lowercase name with no spaces. Use hyphens to separate words.
Project name: YOUR-APP-NAME
VC UI example:
my-vc-appSalesDoc UI example:my-salesdoc-app
Project directory
Press Enter to accept the default (.), which creates the project inside a new folder in your current directory.
Project directory: .
Template
This is where VC UI and SalesDoc UI diverge. Use the arrow keys to select the application you are setting up, then press Enter.
Select a template:
VC-UI Application
SalesDoc UI Application
- Choose VC-UI Application for Variant Configuration
- Choose SalesDoc UI Application for Sales Document
Project display name
Enter a human-readable name for your application. This appears in the UI.
Project display name: YOUR-DISPLAY-NAME
VC UI example:
My Variant ConfiguratorSalesDoc UI example:My Sales Document App
Project description
Optionally enter a description, or press Enter to accept the default.
Project description: A enosix cloud-ui application
Host URL
This is the domain (without https://) where your app will be hosted after deployment. You may not know this yet — you can update it later. For now, enter a placeholder or your known CF route.
Host URL: YOUR-APP-HOST
Example:
my-app.cfapps.us10.hana.ondemand.comIf you are unsure, enter
localhost:3000for now and updateVITE_HOSTinpublic/config.jsbefore you build and deploy.
API host URL
This is the URL of your Link API Proxy service on SAP BTP.
API host URL: YOUR-API-HOST-URL
Example:
https://my-link-service.cfapps.us10.hana.ondemand.com/my-route
Defaults file URL
This is the URL of a JSON file used by the test harness to pre-populate configuration. Press Enter to accept the default for now.
Defaults file URL: http://localhost:3000/initial-content-example.json
npm registry login
When asked whether to log in to the enosix npm registry, type Y and press Enter. Since you already logged in during Step 1, the tool will detect your existing session and skip re-entry.
Log in to enosix npm registry? Yes
Step 4: Wait for installation to complete
The tool copies the template files and runs pnpm install automatically. This may take a minute. When finished you will see:
✓ Project created successfully!
Next steps:
cd YOUR-APP-NAME
pnpm run dev
Step 5: Enter the project directory
cd YOUR-APP-NAME
All remaining commands in this guide are run from inside this directory.
Part 2: Configure the Project
Step 6: Open the runtime config file
Open public/config.js in a text editor. This file controls the runtime values used by Cloud UI templates:
window.config = window.config || {};
window.config.VITE_HOST = 'YOUR-APP-HOST';
window.config.VITE_LOG_LEVEL = 'debug';
window.config.VITE_API_HOST = 'YOUR-API-HOST-URL';
window.config.VITE_DEFAULTS_ENDPOINT = 'http://localhost:3000/initial-content-example.json';
Step 7: Review and update runtime config values
Update the values in public/config.js:
// The host where your app is served. Used for CORS.
// For local development, keep this as localhost:3000
window.config.VITE_HOST = 'YOUR-APP-HOST';
// Log level: debug | info | warn | error
window.config.VITE_LOG_LEVEL = 'debug';
// URL to your Link API Proxy
window.config.VITE_API_HOST = 'YOUR-API-HOST-URL';
// URL to the defaults JSON used by the test harness
window.config.VITE_DEFAULTS_ENDPOINT = 'http://localhost:3000/initial-content-example.json';
public/config.jsis ignored when the app is deployed to BTP in favor of user-provided variables.
Part 3: Run Locally (Optional)
Step 8: Start the development server
pnpm run dev
Open your browser at http://localhost:3000 to verify the app loads. You should see the test harness for your chosen application. You can stop the server with Ctrl+C when you are done.
Part 4: Deploy to Cloud Foundry
Step 9: Log in to Cloud Foundry with SSO
cf login --sso
The CLI will print a URL. Open it in your browser, log in with your SAP BTP credentials, and copy the one-time passcode shown. Paste it back into the terminal prompt and press Enter.
API endpoint: https://api.cf.YOUR-CF-REGION.hana.ondemand.com
Temporary Authentication Code ( Get one at https://login.cf.YOUR-CF-REGION.hana.ondemand.com/passcode ):
If you do not know your CF API endpoint, ask your BTP administrator. It will look like
https://api.cf.us10.hana.ondemand.com.
Step 10: Select your org and space
After authenticating, the CLI will prompt you to select an org and space if you have access to more than one. Enter the number corresponding to the correct org and space for your deployment.
Select an org:
1. YOUR-ORG-NAME
Select a space:
1. YOUR-SPACE-NAME
Step 11: Build the application
pnpm run build
This compiles the TypeScript and bundles the application. Wait for it to complete with no errors before continuing.
VC UI: Output is written to
dist/SalesDoc UI: Output is written todist/(with the app insidedist/public/and nginx configuration files at the root ofdist/)
Step 12: Push the application to Cloud Foundry
cf push YOUR-APP-NAME -f manifest.yml --var name=YOUR-APP-NAME --var host=YOUR-APP-HOST -p dist
Replace the placeholders:
| Placeholder | Description | Example |
|---|---|---|
YOUR-APP-NAME | The name for your CF application | my-vc-app or my-salesdoc-app |
YOUR-APP-HOST | The full hostname where the app will be accessible | my-app.cfapps.us10.hana.ondemand.com |
Tip: After the first push, CF assigns a route automatically. You can find it by running
cf app YOUR-APP-NAMEand looking at theroutes:line. If the assigned route differs from what you used forYOUR-APP-HOST, re-push with the correct host value.
Step 13: Update config values and redeploy when needed
If your API host, defaults endpoint, or log level changes after your first deployment, update public/config.js and redeploy:
pnpm run build
cf push YOUR-APP-NAME -f manifest.yml --var name=YOUR-APP-NAME --var host=YOUR-APP-HOST -p dist
| Placeholder | Description | Example |
|---|---|---|
YOUR-API-HOST-URL | URL to your Link API Proxy | https://my-link.cfapps.us10.hana.ondemand.com/route |
YOUR-DEFAULTS-FILE-URL | URL to the defaults JSON file | https://my-app.cfapps.us10.hana.ondemand.com/initial-content-example.json |
Before rebuilding, update these values in
public/config.js:
window.config.VITE_API_HOSTwindow.config.VITE_DEFAULTS_ENDPOINTwindow.config.VITE_LOG_LEVEL
Step 14: Restart the application
cf restart YOUR-APP-NAME
Step 15: Verify the deployment
cf app YOUR-APP-NAME
Look for running in the state column. The routes: line shows the URL where your app is accessible.
Open the route URL in your browser to confirm the app is live.
Summary of Placeholders
| Placeholder | What to put here |
|---|---|
YOUR-APP-NAME | Short lowercase name for your app, e.g. my-vc-app or my-salesdoc-app |
YOUR-DISPLAY-NAME | Human-readable title shown in the UI, e.g. My Variant Configurator or My Sales Document App |
YOUR-APP-HOST | The CF hostname for your app, e.g. my-app.cfapps.us10.hana.ondemand.com |
YOUR-API-HOST-URL | Full URL to your Link API Proxy, e.g. https://my-link.cfapps.us10.hana.ondemand.com/route |
YOUR-DEFAULTS-FILE-URL | URL to the initial content JSON, e.g. https://my-app.cfapps.us10.hana.ondemand.com/initial-content-example.json |
YOUR-REGISTRY-USERNAME | Your enosix npm registry username |
YOUR-REGISTRY-PASSWORD | Your enosix npm registry password |
YOUR-EMAIL-ADDRESS | Your email address for registry login |
YOUR-CF-REGION | Your BTP CF region, e.g. us10 or eu10 |
YOUR-ORG-NAME | Your BTP org name |
YOUR-SPACE-NAME | Your BTP CF space name |
Troubleshooting
pnpm install fails with a registry error
Your enosix npm registry credentials may be missing or expired. Run pnpm login --registry=https://registry.npm.enosix.io again with valid credentials, then retry.
cf push fails with "No space targeted"
Run cf login --sso again and make sure you select an org and space.
App starts but shows a blank page or CORS error
The VITE_HOST value used during cf push (the --var host= argument) must exactly match the domain your browser uses to access the app. Re-push with the correct host value.
App crashes after cf restart
Run cf logs YOUR-APP-NAME --recent to see the error output.