Skip to main content

Quickstart

This quickstart will help you learn how to create an app plugin using SE2. It will also introduce some of SE2's key features to manage development environments and user access, and the plugin editor.

Prerequisites​

  • The Subo CLI (installation instructions below) is supported only on MacOS and Linux
  • Check out our language support page to see a list of languages and their respective support statuses for SE2
  • Install Docker

Create a development environment​

The Subo CLI will create some files on disk to set up your local deployment. Get started by creating a directory somewhere on your filesystem. In the example below, we'll name our directory suborbital:

mkdir suborbital && cd suborbital

Install Subo: the SE2 CLI​

If you use macOS, you can use Homebrew to install the subo command line tool:

brew tap suborbital/subo
brew install subo

Note: this may take a few minutes! Next, run subo --version to ensure the installation was successful.

To install on Linux (or macOS without Homebrew), you can download Subo directly.

You can set up multiple separate environments within an organization. These could be used for separating production/development/staging environments,or to create different applications for distinct use cases.

Generate your env token​

You can get an SE2 Environment token either with our environment token generator web app or with the subo command line tool.

To create your env token, run:

subo se2 create token <your email address>

A verification code will be sent to your email address, and the env token will be used to authenticate you and link your SE2 installation to you.

tip

Subo will print out your environment token in your terminal, and also cache it on disk for transparent use in later steps.

If you lose your environment token, just repeat this process to generate a new one.

Start SE2 locally​

Danger, Will Robinson

If you're coming from Suborbital Compute v0.3.3 or earlier and would like to develop locally on SE2 v0.4.0 or greater, you must first upgrade to Subo v0.6.0 and update the deployment templates with subo se2 deploy --reset.

An SE2 migration tool for production deployments of Compute will be available soon.

Next, use Subo to start your local SE2 instance. Make sure to do this within the same directory you created above!

  • Make sure Docker is running

  • Run:

    subo se2 deploy --local

  • Grab a refreshing beverage while this runs (it'll take a few minutes!)

You may be asked to enter your environment token, and then Subo will use docker-compose to launch your SE2 instance automatically. SE2 runs in the background by default. You can use docker-compose logs -f to view the logs of the running containers. Run docker-compose down to terminate the containers.

When you run SE2, it will wait for you to press enter to start a REPL where you can add or edit plugins (see Meet the Editor). In the example below, we'll create a plugin named hello:

⏩ START: preparing deployment
ℹ️  using cached environment token
✅ DONE: ready to start installation
⏩ START: installing...
Network suborbital_se2  Creating
Network suborbital_se2  Created
Container suborbital-se2-builder-1  Creating
Container suborbital-se2-controlplane-1  Creating
Container suborbital-se2-controlplane-1  Created
Container suborbital-e2core-1  Creating
Container suborbital-se2-builder-1  Created
Container suborbital-e2core-1  Created
Container suborbital-se2-builder-1  Starting
Container suborbital-se2-controlplane-1  Starting
Container suborbital-se2-controlplane-1  Started
Container suborbital-e2core-1  Starting
Container suborbital-se2-builder-1  Started
Container suborbital-e2core-1  Started
ℹ️  use `docker ps` and `docker compose logs` to check deployment status

PROXY: local tunnel to plugin editor started


Press enter to launch the local SE2 REPL...
1. Create or edit a plugin

Choose an option: 1

To create or edit a plugin, enter its name (or FQMN): hello

✅ visit http://local.suborbital.network/?builder=http://local.suborbital.network:8082&token=0PYjmlH10jjjIL2NUOXzAfCA&ident=com.suborbital.acmeco&namespace=default&fn=hello to access the editor

This will allow you to create plugins and use the plugin editor locally while you work on integrating your application. Follow the instructions in the REPL to create your first plugin.

The Subo REPL includes a proxy that makes it easy to connect the hosted editor to your local SE2 installation. By default, it makes the editor accessible on local.suborbital.network:80. The editor proxy port can be configured with the subo se2 deploy --local --proxy-port <some port> option.

The local.suborbital.network subdomain points to 127.0.0.1, i.e. localhost. You may need to substitute a different hostname or IP address depending on your particular network setup.

Meet the editor​

The SE2 plugin editor uses SE2's APIs from either Go or JavaScript/TypeScript to provide a low-friction environment for your users to write, build, test, and deploy plugins to your SE2 an instance in a single place. Alternatively, the Builder API can be used programmatically, if that better suits your use case.

Obtain an editor token​

In addition to the IDENTIFIER and ENV_TOKEN, you’ll also need to set NAMESPACE and fn to the name of our namespace (e.g. default) and the name of our plugin (e.g. hello). Copy the token field in the response; this is your editor token.

curl --location --request GET "http://local.suborbital.network:8082/auth/v2/access/${IDENTIFIER}/${NAMESPACE}/${EXT}" \
--header "Authorization: Bearer ${ENV_TOKEN}"

Editor URLs in production​

To edit a plugin via the editor in a production environment, you—or more likely your application—must build a valid URL to pass to the editor.

Configure the URL like so:

  • Domain: https://editor.suborbital.network/
  • Query parameters:
    • builder: https://your-builder.example.com
    • token: The env token you created above
    • ident: The name of your environment followed by a period, followed by the name of your tenant. In our case, it will be dev.suborbital.user1
    • namespace: the name of your namespace if different than “default”
    • fn: the name of your plugin
    • template: the name of the language you wish to use (Go or JavaScript)

Altogether, it should look something like https://editor.suborbital.network/?builder=https://your-builder.example.com&ident=dev.suborbital.user1&fn=hello&template=javascript

Your first plugin​

Paste the URL you created above into your browser to load the plugin editor. Once inside the editor, you can edit, build, test, and deploy your plugins all in one place! By default, the editor will load pre-populated with the greeting plugin below. You can use it to run the editor for the first time.

import { log } from "@suborbital/runnable";

export const run = (input) => {
    let message = "Hello, " + input;

    log.info(message);
    return message;
};
  • The plugin provided is complete, so we can just click "Build"
  • In the "TEST" field, add some text. Here, we've added "new Suborbital user"
  • Click "Run test"
  • Toward the bottom of the editor, click "TEST RESULTS". There's our greeting!

Editor displaying the greeting plugin above with the test output &#39;Hello, new Suborbital user!&#39;

Executing plugins​

Once your first plugin has been built and deployed, it can be run with a request to the Execution API.

export ENV_TOKEN=<your previously generated token>

curl http://local.suborbital.network:8080/com.suborbital.acmeco/default/hello/v1.0.0 \
     --header "Authorization: Bearer $ENV_TOKEN" \
     -d 'my friend'

hello, my friend

Connect your application​

Now that you've set up SE2 and created your first plugin, you can use SE2's APIs from either Go or JavaScript/TypeScript to start integrating plugins into your application!