Configure your development environment
This articles provides the steps to configure your development environment for Optimizely Connect Platform (OCP).
To build an app in Optimizely Connect Platform (OCP), you need:
- An OCP developer account
- The OCP command-line interface (CLI)
- Your preferred integrated development environment (IDE)
To access the OCP CLI, you must have an OCP developer account. Then, you can use the OCP CLI to manage your app throughout the build process, from scaffolding the app structure to publishing the app to the Optimizely Data Platform (ODP) App Directory. Write the code for your app in TypeScript using your preferred IDE (for example, Visual Studio Code.
Request an OCP developer account
To begin working with OCP, sign up for an OCP developer account using one of the links below:
- Tech partner – Use this sign-up form if you are a company that has your own software that you want to integrate with ODP.
- Solution partner – Use this sign-up form if you want to create a third-party app in OCP.
During onboarding, you are given one of two roles:
- Developer – Allows you to run all commands in the OCP CLI except for those that let you publish your app to the public in the ODP App Directory.
- Publisher – Gives you all the same access as the developer role, with the addition of being able to publish apps to the public in the ODP App Directory.
Configure the OCP CLI
Develop, manage, and publish an OCP app using the OCP CLI. You can configure the OCP CLI on either a Mac/Linux machine or a Windows machine. Skip directly to the section that pertains to your environment.
Prerequisites
- An OCP developer account.
- The API key from your invitation email.
- Node.js 18 JavaScript runtime environment. Find your platform-specific installer here, or use your preferred Node version manager for the install.
- Yarn; find global install instructions for Yarn here. If you are on Windows, we suggest installing Yarn through Corepack, as described here.
Important
OCP requires Yarn 1 (classic). Make sure you have the supported version installed (
yarn -v
). - The OCP CLI requires Git to build an app. Find global install instructions for Git here.
Note
If you are not planning to build an app, you can skip the Git install.
Configure the OCP CLI for Mac/Linux
-
Run the following command to make a
.ocp
directory:mkdir ~/.ocp (home dir)
-
Using the API key you received during onboarding, create the credentials file in the
.ocp
directory:echo '{"apiKey": "<value-from-invitation>"}' > ~/.ocp/credentials.json
-
Run the following Yarn command to install the OCP CLI:
yarn global add @optimizely/ocp-cli
-
Set your
PATH
variable:export PATH="$(yarn global bin):$PATH"
Configure the OCP CLI for Windows
Note
The following instructions are for PowerShell.
-
Run the following command to make a
.ocp
directory:New-Item -Path "~/.ocp" -Name "home dir" -ItemType "directory"
-
Using the API key you received during onboarding, create the credentials file in the
.ocp
directory:Write-Output '{"apiKey": "<value-from-invitation>"}' | out-file "~/.ocp/credentials.json" -encoding utf8
-
Run the following Yarn command to install the OCP CLI:
yarn global add @optimizely/ocp-cli
-
Ensure the value returned from
yarn global bin
is on your path:yarn global bin
Note
The output should look similar to the following:
C:\Users\[YOUR_USERNAME]\AppData\Local\Yarn\bin
If it does not, follow these instructions to set your
Path
variable.
Test your OCP CLI configuration
Verify your OCP CLI configuration by running the following command:
ocp accounts whoami
The results should look similar to the following:
$ ocp accounts whoami
id: e1006b36-183e-4951-912c-416012f5a882
email: [email protected]
role: developer
githubUsername: jonhsmith
accounts:
- 7b5d1518a0be
personal_apps: []
vendor: mycompany
vendor_apps: []
OCP CLI help command
Commands are grouped into namespaces:
$ ocp -h
Usage: ocp <command>
Namespaces: (`<namespace>` -h, --help for additional help)
accounts
app
availability
directory
env
jobs
review
Run the help command, -h
or --help
, to list commands in a namespace, for example:
$ ocp app -h
Usage: ocp app <command>
Commands:
init Create a new app project
logs Fetch app logs
package Prepare a package for manual upload
prepare Validate, package, upload and build an app to prepare for publishing
register Register an app version
validate Validate an app locally
ocp <command> -h, --help for help on specific commands
Adding the help context on a command displays documentation for the command with all available options, for example:
$ ocp app prepare -h
Usage: ocp app prepare [<path>] [--noProgress | --no-progress] [--upgradeDeps | --upgrade-deps] [--publish] [--usePreviousAppEnvValues | --use-previous-app-env-values]
[--bumpDevVersion | --bump-dev-version]
Parameters:
path The root directory of the app
Flags:
--noProgress, --no-progress Don't display any progress indicators
--upgradeDeps, --upgrade-deps Automatically update dependencies
--publish Automatically publish if the upload is successful
--usePreviousAppEnvValues, --use-previous-app-env-values Use app env values (.env file) from the previous version of the app. Any values in local .env file will be ignored
--bumpDevVersion, --bump-dev-version Bump dev version before building. Allows quickly testing dev versions
OCP CLI commands
The table below lists all available OCP CLI commands with their parameters and descriptions.
Command | Parameters | Description |
---|---|---|
ocp -h | The help context for the OCP CLI is -h . It provides information about your environment when you run ocp -h and provides contextual help when you add -h after any command. | |
ocp accounts whoami | Returns your account information. | |
ocp accounts whois | <user> | Returns basic account information for a specific user. Requires a user input, for example, ocp accounts whois "user" . |
ocp app init | <appId> | Creates a new app project and initializes the app. Requires the app ID, for example, ocp app init <appId> . |
ocp app logs | <appId> or <buildId> | Returns app logs. Requires the app ID or build ID, for example, ocp app logs <buildId> . See additional flags/options. |
ocp app package | <path> | Prepares a package for manual upload. Requires the path for the root directory of the app, for example, ocp app package <path> . |
ocp app prepare | <path> | Validates, packages, uploads, and builds an app to prepare for publishing. Requires the path for the root directory of the app, for example, ocp app prepare <path> . See additional flags/options. |
ocp app register | <id> <name> | Registers an app version. Requires the app ID and name, for example, ocp app register <id> <name> . You can append --availability or --a to define the availability region to which the app is registered (default is US). |
ocp app validate | <path> | Validates an app locally. Requires the path for the root directory of the app, for example, ocp app validate <path> . See additional flags/options. |
ocp availability list | Lists all availability regions (US, EU, AU). | |
ocp directory unpublish | <[email protected]> | Unpublishes an app version (uninstalls everywhere and undeploys). Requires the app ID and version in the following format: <[email protected]> . For example, ocp directory unpublish <[email protected]> . See additional flags/options. |
ocp directory publish | <[email protected]> | Publishes (makes available) a specific app version that has been reviewed and approved. Requires the app ID and version in the following format: <[email protected]> . For example, ocp directory publish <[email protected]> . You can append --noProgress or --no-progress . COMPLETE THIS LATER |
ocp directory info | <appId> | Gets information about an app. Requires the app ID, for example, ocp directory info <appId> . You can append --availability or --a to define the availability region of the app (default is US). |
ocp directory install | <[email protected]> <trackerId> | Installs a specific app version into an account. Requires the app ID and version (in the following format: <[email protected]> ), and the tracker ID of the account to which you want to install the app. For example, ocp directory install <[email protected]> <trackerId> . You can append --availability or --a to define the availability region of the app (default is US). |
ocp directory list | <appId> | Lists registered app versions. Lists all apps by default if you do not define the app ID, for example, ocp directory list <appId> . See additional flags/options. |
ocp directory listFunctions or ocp directory list-functions | <appId> <trackerId> | Lists the functions exposed by an app installation. Requires the app ID and tracker ID, for example, ocp directory listFunctions <appId> <trackerId> . You can append --availability or --a to define the availability region of the app (default is US). |
ocp directory listGlobalFunctions or ocp directory list-global-functions | <appId> | Lists the global functions exposed by an app. Requires the app ID, for example, ocp directory listGlobalFunctions <appId> . You can append --availability or --a to define the availability region of the app (default is US). |
ocp directory listInstalls or ocp directory list-installs | <[email protected]> | Lists installations of a specific app version. Requires the app ID and version (in the following format: <[email protected]> ). For example, ocp directory listInstalls <[email protected]> . You can append --availability or --a to define the availability region of the app (default is US). |
ocp directory status | <[email protected]> | Gets the status of a particular app ID and version. Requires the app ID and version (in the following format: <[email protected]> ). For example, ocp directory status <[email protected]> . You can append --availability or --a to define the availability region of the app (default is US). |
ocp directory uninstall | <appId> <trackerId> | Uninstalls an app from an account. Requires the app ID and tracker ID, for example, ocp directory uninstall <appId> <trackerId> . You can append --availability or --a to define the availability region of the app (default is US). |
ocp directory upgrade | <appId <trackerId> | Upgrades the install to a specific app version. Requires the app ID and tracker ID, for example, ocp directory upgrade <appId> <trackerId> . See additional flags/options. |
ocp env get | Gets the current environment of the OCP CLI. | |
ocp env set | <env> | Sets the current environment for the OCP CLI. Requires the environment name. |
ocp jobs list | <appId> | Lists jobs. Requires the app ID for which you want to view jobs, for example, ocp jobs list <appId> . See additional flags/options. |
ocp jobs terminate | <jobId> | Terminates a job. Requires the ID of the job to terminate. You can append --availability or --a to define the availability region (default is US). |
ocp jobs trigger | <[email protected]> <jobName> <trackerId> | Triggers a job. Requires the app ID and version (in the following format: <[email protected]> ), job name, and tracker ID of the account for which you want to trigger the job. For example, ocp jobs trigger <appVersion> <jobName> <trackerId> . See additional flags/options. |
ocp review list | <appId> | Lists app versions currently under review. You can optionally define the app ID of the app for which you want to view versions under review (for example, ocp review list <appId> . Lists all apps by default. |
ocp review open | <[email protected]> | Opens a review in your browser. Requires the app ID and version (in the following format: <[email protected]> ). For example, ocp review open <[email protected]> . |
Additional flags/options for OCP CLI commands
You can append various flags/options for some of the OCP CLI commands, listed below.
ocp app logs
--tail
– Tails the logs.--appId
--buildId
--appVersion
--trackerId
--jobId
--installId
--from
– A start time as an ISO string, an epoch timestamp, or relative string (for example,5m
for 5 minutes). Default is24h
.--to
– An end time as an ISO string, an epoch timestamp, or relative string (for example,5m
for 5 minutes).--search
– String to search for in log messages. Can be specified multiple times.--availability
or-a
– The availability region that will be targeted (default is US).
ocp app prepare
--noProgress
or--no-progress
– Do not display any progress indicators.--upgradeDeps
or--upgrade-deps
– Automatically update dependencies.--publish
– Automatically publish if the upload is successful.--usePreviousAppEnvValues
or--use-previous-app-env-values
– Use app env values (.env file) from the previous version of the app. Any values in the local .env file will be ignored.--bumpDevVersion
or--bump-dev-version
– Bump dev version before building. Allows you to quickly test dev versions.
ocp app validate
--noProgress
or--no-progress
– Do not display any progress indicators.--upgradeDeps
or--upgrade-deps
– Automatically update dependencies.
ocp directory unpublish
--force
or-f
--noProgress
or--no-progress
--availability
or-a
– The availability region that will be targeted (default is US).
ocp directory list
--allStatuses
– Includes all statuses. The stopped status is not included by default.--availability
or-a
– The availability region that will be targeted (default is US).
ocp directory upgrade
--toVersion
or-v
– The desired version (for example, 1.0.0).--availability
or-a
– The availability region that will be targeted (default is US).
ocp jobs list
--version
– Specific versions to filter by.--trackerId
– Specific Tracker IDs to filter by.--function
– Specific job function to filter by.--status
– Specific job status to filter by. Possible values: PENDING, SCHEDULED, RUNNING, COMPLETE, ERROR, TERMINATED.--minDuration
– Show jobs that have been running longer than the given duration (for example, 5m = 5 minutes).--sortBy
– Column to sort the jobs by. Possible values: id, function, trackerId, status, error, createdAt, triggeredAt, scheduledAt, terminatedAt, updatedAt, duration. The default column to sort by is updatedAt.--sortDirection
– Sort resulting jobs in ascending or descending order. Possible values: asc or desc. The default sort direction is asc.--limit
– Number of jobs to list. The default is 50.--columns
– Columns to display. Possible values: id, version, function, trackerId, trigger, status, error, createdAt, triggeredAt, scheduledAt, terminatedAt, updatedAt, duration. The default columns are id, version, function, trackerId, status, updatedAt.--from
– A start time as an ISO string, an epoch timestamp, or relative string (for example, 5m = 5 minutes). The default time value is 24h.--to
– An end time as an ISO string, an epoch timestamp, or relative string (for example, 5m = 5 minutes).--availability
or-a
– The availability region that will be targeted (default is US).
ocp jobs trigger
--parameters
– Parameters to pass to the job.--availability
or-a
– The availability region that will be targeted (default is US).
Updated 6 days ago