Create a Settle App

 

Support

Find other settle developers to work with and chat with our team: Concourse Discord

 

This guide covers


  • Create a settle account
  • Register an app
  • Get access to the developer pipeline
  • Get your API keys
  • Clone and run the starter kit
  • Starter Kit Folder Structure
  • Test your app locally in the sandbox
  • Deploy to the staging environment
  • Deploy to the production environment
  • Submit your app to be publicly available in the app store

Creating a Settle Account


Create Account – To create a Settle account, simply follow the link and fill out the form. You will receive a verification email, use the link in that email to validate your account.

Registering Your App



Important – you must register your app!

Apps are registered and managed through the Developer Tools app in Settle. Install and open it to continue.

Steps

First, become a Settle developer and create an app

Once you have the developer tools opened, opt in as a developer on the first page. 

Now that your a Settle developer, create a new app. Once you set a name for your app you can continue to step #2 and fill in other details about your app later (category in the app store, hosting options, keywords, ect)

Next, request a repo to deploy your app to

You’ll need a Bitbucket account, enter your email address for the account and click ‘Request Repo’ to complete registration. You should receive a confirmation email from Settle. It will normally take a few hours to get your repository set up, when that’s done you’ll receive another confirmation email with some important links and credentials.

Receive your repo

After requesting a repo, you will get access to deploy your app within 24 hours

Opting in to provide data to your app

Now is also a good time to install your app, the quickest way to do that is to click ‘Install App’ in the app profile area. Your app needs to be installed for your settle user account to allow access to user specific API data. This may not be needed right away, but make sure to do it now as it’s easy to forget and can be confusing later on when trying to debug if your app isn’t working during testing.

For example, if your app uses portfolio data, you will need to opt in to providing this data to your app. Since your app isnt in the app store yet, this can be done privately in the dev tools.

Run The Starter Kit


Your app runs from a Bitbucket Repository.
The default starter kit users Node/React.
Your deployment to servers is managed by  Jenkins.
You can request another repo on our Support Channel.

To continue make sure you registered an app and received a repo in the last step.

Steps

The Easy Way – Clone with HTTPS

When viewing your repository on Bitbucket, you can clone it by clicking the button in the upper right area of the page.

You will be presented with a popup that will provide the Git command to clone the repository. The easiest option is to use HTTPS (make sure to select this option in the upper right area of the popup). You will be asked for a password when cloning the repository, this will be the password of the Atlassian account you’re using to access Bitbucket.

The Hard Way – Clone with SSH

  1. Create an SSH key
  2. Upload your ssh key so you can access your repo: https://bitbucket.org/account/user/<YOUR_ACCOUNT_NAME>/ssh-keys/
  3. Clone your repo and add your ssh key:
ssh-agent bash -c ‘ssh-add <OPEN_SSH_KEY_LOCATION>; git clone [email protected]:SettleApps/<REPOSITORY_NAME>.git’

cd <REPOSITORY_NAME>/

// Example:

ssh-agent bash -c ‘ssh-add /Users/<user>/.ssh/new-bitbucket-key.ssh; git clone [email protected]:<REPOSITORY_NAME>.git’

Initial Setup

The JS starter kit provides an example of interacting with the price feed API. The settle API requires Authentication.

First, you’ll need to enter your app’s key and secret in the ‘/Sources/Apps/app-1/app/.env’ file:

SETTLE_API_KEY    = 'YOUR API KEY HERE'
SETTLE_API_SECRET = 'YOUR API SECRET HERE'

These can be found in the Developer Tools app; You can find it in the app list in the left sidebar of Settle, or use this link to bring it up. Select the ‘Apps’ tab, make sure your app is selected from the list on the left and select ‘Developer Credentials’.

If you didn’t request a repo yet, you can also find your API keys at the bottom of the first page in the dev tools.

You can find your API key and secret here, as well as other important information about your app.

Finally, open a terminal window and change directory to

// /Sources/Apps/app-1/app/
npm install

 

After a successful initial setup, your app should be ready to run locally:

npm run local

Your app should now be accessible from: http://localhost:3000

 

Repository Structure

By default the example code that comes in your repository includes everything needed to run a basic Node/React frontend and server (based on https://github.com/facebook/create-react-app), as well as a very minimal example to demonstrate how to make api calls with the Settle SDK.

The actual app code is found in ‘Sources/Apps/App-1/app/’, this is where most if not all of your own modifications will be made while making your own app. You can safely replace the contents of this folder with other Settle app examples, or your own custom code as long as you make sure either that your package.json file responds to the same ‘local’ and ‘deploy’ npm scripts as found in the example, or that you modify the deployment scripts and configurations (found one level up in ‘Sources/Apps/App-1’).

You should be aware that the repository is structured in a certain way to work with the automated deployment scripts. as a general rule changes can be made freely within ‘Sources/Apps/App-1/app/’, keeping in mind the above considerations for npm scripts. Changes can also be made to the configuration and deployment scripts up one level in ‘Sources/Apps/App-1’, though you’ll need to be a bit more careful and knowledgeable of the deployment process for this to work smoothly. Changes should NOT be made to the contents sources ‘Sources’ directory without coordination with Settle, including renaming the ‘app-1’ folder, as this will break the deployment process unless appropriate changes are made to the core deployment scripts.

The scripts folder contains various deployment scripts for the repository. In general you shouldn’t have to worry about these scripts unless your app has some advanced deployment requirements. If you need to make changes to these scripts this should be coordinated with Settle Team members; The scripts area is compared to a hash for security, and if changed will need to be reviewed and authenticated by Settle before a build will be able to run with the updated scripts.

Multiple apps can be added to the same repository on request, so for example you might have app-1 and app-2 in your ‘Sources/Apps’ folder. The name of these app folders should not be changed however, and in general you should only make changes within your app folders (like ‘Sources/Apps/app-1’) unless you have advanced configuration requirements and coordinate with Settle as this will likely require authenticated deployment changes to be made.

The important code can be found in the highlighted files. ‘server.js’ is the backend server, and ‘src’ contains the react specific files. ‘index.jsx’ is responsible for setting up react and handling the important token and mode parameters passed to the iframe when running in Settle. ‘App.jsx’ is the main component that renders the app.

Testing Your App Locally


Apps can be user specific, meaning that they use the “token” GET param to authenticate a user, or could be non user specific that return the same data to everyone who loads it.
A non user specific app can run in your browser.
A user specific app must run inside of the developer sandbox.

Running In The Sandbox

When apps run in Settle, they are loaded in an iframe and are provided with important query string arguments to identify the user viewing the app, and the view mode the app is in.

Settle passes in:

  • ?mode = work, helper or alert
  • ?token = a users token to convert to a GUID and make API calls with Settle.exchangeTokenForGuid({token: token})

To make things simple, Settle provides a Developer Sandbox app to take care of this for you. Just open up the ‘Developer Sandbox app from the app list on the left of the page, then enter http://localhost:3000 into the url area in the upper left of the app view, and click ‘Embed’ to the right. The example app should now load up within the developer sandbox.

Did it not work? Check the next tab for how to allow your HTTP app in HTTPS.

HTTP In HTTPS

Since Settle uses HTTPS, you’ll probably run into an issue with having the develop sandbox load your app on an unsecured HTTP connection.  The recommended option is to download ngrok and run ./ngrok http <port> . Grab the https url, eg https://f52b35af.ngrok.io and paste that into the dev sandbox

If preferred, an easier way to solve this is to allow unsecure assets to load on the page. In chrome this is done by clicking the shield icon in the right of the address bar and clicking ‘Load Unsafe Scripts’.

During development, the local server can auto-refresh most changes you make both in react (via the React development server) and the backend server (via nodemon).

Troubleshooting

If your app requested private data such as the portfolio, you need to install the app or else requests will be unauthorized. You can install your app privately in the developer tools:

Deployment


Overview

Settle has a built in deployment pipeline to handle your staging and production environment.

Test deployment – a staging environment to test your apps before pushing to production.
Branch: develop

Production deployment – a zero down time production server to serve to settle users.
Branch: master

Jenkins

Settle provides your app access to manage deployments in jenkins. To access it, log in at https://www.production.settle.host/jenkins – Your login credentials can be found in the ‘Developer Details’ section of the Developer Tools app.

The testing deployment is tied to your ‘develop’ branch, so make sure any changes are committed/merged there from your feature branch before starting a build.

Test Deployment

Branch: Test deployments run on the develop branch in your Bitbucket repo.

1) Bitbucket

Push your code to the develop branch in Bitbucket then you can trigger your deployment in Jenkins.

// Example of pushing to the develop branch
git checkout -b develop
// make a change to the code
git add .
git commit -m ‘my first commit’
git push origin develop

 

2) Jenkins

To deploy for testing, go to the main Jenkins dashboard and click on the link ‘Settle-App-xx-Test’ that matches your app number. If you have multiple apps, it may help to filter the available jobs to just the app you want to work with by selecting the tab at the top left of the pipeline table.

When viewing the test pipeline for you app, you can click ‘Build Now’ in the left menu to start the build process. A new build will appear in the build history showing progress of the deployment. When complete you’ll see the build will show a blue icon if successful, or a red icon if the build failed.

For additional information you can click on an item in the build history to view details for that build. Console output is available which can be invaluable in the event of a failed build, or should any debugging of the build process be necessary.

Access your test app:

Find your apps direct link your developer tools under “Step 4” Developer Details. Your link will be https://test-<your dev id>-ui-1.public.settle.host

Production Deployment

Production deployment works a bit differently from test deployment since a production build can’t be directly triggered manually. When you’re ready to do a production build of your app, you must first do a pull request from develop to master in Bitbucket.

Make sure to add ‘Jenkins Settle Host’ as a reviewer – This is necessary for automatically validating and triggering the build. Click ‘Create pull request’ in the bottom right when your done.

Next, a successful test deployment needs to be run; You can follow the steps above in the ‘Test Deployment’ section to do this. Once the test deployment has successfully completed, the Jenkins Settle Host will automatically approve the pull request; You should receive an email notification when this happens.

After the pull request has been approved you’ll be able to click ‘Merge’ when viewing it in Bitbucket. Merging to master following these steps will trigger the production pipeline to run in Jenkins. From there, you’ll be able to view the build progress and info just as you would for a test build.

 

 

Access your production app:

Find your apps direct link your developer tools under “Step 4” Developer Details. Your link will be https://prod-<your dev id>-ui-1.public.settle.host

App Store


Prepare Your App

Your app is going to be listed in the Settle app store as a chat plugin or app, depending on what you selected on the app details page of your developer tools.

Select an app store category for your app in the developer tools.

List Your App In The App Store

On step 4 of your app (“developer details”) in the developer tools, click “Submit App”.

You will get a confirmation email that we are processing the request, and a confirmation when your app is live.

Link A Settle Hub

In the Developer Tools under “App Details” link a hub that you’ve created.

Your apps community hub is available in the nar bar.

Tutorials

Gas Station Tutorial

Risk Check Tutorial