Running Native Executables

Viash lets you turn your component into a native executable.

Native components are a good way to get started with Viash and are ideal to test out your components before using the more sophisticated platforms like Docker and Nextflow.

Running native executables

Running a native component

Use the viash run command to run a native component directly:

viash run -p native config.vsh.yaml -- --input "Hello!"

Building and running a native executable

To build an executable, use the viash build command:

viash build config.vsh.yaml -p native

You can then simply run the generated executable:

output/my_executable --input "Hello!"

Migrating from native to Docker

Once you’re content with your native executable, you might want to take it a step further and use it with a Docker backend instead. This has a few strong advantages over running native components:

  • Executables with a Docker backend are portable. All they require are an install of Docker on the target system, nothing more.
  • Dependencies are automatically resolved by Viash if you provide some information in the config file.
  • You can use specific versions of software packages without having to worry about conflicts with a target system’s setup.

Let’s say you have a bash script that uses curl to download some data, process it using and then post it to a web server. When you create a native component for this script, everything will work fine as long as you have curl installed locally on your machine.
In order to get everything working with a Docker backend, you need to follow a few simple steps:

If you’re only using the native platform, the platforms section of your your config file will probably look like this:

platforms:
  - type: native

Start off by adding the docker platform and a suitable image to the platforms dictionary. In this case, since you’re using a bash script, you might want to use the official bash image. Replace your existing platforms section with the following:

platforms:
  - type: native
  - type: docker
    image: bash:latest

At this point you can build and execute the component with a Docker backend already! Viash will do all the rest. However, if you have any dependencies outside of bash, your script will fail to execute correctly inside of the container.
To remedy this, Viash allows you to provide the dependencies inside of the config file and they will automatically be resolved at runtime. To add curl as a dependency, expand your platforms definition like so:

platforms:
  - type: native
  - type: docker
    image: bash:latest
    setup:
      - type: apk
        packages: [ curl ]

In this case, curl is available via the Alpine Package Keeper (APK for short). There are many more ways of adding dependencies for every language Viash supports and more are being added periodically.
Now build your component using this command:

viash build config.vsh.yaml -p docker

Finally, run the built executable with:

output/name_of_your_component

That’s it! In just a few steps you’ve made your script ready to be used on any system that has Docker installed. That includes linux, macOS and Windows via WSL2.

← Creating a Nextflow Data Pipeline
Frequently Asked Questions →