Integrating the Vega SDK into CI Pipelines

This page describes how to integrate the Vega SDK into Continuous Integration (CI) pipelines, including automated installation processes and configuration requirements.

A build host is the machine (virtual or physical) that builds your Vega app as part of a Continuous Integration (CI) pipeline. The Vega SDK provides an installation command on the installation instructions page that can run non-interactively, avoiding user input to facilitate automated SDK installation on a build host. On the installation page, you must select the appropriate operating system and architecture for your build host. For example, if your build host is running Ubuntu 22.04, select "Linux (x86_64)" from the "Operating System" drop-down. The resulting command can then be run on the build host.

In addition, you must configure the npm client on the build host to use Amazon’s private npm registry for downloading Vega npm packages.

Automating your build and deployment processes is crucial for maintaining consistent, high-quality software releases. Integrating the Vega SDK into your CI pipeline can significantly streamline your development workflow. This guide describes the process, requirements, and important considerations.

Prerequisites

Before integrating the Vega SDK into your CI pipeline, make sure that your build environment meets the following requirements. Pay particular attention to selecting the correct platform for your build host, as choosing the wrong platform can lead to installation or runtime errors.

System Requirements

Host Configurations

• Operating System
  • Ubuntu 20.04 or higher
    • x86_64
  • Mac OS X
    • arm64 or x86_64

User Requirements

Vega OS versions prior to 0.20.3106

* Non-root user account on the build host/CI environment
    * Required for all installation methods
    * For direct CI/CD installations, ensure build process runs as non-root

Vega OS versions 0.20.3106 and later

* There is no longer a requirement for a non-root user account
* Set `NONINTERACTIVE=true` for CI environments

Installation Process

The Vega SDK installation process needs special consideration when implementing it in a CI environment. Unlike developer workstations where interactive installation is common, CI environments require a fully automated approach. The following sections guide you through this process.

Basic Installation

1. From the installation page, select the appropriate OS and architecture for your build host
2. Use the provided installation command in non-interactive mode

Non-root User Requirement

Note: For SDK versions prior to 0.20.3106, the installer script must be run by a non-root user.

Environment Variable Configuration

Use the following environment variables to control the installer script:

Installation Directory Configuration

*# Default installation path: $HOME/kepler/sdk/$VERSION*
*# Custom installation example:*
curl -fsSL <script url> | INSTALL_ROOT_DIR=/opt/kepler /bin/bash --version <version> --sdk-url <sdk url>

Important Considerations

Environment Variables

After installation, you need to configure the environment to locate the SDK tools.

Set KEPLER_SDK_PATH

export KEPLER_SDK_PATH="/path/to/kepler/sdk/version"

Add to System PATH

export PATH="/path/to/kepler/sdk/version/bin:$PATH"

Example

If your SDK is installed at /home/user/kepler/sdk/0.20.3106.

export KEPLER_SDK_PATH="/home/user/kepler/sdk/0.20.3106"
export PATH="/home/user/kepler/sdk/0.20.3106/bin:$PATH"

Verification: To verify correct setup, run the following command.

kepler -v  

Optional VVD Image Installation

Starting in version 0.20.3106, the installation of the Vega Virtual Device (VVD) image is optional to reduce the effective size of the SDK installation:

• Remove the --sim-url flag to skip downloading and installing the VVD image
• This can significantly reduce installation footprint in CI environments

VS Code Plugin Notes

In CI environments, you can safely ignore VS Code plugin installation errors.

Telemetry Configuration

# Use the OPT_IN environment variable to enable telemetry
curl -fssL <script url> | OPT_IN=true /bin/bash --version <version> --sdk-url <url>

Docker Integration

Docker provides a consistent and isolated environment for building applications with the Vega SDK. The following example demonstrates how to create a build environment that includes all necessary dependencies and configurations. This approach can be adapted for various CI solutions that support container-based builds.

Example Dockerfile

FROM ubuntu:22.04

SHELL ["/bin/bash", "-c"]

# Need cURL to fetch the installer.
RUN apt-get update && \
    apt-get install curl ca-certificates --no-install-recommends -y && \
    rm -rf /var/lib/apt/lists/*

# Install Vega SDK
ARG INSTALLER_SCRIPT
ARG SDK_VERSION
ARG SDK_URL
ARG SDK_ROOT=/kepler
ARG SIM_URL
RUN test -n "$INSTALLER_SCRIPT" || (echo "INSTALLER_SCRIPT not set" && false)
RUN test -n "$SDK_VERSION" || (echo "SDK_VERSION not set" && false)
RUN test -n "$SDK_URL" || (echo "SDK_URL not set" && false)
RUN curl ${INSTALLER_SCRIPT} | NONINTERACTIVE=true INSTALL_ROOT_DIR=${SDK_ROOT} bash -s -- \
    --sdk-url=${SDK_URL} \
    --sim-url=${SIM_URL} \
    --version=${SDK_VERSION}
## Setup required environment variables
## Note that the script installs into $SDK_ROOT/sdk/$SDK_VERSION
## If $SDK_ROOT was not set, it defaults to /kepler
ENV KEPLER_SDK_PATH="$SDK_ROOT/$SDK_VERSION"
ENV PATH="$KEPLER_SDK_PATH/bin:$PATH"
## Verify kepler command is available
RUN kepler -v

# If you are building a React Native app, NodeJS and NPM are required
RUN curl -sL https://deb.nodesource.com/setup_lts.x | bash -
RUN apt-get update && apt-get install -y nodejs
RUN npm install -g npm

## Set global npm config path to /etc/npmrc
## Bind mount your npmrc config to this location
ENV NPM_CONFIG_GLOBALCONFIG="/etc/npmrc"
## Verify node and npm commands are available
RUN node -v && npm -v

ENTRYPOINT [ "/bin/bash", "-c" ]

Docker Build Example

docker build . --tag ksdk \
--build-arg INSTALLER_SCRIPT=<url_to_installer_script> \
--build-arg SDK_URL=<url_to_sdk> \
--build-arg SIM_URL=<url_to_simulator> \
--build-arg SDK_VERSION=0.20.3106 \
--build-arg SDK_ROOT=/tmp/kepler

Last updated: Sep 30, 2025