OAK4 `oakapp.toml` format and syntax definition

JeremyA

Is there a guide describing fields of the oakapp.toml fields?

For example, I want to know how to convert the [base_image] for other docker image registries. For example, gitlab container registries, Azure registries, or AWS registries.

This is a good example but I'm not sure how to expand this to my use cases without a guide for the meaning of each element and relate that to my situation.
luxonis/oak-examplesblob/main/apps/default-app/oakapp.toml

Ales

Try following links:

You've found a good example, it contains all [base_image] fields we support. You just need to tweak the values to fit your needs.

JeremyA

I've seen that link but it only describes that there is a [baseimage] but doesn't describe the items within it such as service, oauth_url, auth_name, etc. Additionally, I'm not using dockerhub I need the explanation of these fields so that I can find the equivalent values for these fields for other container registries.

Ales

[base_image] items are:

api_url - Service HTTPS address (example: https://registry-1.docker.io)
service - Name of a Image Registry Service (example: registry.docker.io)
oauth_url - Address to get a OAuth 2.0 token for this service (example: https://auth.docker.io/token)
auth_type - Scope type (example: “repository”).
auth_name - Name of resource (example: “library/ubuntu”)
image_name - Image name (example: “library/ubuntu”)
image_tag - Image tag (example: "latest")

Under the hood, we use the OCI registry client library. You may find a clearer explanation of what those fields mean in its documentation.

JeremyA

Does this work with only anonymous pulls like docker? Our gitlab uses authenticated access with basic credentials - a username and deploy tokens to manage access. We have to use docker login … for our pulls.

Ales

JeremyA Does this work with only anonymous pulls like docker?

yes

JeremyA

Is there any plan to allow it to work with authenticated access?

Ales

JeremyA It's on the roadmap, but we have no ETA yet for this one.

However, it's often not necessary to have a full base image; the preferred way is to use recommended base images (either luxonis/oakapp-base or debian:bookworm-slim), which should cover most use cases. Then you can build layers on top of these using prepare_container, prepare_build_container and build_steps in oakapp.toml. This way you can utilize caching effectively (e.g., by excluding build-time dependencies from the final image).

JeremyA

Ales The only problem with that is that it adds a hardware requirement if we want to build software for the OAK4 at scale in CI. It's far more convenient and robust to build the image in CI and and pull it to target.

Ales

JeremyA Authenticated Docker registry support is on the roadmap and is expected to be ready within the next few months.

We are also working on a self-hosted agent that can be used to build apps in CI/CD pipeline. Creating a full Docker image is neither necessary nor recommended, as it bypasses optimizations we provide for developer experience.

To develop an app, you currently need one camera; you run the command below repeatedly until you're happy with the result. That can be also done remotely.

oakctl app run <app_source_path>

Once your app is ready, you can build it and get *.oakapp file. In the future, this step will optionally be handled by a self-hosted agent.

oakctl app build <app_source_path>

You can install the app to other device(s) with a single command:

oakctl app install <app>

You can manage and monitor your entire device fleet through Luxonis Hub; you can find there some example apps, upload/update your own.

Ales

@JeremyA could you describe your situation in more detail? Please contact support@luxonis.com and ask them to include me in the conversation.

We are currently in the testing phase of the self-hosted agent. If your use case is a good fit, it may make sense to include you in the pilot.

JeremyA

I think what you're saying is what has been repeated in examples where we actually build code using oakctl app build. Does that require a camera connection to build or could it be done in CI? How do we manage oakctl app build's outputs for other camera deployments? My concern is that this process would require camera hardware to build, does not scale well (build per camera?), and may accidentally include small changes that affect the output from run to run. It also doesn't include best practice CI automated tests that is key to good software development.

I may be missing the point but it looks like this is good tooling for prototyping but not for production level outputs. This is why I am pursuing a CI process that would build a docker image FROM the recommended base images for C++ code (better optimized than python) while still using oakctl to deploy those images.

Ales

Does that require a camera connection to build or could it be done in CI?

We can provide you an early access self-hosted agent that can be run in CI. However, it's better to have a physical device. The output from one device can be used in any other RVC4 device.

How do we manage oakctl app build's outputs for other camera deployments?

A build output (*.oakapp file) can be deployed to as many devices as you want. Imagine it as an Android app. One .apk can be used on thousands of phones.

My concern is that this process would require camera hardware to build, does not scale well (build per camera?)

No, you build once and use just the output.

This is why I am pursuing a CI process that would build a docker image FROM the recommended base images for C++ code (better optimized than python) while still using oakctl to deploy those images.

An app is not just an image, *.oakapp contains metadata that allow us to bring you more features (management apps in Hub, static frontend, etc.).

Reminding that improved [base_image] feature will come within a few months. It is planned.