Quick Start

• Download bp.zip

If the Web Browser alerts that the bp.zip file is suspicious, allow the file

• Extract bp.zip by double-clicking on the file

Before you can run 'bp' for the first time, 'Right-click' on the extracted 'bp' file and select Open from the context menu and Accept any security warning that appears. A terminal window will open and execute the file. Close the terminal window.

• Open Terminal and from the directory bp has been extracted to, run the following command to move the file to your executable path:

  sudo mv bp /usr/local/bin/
  

• To verify that bp is successfully installed, run:

  bp --version
  1.0.0
  

• Download bp.zip

• Extract contents to folder

  expand-archive bp.zip c:\backplane
  

• Add bp.exe file system environment path

  $newPath = "C:\backplane"
  $currentPath = [System.Environment]::GetEnvironmentVariable("Path", "Machine")
  [System.Environment]::SetEnvironmentVariable("Path", "$currentPath;$newPath", "Machine")
  

• Verify installation - To check if bp.exe is successfully installed, run:

  bp --version
  1.0.0
  

• Download bp.zip

• Extract executable from ZIP file.

  sudo apt install unzip
  unzip bp.zip
  

• Move the file to your executable path

  sudo mv ./bp /usr/local/bin/bp
  

• Verify installation to check that bp is successfully installed, run:

  bp --version
  1.0.0
  

Clone Repo

• Open a Terminal window. If using Windows, right-click and Run as Administrator.

git clone https://github.com/backplane-cloud/backplane-api.git
cd backplane-api

Create Local Environment Variable file (.env)

• Create .env file. Windows: new-item .env Linux/Mac: touch .env and copy the below template into it.

NODE_ENV=development
PORT=8000

JWT_SECRET=<provide-key>
// Make up your own secret, this is used as the salt to CryptB for password Hashing. e.g. MyS3cureP&!00word\*

MONGO_URI=<connection-string>

MAILSENDER_USERNAME=<your-username>
MAILSENDER_PASSWORD=<provide-key>

LOGTAIL_KEY=<provide-key>
LOG_LEVEL=debug

Setup Database

MongoDB

• See Setting up MongoDB for instructions. The connection string will need to updated into the .env file.

Setup Middleware

MailerSend

• MailerSend is used as an SMTP mailrelay, so that User Registration e-mails can be sent as well as approval request e-mails. Create an account here: MailerSend

LogTail

• /utils/logger.js is used as Middleware for logging purposes. It leverages LogTail, now known as Better Stack is used as a Log Repository. It’s free up to 1GB a month with 3-day retention. Create an account here: LogTail.

Run Server

• Run the npm i command to install all dependencies
• Run npm run server to launch server.

The Backplane API Server is now up and running and you are ready to Start Using Backplane

Install Node

• Install Node.JS on your system and then from a terminal window, initialise an NPM project.

  mkdir backplane-api
  cd backplane-api
  npm init -y
  npm i express dotenv @backplane-software/backplane-api
  

Create Local Environment Variable file (.env)

• Create .env file. Windows: new-item .env Linux/Mac: touch .env and copy the below template into it.

NODE_ENV=development
PORT=8000

JWT_SECRET=<provide-key>
// Make up your own secret, this is used as the salt to CryptB for password Hashing. e.g. MyS3cureP&!00word\*

MONGO_URI=<connection-string>

MAILSENDER_USERNAME=<your-username>
MAILSENDER_PASSWORD=<provide-key>

LOGTAIL_KEY=<provide-key>
LOG_LEVEL=debug

Setup Database

MongoDB

• See Setting up MongoDB for instructions. The connection string will need to updated into the .env file.

Setup Middleware

MailerSend

• MailerSend is used as an SMTP mailrelay, so that User Registration e-mails can be sent as well as approval request e-mails. Create an account here: MailerSend

LogTail

• /utils/logger.js is used as Middleware for logging purposes. It leverages LogTail, now known as Better Stack is used as a Log Repository. It’s free up to 1GB a month with 3-day retention. Create an account here: LogTail.

Create Index.js

• Create index.js file and copy the below into it.

import express from "express";
import dotenv from "dotenv";
import backplane from "@backplane-software/backplane-api";

// Load Environment Configuration
dotenv.config();

// Create Express Instance
const app = express();

// Initialise Backplane Server with Instance
backplane(app);

// Start REST API Server
const port = process.env.PORT || 5001;
app.listen(port, () =>
  console.log(`Backplane REST API Server started on port ${port}`)
);

Update Package.json

• Add "type": "module" so the script can load ES modules.
• Add "server": "node index.js" to the scripts section.

Run Server

• Run npm run server to launch server.

Use curl http://localhost:8000 to confirm server is running.

The Backplane API Server is now up and running and you are ready to Start Using Backplane

Clone Repo

• Open a Terminal window and run:

  git clone https://github.com/backplane-cloud/backplane-api.git
  cd backplane-api
  npm i
  

Docker Commands

• Ensure Docker is installed and run:

  docker build -t backplanesoftware/backplaneapi:0.26.1 .
  
  docker network create my-network
  
  docker run --network my-network --name api -p 8000:8000 backplanesoftware/backplaneapi:0.26.1
  
  docker run —network my-network —name cli -p 3000:3000 backplanesoftware/backplanecli:0.0.1
  

Configure CLI

• Set CLI server to docker URL http://api:8000/api

  bp auth setserver —server  http://api:8000/api
  

The Backplane API Server is now up and running and you are ready to Start Using Backplane

Creating a Service Principal in Azure

To create credentials you’ll need to create an App registration in Entra ID.

1. Go to Microsoft Entra ID, and under Manage in the left side menu, select App registrations.

2. Click on New Registration and provide a name (e.g. backplane-api) a name and click Register.

3. Take note of the Tenant ID and Client ID.

4. Create a new Client Secret, click on Add a certificate or secret, New client secret, type a description, set expiry and click Add. Make a note of the Secret Value.

5. Assign the Service Principal you created with Contributor permission at the Subscription scope.

Add Azure Credentials via CLI

bp cloud azure add --id "<orgID>"
--tenantid "<tenant ID>"
--clientid "<client ID>"
--clientsecret "<Your Client Secret>"
--subscriptionid "<default subscription GUID>"

Note:

The Subscription ID is required in the MVP since App environments are provisioned as Resource Groups as opposed to Subscriptions. Subscription environments will be in a future release.

Creating a Service Principal in GCP

1. Login to https://console.cloud.google.com
2. Go to IAM and admin > Service accounts
3. Select a Project and click on Create Service Account
4. Enter a service account name e.g. backplane-api and a description e.g. For Backplane API environment provisioning
5. Click Create and Continue
6. Click on Done.
7. Click on IAM and switch to the Organisation level.
8. Click on Grant Access
9. Enter the service principal name e.g. backplane-demo@backplane-core.iam.gserfviceaccount.com
10. In role, find Project Creator, click Save.
11. Go back to your Project and click on IAM and Admin and then Service Accounts
12. Click on your Service Account and select Keys, Add Key, Create New Key. Use JSON as the Key Type. Click on Create. This will download a .json file.
13. Finally, go to APIs and Services and ensure Cloud Resource Manager API is enabled.

The downloaded JSON is now ready to be used in your Org.

Add GCP Credentials via CLI

bp cloud gcp add --id "<OrgID>" --tenantid "<Enter Google Org ID>" --gcpsecret "<path-to-JSON-file>"

Creating a Service Principal in AWS

1. Login to AWS Management Console
2. Go to IAM
3. Click on Users
4. Click on Create User
5. Enter User Details e.g. backplane-api, click next
6. Permission Options, select attach policies directly
7. Click on Create Policy and in Policy Editor select JSON. Paste in the below JSON

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Action": [
                "organizations:CreateAccount",
                "organizations:DescribeOrganization",
                "iam:ListUsers",
                "organizations:ListPolicies"
            ],
            "Resource": "*"
        }
    ]
}

8. Click Next, give Policy Name Backplane-account-creator
9. Click Create Policy
10. Click Create User
11. Click on the new User Created, and click on Security Credentials
12. Click on Create Access Key
13. Select Third-party service use-case and tick the confirmation and click Next
14. Create access key, record Access key and Secret access key values. Click Done.

Add AWS Credentials via CLI

bp cloud aws add --id "<OrgId>" --clientid "<accessKey>" --clientsecret "<accessKeySecret>"

Creating a Service Principal in OCI

Here’s how you can set up and use a service principal for authenticating Backplane with OCI

Create a Dynamic Group

1. Log in to the Oracle Cloud Console.
2. Obtain the Root Compartment OCID from Identity & Security -> Compartments
3. Navigate to Identity & Security -> Domains -> Click on Domain -> Dynamic Groups
4. Create a New Dynamic Group:

• Click on “Create Dynamic Group”.

• Enter a Name and Description for the dynamic group

  Field	Value
  Name	Backplane API
  Description	Service Credentials for Backplane API to create compartments

• Define the Matching Rules to include the instances or resources that you want this dynamic group to manage. For example, to include all instances in your tenancy:

  Matching Rule

  ALL {instance.compartment.id = '<your_compartment_ocid>'}
  

  • Click Create

Create a Policy

• Navigate to Identity & Security > Policies

• Click Create Policy

  • Enter a Name, Description, and Compartment for the policy.
  • In Policy Builder, toggle it to show manual editor and add the required Policy Statement/s. For example, to allow the Dynamic Group to manage all resources:

  Allow dynamic-group '<Domain>'/'<Dynamic Group Name>' to manage all-resources in tenancy
  

  • Click Create

Collect Information

• Create an oci.json file as per template below with the information collected

Example oci.json

{
  "tenancyId": "ocid1.tenancy.oc1..aaaaaaaane...",
  "userId": "ocid1.user.oc1..aaaaaaaayuatcpsk...",
  "fingerprint": "xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx",
  "privateKey": "-----BEGIN PRIVATE KEY-----\nMIIEv...n-----END PRIVATE KEY-----\n",
  "region": "uk-london-1",
  "passphrase": null
}

Add OCI Credentials via CLI

bp cloud oci add -i 66681fa21440f6afb76522e6 --ocisecret ../oci.json

• OCI Credentials are now added to Backplane for Compartment Creation