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.
Print Docker configuration to terminal
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
push
: Push the container to Docker Hub or the specified docker registry.pushifnotpresent
Push the container to Docker Hub or the specified docker registry if the specified tag) does not exist yet.
Do nothing
donothing
/meh
: Do not build or pull anything.