Executables With a Docker Backend

The Docker backend allows you to create executables that use a Docker container to run your script in, along with any dependencies it might need.

Executables with a Docker backend make it easy to adhere to strict version requirements as well as simplifying the management of dependencies.

Running Docker executables

Running a component

Use the viash run command to run a component with a Docker backend directly:

viash run -p docker config.vsh.yaml --setup ifneedbecachedbuild -- --input "Hello!"

Note: If you make changes to the platform section of your config file, you will need to run --setup again.

Building and running an executable

To build an executable, use the viash build command:

viash build config.vsh.yaml -p docker --setup alwayscachedbuild

You can then simply run the generated executable:

output/my_executable --input "Hello!"

Doing this will perform checks and actions according to the selected setup strategy after which the script is run inside the Docker image.

Pass the hidden ---dockerfile argument to a component or executable with a Docker backend to get an overview of the Docker configuration. For example:

viash run -p docker config.vsh.yaml -- ---dockerfile

Another example:

./my_docker_executable ---dockerfile

Both of these output something similar to this to the terminal:

FROM bash:latest

RUN apk add --no-cache curl

Automatic Docker volume creation

Viash automatically creates a Docker volume for components and executables with a Docker backend if an argument of the type file exists in the config file.
This allows your script to read and write files as if it were working with them natively.
The full mount name is /viash_automount/ABSOLUTE_PATH_TO_FILE_DIRECTORY.

You can see this in action by following along any of the component creation guides in the CREATING VIASH COMPONENTS category on the left. The md_url_checker component prints the paths to the input and output files to the console.
When executing this command on the final Docker executable:

output/md_url_checker --inputfile Testfile.md

These lines will be printed to the terminal along with the other output:

...
/viash_automount/home/user/md_url_checker/Testfile.md has been checked and a report named /viash_automount/home/user/md_url_checker/output.txt has been generated.
...

As you can see, /viash_automount/ is added before the path to the files so Docker can read and write to both files.

By default, files created and modified by a Docker container are owned by root. Viash automatically changes the owner of any files defined in the config file to the user running the component or executable by default.

Note: Any other files your script generates will still be owned by root as Viash won’t have any knowledge of them.

Docker setup strategies

Viash supports the use of several different Docker setup strategies. You can choose what strategy to build a component with when using a Docker backend by passing the --setup option followed by one of the strategies below.
For example:

viash build config.vsh.yaml -p docker --setup alwayscachedbuild

Build

  • alwaysbuild / build / b: Always build the image from the dockerfile. This is the default setup strategy.
  • alwayscachedbuild / cachedbuild / cb: Always build the image from the dockerfile, with caching enabled.
  • ifneedbebuild: Build the image if it does not exist locally.
  • ifneedbecachedbuild: Build the image with caching enabled if it does not exist locally.

Pull

  • alwayspull / pull / p: Try to pull the container from Docker Hub or the specified docker registry.
  • alwayspullelsebuild / pullelsebuild: Try to pull the image from a registry and build it if it doesn’t exist.
  • alwayspullelsecachedbuild / pullelsecachedbuild: Try to pull the image from a registry and build it with caching if it doesn’t exist.
  • ifneedbepull: If the image does not exist locally, pull the image.
  • ifneedbepullelsebuild If the image does not exist locally, pull the image. If the image does exist, build it.
  • ifneedbepullelsecachedbuild: If the image does not exist locally, pull the image. If the image does exist, build it with caching enabled.

Push

Do nothing

  • donothing / meh: Do not build or pull anything.
← Frequently Asked Questions
Contributing Guidelines →