Getting Started

• 1: Quickstart
• 2: Import examples
• 3: Install a working container runtime
• 4: Working behind proxy

1 - Quickstart

This page describes

• how to create a GitHub repository for your Vehicle App development,
• how to set up and configure the DevContainer-based development environment , and
• how to build, customize and test the sample Vehicle App included in your freshly created Vehicle App repository.

You will learn how to use the Vehicle App SDK, interact with the Vehicle API and work with CI/CD using the pre-configured GitHub Workflows that come with the template repository.

Once you have completed all steps, you will have a solid understanding of the development workflow, and you will be able to use one of our template repositories as a starting point for your own Vehicle App development project.

Prerequisites

Please make sure you did all the prerequisite steps to create comprehensive development environment for your Vehicle App:

• Install VS Code

• Install a working container runtime

• Add the Remote-Containers extension to VS Code via the marketplace or using the command line:

  code --install-extension ms-vscode-remote.remote-containers
  

How to create your Vehicle App repository?

For your (GitHub) organization and Vehicle App repository the name MyOrg/MyFirstVehicleApp is used as a place holder during the rest of the document.

You can create your own repository using one of our provided templates or start prototyping via digital.auto.

• Using Template
• Velocitas CLI create
• digital.auto

How to start developing?

In this section you will learn different possibilities to start developing based on your repository. Basically you can work on your own machine using VS Code’s DevContainer or you can set up the environment on a remote agent, using GitHub Codespaces .

• VS Code
• GitHub Codespaces

You can find more information about the Vehicle App development in the respective pages .

How to start the runtime services?

The runtime services (like KUKSA Data Broker or Vehicle Services) are required to develop Vehicle Apps and run integration tests.

Currently, the supported options to run these services is either locally , in a Kubernetes (K3D) cluster or via the Kanto runtime .

• Local Runtime
• K3D Runtime
• Kanto Runtime

$ velocitas exec runtime-local up

Hint: Log files can be found in your workspace's logs directory
> mqtt-broker running
> vehicledatabroker running
> seatservice running
> feedercan running
✅ Runtime is ready to use!

$ velocitas exec runtime-k3d up

Hint: Log files can be found in your workspace's logs directory
> Checking K3D registry... created.
> Creating cluster with proxy configuration.
> Checking K3D cluster... created.
> Checking zipkin deployment... deployed.
> Checking dapr... initialized.
✅ Configuring controlplane for k3d...
> Deploying runtime... installed.
✅ Starting k3d runtime...

$ velocitas exec runtime-kanto up

Hint: Log files can be found in your workspace's logs directory
> Checking Kanto registry... registry already exists.
> Checking Kanto registry... starting registry.
> Checking Kanto registry... started.
✅ Configuring controlplane for Kanto...
⠇ Starting Kanto...waiting
✅ Kanto is ready to use!

More information about the runtimes are available here .

How to debug your Vehicle App?

Now that the runtime services are all up and running, let’s start a debug session for the Vehicle App.

• Python
• C++

How to trigger the CI Workflow?

The provided GitHub workflows are used to build the container image for the Vehicle App, run unit and integration tests and collect the test results.

The CI Workflow will be triggered by pushing a change to the main branch of your repository:

1. Make modification in any of your files

2. Navigate in your terminal to your repository

3. Commit and push your change

   git add .
   git commit -m "<explain your changes>"
   git push origin
   

To see the results open the Actions page of your repository on GitHub, go to CI Workflow and check the workflow output.

How to release your Vehicle App?

Now that the CI Workflow was successful, you are ready to build your first release. The goal is to build a ready-to-deploy container image that is published in the GitHub container registry.

1. Open the Code page of your repository on GitHub
2. Click on Create a new release in the Releases section on the right side
3. Enter a version (e.g. v1.0.0) and click on Publish release
   • GitHub will automatically create a tag using the version number

The provided release workflow will be triggered by the release. It creates a release documentation and publishes the container image of the Vehicle App to the GitHub container registry. A detailed description of the workflow can be found here .

How to deploy your Vehicle App?

After releasing the Vehicle App to the GitHub container registry you might ask how to bring the Vehicle App and the required runtime stack on a device. Here, Eclipse Leda comes into the game.

Please read the documentation of Eclipse Leda to get more information.

Next steps

• Tutorial: Creating a Vehicle Model
• Tutorial: Create a Vehicle App
• Tutorial: Develop and run integration tests for a Vehicle App

2 - Import examples

This guide will help you to import examples provided by the SDK package into your template repository.

A Visual Studio Code task called Import example app from SDK is available in the /.vscode/tasks.json which can replace your /app directory in your template repository with some example Vehicle Apps from the SDK package.

1. Press F1
2. Select command Tasks: Run Task
3. Select Import example app from SDK
4. Choose Continue without scanning the output
5. Select seat-adjuster

Run the Vehicle App from SDK example

The launch settings are already prepared for the VehicleApp in the template repository /.vscode/launch.json. The configuration is meant to be as generic as possible to make it possible to run all provided example apps.

Every example app comes with its own /app/AppManifest.json to see which Vehicle Services are configured and needed as a dependency.

To start the app: Just press F5 to start a debug session of the example Vehicle App.

To debug example, please check How to debug Vehicle App?

3 - Install a working container runtime

In the past the recommended runtime would for sure be Docker Desktop . But since Docker Inc. changed their license model it is fair enough for an open source project to look for free alternatives.

Linux

The obvious (and our recommended) “alternative” to Docker Desktop on Linux is to just use the Docker Engine (without Docker Desktop), a pure CLI-based solution available for most popular Linux distributions licensed under the Apache License, version 2.0. Installation instructions can be found here .

MacOS

Since the Docker Engine is not working out of the box on MacOS, a virtualizations tool which helps emulating linux is needed. Fortunately there are several solutions on the market. Good results could be achieved using Colima .

Setup Colima

Please uninstall or at least quit Docker Desktop if you already used it, before starting the setup.

For Colima to work properly you need Colima itself and a container client e.g. the Docker client, which is still free to use:

    brew install colima
    brew install docker

After the installation you need to start the runtime:

    colima start --cpu x --memory y

For M1 Macs it might be necessary to add --arch aarch64

Docker Desktop uses 5 cores and 12 GB of RAM by default on an M1 MacBook Pro. The equivalent in Colima can be achieved with

    colima start --cpu 5 --memory 12

That’s all you have to do. After these few steps you can go on with the devcontainer setup.

Microsoft Windows

There is currently no recommended alternative for Windows except using GitHub codespaces, a cloud-based development environment.

An option would be to setup a VM (e.g. with VirtualBox or VMWare) running a Linux system with Docker Engine (see above).

Other alternatives

Besides our recommendations above, there are further alternatives, which are not yet evaluated by this project or have some other drawbacks, blocking a recommendation.

For example, you could try Podman / Buildah , which can replace docker run and docker build, respectively. Podman is available for MacOS, Windows, and several Linux distributions. Buildah seems just being available for several Linux distributions.

4 - Working behind proxy

We know what a pain and how time consuming it can be to setup your environment behind a cooperate proxy. This guide will help you to set it up correctly.

Be aware that correct proxy configuration depends on the setup of your organization and of course of your personal development environment (hardware, OS, virtualization setup, …). So, we most probably do not cover all issues out there in the developers world. So, we encourage you to share hints and improvements with us.

HTTP(s) proxy server

Install and configure the proxy server as recommended or required by your company. For example you could use PX , which is a HTTP(s) proxy server that allows applications to authenticate through an NTLM or Kerberos proxy server, typically used in corporate deployments, without having to deal with the actual handshake. Px leverages Windows SSPI or single sign-on and automatically authenticates using the currently logged in Windows user account. It is also possible to run Px on Windows, Linux and MacOS without single sign-on by configuring the domain, username and password to authenticate with. (Source: PX )

• Install your HTTP(s) proxy server
• Start your HTTP(s) proxy server

Docker Desktop

You need to install Docker Desktop using the right version. As we recognized a proxy issue in Docker Desktop #12672 we strongly recommend to use a Docker Desktop version >= 4.8.2. In case you have an older version on your machine please update to the current version.

In the next step you need to enter your proxy settings:

• Open Docker Desktop and go to the Settings
• From Resources, select Proxies
• Enable Manual proxy configuration
• Enter your proxy settings, this depends on the configuration you did while setting up your proxy tool e.g.:
  • Web Server (HTTP): http://localhost:3128
  • Secure Web Server (HTTPS): http://localhost:3128
  • Bypass: localhost,127.0.0.1
• Apply & Restart.

Docker daemon

You also have to configure the Docker daemon, which is running the containers basically, to forward the proxy settings. For this you have to add the proxy configuration to the ~/.docker/config.json. Here is an example of a proper config (Port and noProxy settings might differ for your setup):

• Windows
• MacOS
• Linux

{
 "proxies":{
      "default":{
         "httpProxy":"http://host.docker.internal:3128",
         "httpsProxy":"http://host.docker.internal:3128",
         "noProxy":"host.docker.internal,localhost,127.0.0.1"
      }
   }
}

{
 "proxies":{
      "default":{
         "httpProxy":"http://host.docker.internal:3128",
         "httpsProxy":"http://host.docker.internal:3128",
         "noProxy":"host.docker.internal,localhost,127.0.0.1"
      }
   }
}

{
 "proxies":{
      "default":{
         "httpProxy":"http://172.17.0.1:3128",
         "httpsProxy":"http://172.17.0.1:3128",
         "noProxy":"host.docker.internal,localhost,127.0.0.1"
      }
   }
}

For more details see: Docker Documentation

Environment Variables

It is required to set the following environment variables:

• HTTP_PROXY - proxy server, e.g. http://localhost:3128
• HTTPS_PROXY - secure proxy server, e.g. http://localhost:3128

• Windows
• MacOS
• Linux

set
setx HTTP_PROXY "http://localhost:3128"
setx HTTPS_PROXY "http://localhost:3128"

echo "export HTTP_PROXY=http://localhost:3128" >> ~/.bash_profile
echo "export HTTPS_PROXY=http://localhost:3128" >> ~/.bash_profile
source ~/.bash_profile

echo "export HTTP_PROXY=http://localhost:3128" >> ~/.bash_profile
echo "export HTTPS_PROXY=http://localhost:3128" >> ~/.bash_profile
source ~/.bash_profile

Troubleshooting

Solving issues with TLS (SSL) certificate validation using https connections from containers

If you are behind a so-called intercept proxy (which you most probably are), you can run into certificate issues: Your corporate proxy works as a “man-in-the-middle” to be able to check the transferred data for malicious content. Means, there is a protected connection between the application in your local runtime environment and the proxy and another from the proxy to the external server your application wants to interact with.

For the authentication corporate proxies often use self-signed certificates (certificates which are not signed by a (well-known official) certificate authority. Those kind of certificates need to be added to the database of trusted certificates of your local runtime environment. This task is typically handled by the IT department of your corporation (if the OS and software installed on it is managed by them) and you will not run into problems, normally.

If it comes to executing containers, those are typically not managed by your IT department and the proxy certificate(s) is/are missing. So, you need to find a way to install those into the (dev) container you want to execute.

See (one of) those articles to get how to achieve that:

• Overcoming Proxy Issues with Docker Containers
• Docker behind SSL intercepting proxy

Initial DevContainer build issue

If you experience issues during initial DevContainer build, clean all images and volumes otherwise cache might be used:

• Open Docker Desktop
• From Troubleshooting choose Clean / Purge data

GitHub rate limit exceeded

How to fix can be found at Lifecycle Management Troubleshooting .