Open Delivery Gear - Core

This repository is the home of the core API and feature extensions for the Open Delivery Gear.

Index

• Technology
• Getting Started
  • Standalone
  • Kubernetes in Docker
• Documentation
• Packages

Technology

The core API implements a Python HTTP web server, intended for deployment into a Kubernetes cluster. It features compliance-related automation for software built with the Open Component Model.

Getting Started

There are multiple ways to run ODG-Core locally.

Standalone

The ODG-Core Python HTTP web server can be started locally as a standalone application. It is loosely coupled to the database and Kubernetes-specific components, therefore this option is considered best if you intend to run web server-only features (e.g. adding new endpoints).

Dependencies and Setup

First, you need to prepare your local environment. Install uv (e.g. brew install uv), then run:

make setup

This creates a project-local .venv with all dependencies pinned from uv.lock. Afterwards you can either prefix commands with uv run (e.g. uv run pytest) or activate the venv manually.

Common Makefile targets:

Target	Description
make setup	Create/update .venv from lock file
make run-db	Start a local PostgreSQL instance
make run	Start the development server
make test	Run the test suite
make lint	Run ruff and bandit
make format	Check code formatting
make build-core	Build the odg-core-libs wheel
make build-clients	Build bdba-client and odg-client wheels
make build-docker-local	Build the OCI image for your local architecture
make build-docker	Build the OCI image for all supported architectures
make clean	Remove build artifacts

Running the Web Server

The Makefile features a convenient command to run the ODG-Core web server in a lightweight fashion. This naturally has limitations, as most features will be turned off. If you want to run specific features, please review the Makefile and build your custom run command.

make run

Kubernetes in Docker

To run the ODG-Core web server alongside dependencies and feature extensions, you need to deploy it to a Kubernetes environment. You can use Kubernetes-in-Docker (KinD) to deploy such a setup locally.

Please refer to this guide to deploy ODG to KinD.

Dev Container

You can also develop ODG in a Dev Container. Install the Dev Containers extension and choose Reopen in Container in VS Code.

The Dev Container provides:

• Run & debug:
  • To run the core service, run Debug: core service
  • To run an extension, run Debug: extension and select the extension
• Pytest integration
• PostgreSQL browser (password: MyPassword, see .devcontainer/compose.yml)
• Auto-format & lint on save

To work with a KinD cluster:

1. Create the KinD cluster on the host: kind create cluster --config .devcontainer/kind-config.yml, which includes host.docker.internal as SAN
2. Flatten your kubeconfig into ~/.kube/config: kubectl config view --flatten > ~/.kube/config
3. Open the Dev Container (Reopen in Container in VS Code)
4. Open a terminal session. The kubeconfig is refreshed on every shell startup, with 127.0.0.1 replaced by host.docker.internal
5. Copy the extensions config: cp extensions_cfg.yaml extensions_cfg.local.yaml
6. Adjust the local configuration and secrets to your needs

To clean up the KinD cluster: kind delete clusters odg-devcontainer-cluster

Documentation

The documentation is hosted here.

Quicklinks

• Architecture Overview
• Onboarding Journey
• Reference Documentation

Open-API Specification

Additionally, each ODG-Core instance hosts an Open-API specification. It is available at: https://<odg-core>/api/v1/doc/

You can also checkout the documentation hosted by the public demo instance, but please be aware that the running version might differ from your installation.

-> Public ODG Demo Open-API

Packages

ODG-Core publishes multiple software artefacts. This list provides an overview.

Name	Type	Description	Location
odg-core-libs	Python Package	Core APIs and functionalities. Contains the ODG web server.	PyPi
odg-client	Python Package	Python HTTP client library to interact with the ODG-Core API	PyPi
bdba-client	Python Package	Python HTTP client library to interact with BlackDuck Binary Analysis	PyPi
odg-core	OCI Image	Filesystem to run ODG-Core and ODG extensions in cloud environments	GCP
odg-core	OCM Component	Software component referencing all delivery artefacts and metadata	OCM Repo

---