Custom Docker Containers

We support custom Docker containers to run your service. You may consider using "Docker" as your service runtime in the following scenarios:

• You need OS-level packages not included in the Python Template. With Docker, you have complete control over your base operating system and installed packages.
• Your application is in a language not yet supported by PLANQK, like Go or Rust.
• You need guaranteed reproducible builds. We release regular updates to our coding templates to improve functionality, security, and performance. While we aim for full backward compatibility, using a Dockerfile is the best way to ensure that your production runtime is always in sync with your local builds.

Compliance with our runtime interface is required

You cannot run an arbitrary Docker container. You must comply with our runtime interface.

Set up a Custom Docker Container Project

You can use the PLANQK CLI to bootstrap a custom Docker Container project. Just run planqk init and select Docker Starter as the type of starter project. Alternatively, you can create a new project manually by following the project layout of the planqk-starter-docker repository.

A starting folder structure of your project could look like this:

.
├── Dockerfile
├── openapi.yaml
├── input
│   └── ...
└── src
    └── ...

It is important that there is a file called Dockerfile in the root directory of the project. The Dockerfile is the file that defines the Docker image that will be built by PLANQK.

Optionally, you can provide a file called openapi.yaml in the root directory of the project. This file defines the API of your service (more information).

The input folder may contain the input data and parameters to test your application locally.

The src folder contains any source code required to run your application. You may extend this structure depending on your needs.

Build, Run, and Test your Project

Build the Docker container:

docker build -t your-app .

You can use the input directory to provide respective input files for testing. Remember to provide input files according to your expected JSON input structure. For example, if you expect your users to execute your service with the input { "data": { ... } }, you should test with the file data.json.

By using the command below, any output written to /var/runtime/output will be available in the out directory after the container has finished running.

For more information on how to deal with input and output data, see our runtime interface documentation for custom Docker containers.

Run the Docker container:

PROJECT_ROOT=(`pwd`)
rm -rf $PROJECT_ROOT/out
docker run -it \
  -v $PROJECT_ROOT/input:/var/runtime/input \
  -v $PROJECT_ROOT/out:/var/runtime/output \
  your-app

Windows Users

For GitBash users on Windows, replace

PROJECT_ROOT=(`pwd`)

with

PROJECT_ROOT=(/`pwd`)

For Windows command-prompt users, you can define the volume mounts using -v %cd%/input:/var/runtime/input and -v %cd%/out:/var/runtime/output.

What's next?

• Learn how to describe your Service API using OpenAPI Specification v3.0.
• Deploy your service using our CLI or web application.