---
url: /services/managed/custom-containers.md
description: >-
  Package a Managed Service as a custom Docker container to bring your own OS
  packages, languages, or reproducible builds to Kipu Quantum Hub.
---

# 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 the platform, 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.

> \[!WARNING] Compliance with our runtime interface is required
> You cannot run an arbitrary Docker container.
> You must comply with our [runtime interface](runtime-interface#docker).

## Set up a Custom Docker Container Project

You can use the CLI to bootstrap a custom Docker Container project.
Just run `qhubctl 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 [starter-docker](https://dashboard.hub.kipu-quantum.com/community/implementations/a5b16c2a-cf23-49b0-8d1c-e1444c2816ef) 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 the platform.

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](openapi)).

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:

```shell
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](runtime-interface#docker).

Run the Docker container:

```shell
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
```

::: tip Windows Users
For GitBash users on Windows, replace

```bash
PROJECT_ROOT=(`pwd`)
```

with

```bash
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](openapi).
* [Deploy your service](introduction.md#create-a-managed-service) using our CLI or web application.