Docker

Viash can generate a Docker image and final container for you based on a component. This guide explains how to adapt a component that targets the native platform to work with a Docker backend.

Requirements

As this example targets the Docker platform, the only requirement is to have Docker installed on your system. This is one of the biggest benefits of targeting the Docker platform. You can find instructions on how to install Docker for your OS on the Viash installation page.

Preparing a component for Docker

Creating a component

For this example, you’ll use the same hello_world component the native component creation guide uses. You can either follow with that guide first or simply download the component below that contains the component in all supported languages. Simply rename the language folder you want to use to hello_world and use that as your working directory.

Download hello_world.zip

Adjusting the config

All you need to do to add the Docker platform as a build target is adding docker to the platforms list in your Viash config file. The docker platform has an image property that points to a Docker image from Docker Hub to use as a base.

Depending on the scripting language you’re using, a setup section might be included that will install additional packages in the final image.

Add this snippet to the bottom of your config file to add Docker as a build target and add a bash base image:

- type: docker
  image: bash:4.0

Here’s the full config after making this change:

Download config.vsh.yaml

functionality:
  name: hello_world
  description: A minimal example component.
  arguments:
  - type: string
    name: --input
    default: "World"
  resources:
  - type: bash_script
    path: script.sh
platforms:
  - type: native
  - type: docker
    image: bash:4.0

Add this snippet to the bottom of your config file to add Docker as a build target and our dotnet-script base image:

- type: docker
  image: "dataintuitive/dotnet-script:1.2.1"
  setup:
    - type: apk
      packages: [ bash ]

Here’s the full config after making this change:

Download config.vsh.yaml

functionality:
  name: hello_world
  description: A minimal example component.
  arguments:
  - type: string
    name: --input
    default: "World"
  resources:
  - type: csharp_script
    path: script.csx
platforms:
  - type: native
  - type: docker
    image: "dataintuitive/dotnet-script:1.2.1"
    setup:
      - type: apk
        packages: [ bash ]

Add this snippet to the bottom of your config file to add Docker as a build target and a Node.js base image:

- type: docker
  image: node:15-buster

Here’s the full config after making this change:

Download config.vsh.yaml

functionality:
  name: hello_world
  description: A minimal example component.
  arguments:
  - type: string
    name: --input
    default: "World"
  resources:
  - type: javascript_script
    path: script.js
platforms:
  - type: native
  - type: docker
    image: node:15-buster

Add this snippet to the bottom of your config file to add Docker as a build target and a Python base image:

- type: docker
  image: "python:3.8"

Here’s the full config after making this change:

Download config.vsh.yaml

functionality:
  name: hello_world
  description: A minimal example component.
  arguments:
  - type: string
    name: --input
    default: "World"
  resources:
  - type: python_script
    path: script.py
platforms:
  - type: native
  - type: docker
    image: "python:3.8"

Add this snippet to the bottom of your config file to add Docker as a build target and a base image containing Scala and sbt:

- type: docker
  image: hseeberger/scala-sbt

Here’s the full config after making this change:

Download config.vsh.yaml

functionality:
  name: hello_world
  description: A minimal example component.
  arguments:
  - type: string
    name: --input
    default: "World"
  resources:
  - type: scala_script
    path: script.scala
platforms:
  - type: native
  - type: docker
    image: hseeberger/scala-sbt

Add this snippet to the bottom of your config file to add Docker as a build target and a base image containing R, rstudio and R packages:

- type: docker
  image: "rocker/tidyverse:4.0.4"

Here’s the full config after making this change:

Download config.vsh.yaml

functionality:
  name: hello_world
  description: A minimal example component.
  arguments:
  - type: string
    name: --input
    default: "World"
  resources:
  - type: r_script
    path: script.R
platforms:
  - type: native
  - type: docker
    image: "rocker/tidyverse:4.0.4"

Note

When building your own components that only target Docker or Nextflow, adding the native target platform isn’t necessary.

Running

You can now call upon Viash to generate a temporary executable and run it:

viash run config.vsh.yaml --platform docker

The --platform argument is passed to viash run so Docker will be chosen as the build target. If the platform isn’t specified, the first one in the platforms list is picked.
This results in the following output:

[notice] Checking if Docker image is available at 'hello_world:latest'
[warning] Could not pull from 'hello_world:latest'. Docker image doesn't exist or is not accessible.
[notice] Building container 'hello_world:latest' with Dockerfile
Hello World

As you can see, Viash checks first if an image has been generated before continuing. If the image already exists, Viash will run a contained based on the image.
In this case though, no image was found for this component, so Viash generates the image before building and running the container.

What’s next?

To learn how to use Viash to build an executable with a Docker backend and run it, see Building and Running.