DENV(1) User Manual DENV(1)
NAME
denv config
SYNOPSIS
denv config [help|-h|–help]
denv config print [env]
denv config image <pull | IMAGE>
denv config mounts DIR0 [DIR1 DIR2 ...]
denv config shell SHELL
denv config network {[yes|on|true]|[no|off|false]}
denv config env [help|-h|–help]
denv config env print
denv config env all [yes|no]
denv config env copy VAR0[=VAL0] [VAR1[=VAL1] ...]
DESCRIPTION
Manipulate the configuration of a denv that already exists. The com‐
mands here will all fail if a denv hasn’t been created, see denv-
init(1) to create a new denv.
denv config is separated into a set of sub-commands that are focused on
manipulating the different aspects of the denv configuration. These
correspond to the different keywords specified after `config'.
COMMANDS
help print a help message for denv config. This is the command that is
issued if no keywords are given. It also has the aliases -h and
--help.
print print the loaded denv configuration. This is helpful for debug‐
ging purposes and inspecting the denv that you currently have config‐
ured.
image set (and potentially pull) the container image that should be
used with the denv that you currently reside in.
mounts provide additional directories to mount into the denv during
running.
shell set the shell that should be executed by denv if no other command
is given by the user.
network enable network connection for the denv (passing yes, on, or
true) or disable this network connection (passing no, off, or false).
env manipulate and view the environment variables that will be provided
to the denv at run time.
ARGUMENTS
Below are different arguments that can be provided separated by which
command they correspond to.
print
env If any argument is provided to print, then all of the environment
variables that will be passed into the denv are printed after the de‐
duced configuration. Without an argument, print will just show the de‐
duced configuration and only print the environment variables if copy-
all is false.
image
IMAGE The provided argument is the image tag that should be used for
running with the denv. If this argument is the special key-word
`pull', then it won’t change the actual image tag and instead re-down‐
load the currently configured image from the registry.
For apptainer and singularity runners, this IMAGE can also be a
filesystem path to a unpacked image that is already downloaded (and un‐
packed) somewhere else on the computer. In this case, we simply sym‐
link the image to our image cache so denv can operate like normal.
Work is on-going to investigate supporting this workflow for other con‐
tainer runners <https://github.com/tomeichlersmith/denv/issues/37>.
mounts
DIR Each of the space-separate arguments are interpreted as a directory
that should be included in the list of mounts for the container that
denv spawns. These are in addition to the mount of the denv workspace
to the container home directory. They are mounted into the container
at the same filesystem location that they have on the host. These di‐
rectories are required to be full paths so that the user is cognizant
of what paths will be available in the container and what arent. One
can use realpath(1) to deduce a fullpath from a relative path in a
POSIX-compliant way if desired.
shell
SHELL the program to use as the interactive shell within the container‐
ized environment. No checks on what this program is or if it is even
available within the container are done. As the name implies, denv ex‐
pects it to be some shell that the user can interact with but techni‐
cally it is just the default program that is run when the user does not
provide any arguments to denv.
env
The env subcommand has its own sub-commands due to the variability of
defining which environment variables should be copied into the con‐
tainerized environment.
help print a help message for this subcommand. This has aliases -h and
--help as well.
print print out the environment variables and their values that will be
passed into the container.
all toggle the decision on if all possible environment variables from
the host environment should be copied. yes, true, on all mean to copy
all possible variables from the host environment, while their inverses
no, false, off mean to disable this feature and only copy variables
that are explicitly defined via the copy command below. Variables de‐
fined with a specific value overwrite any values that would be copied
from the environment.
copy configure which environment variables to copy into the denv at
runtime. Each of the space-separated arguments to this command are
treated separated and are interpreted as a VAR with an optional VAL
distinguished by a `=' character.
• VAR environment variable name either in the host environment that
should be copied into the denv (if no value is specified with an `='
sign) or defined to a specific value (when a value is specified with
an `=' sign). These names cannot match special shell environment
names (e.g. `HOME') or special denv names (e.g. `DENV_RUNNER').
• VAL environment variable value to use instead of the value from the
host environment. These values cannot have the special characters:
space ' ', tick '`', quote '"', or dollar-sign '$'. Providing a val‐
ue for a specific environment variable means that variable does not
need to exist in the host environment. Moreover, providing a value
takes precedence: if a value is provided, the denv will receive that
value, ignoring any value that may exist in the environment (even if
all is toggled to on and all environment variables are being copied).
EXAMPLES
Print out the current configuration of the denv.
denv config print
Change the image that the denv should use when running. Be careful. No
cleaning or checking of compatibility is done. A drastic enough change
in the image may require recompilations or even re-writes of code being
written and developed within the denv.
denv config image my-repo/my-image:new-tag
Pull down the image that is currenlty configured again. This is help‐
ful if the denv is using an image tag like “latest” and should be up‐
dated to the latest release again. Updating to the latest release is
not done automatically because of the warnings above.
denv config image pull
Sharing Environment Variables
The syntax for sharing environment variables with the denv is a bit
terse, so it is helpful to display some examples.
By default (without --no-copy-all or --clean-env when running denv
init), denv will copy all possible environment variables from the host
into the denv. This means one can
export foo=bar
printenv foo # prints out "bar"
denv printenv foo # also prints "bar"
In some situations, this is over-sharing and you can disable this so
that host environment variables are not copied into the denv anymore.
denv config env all no
export foo=bar
printenv foo # prints out "bar"
denv printenv foo # does not print anything and returns the error code 1
Even with copying all environment variables disabled, one can still
copy specific values from the host or set specific variables to have
specific values for the denv.
denv config env copy baz myfoo=mybaz
denv printenv myfoo # prints "mybaz"
printenv myfoo # does not print anything and returns error code 1
denv printenv baz # not set in host yet so does not print anything
export baz="hooray"
denv printenv baz # prints "hooray"
FILES
The denv config command is used to safely edit the .denv/config file so
that the user does not accidentally break their configuration. Never‐
theless, this file is a regular text file and so can be edited directly
if the user wishes to do something more advanced that the basic com‐
mands described above can handle.
The config file is a basic key=value shell file that will be sourced by
denv whenever the configuration is needed. denv assumes that this con‐
fig file defines the following shell variables for it to use.
denv_name the name for this denv
denv_image the image to use when running the denv
denv_shell the program to run as a interactive shell if running denv
without any arguments
denv_mounts a space separated list of extra mounts to mount into denv
when running
denv_env_var_copy_all a boolean flag signalling if denv should copy all
possible host environment variables into the denv ("true") or not
("false").
denv_env_var_copy a space-separated list of host environment variables
to copy into the denv. This is ignored if denv_env_var_copy_all is
"true". There are some restrictions on the names of variables that can
be used and so editing this value directly is not recomended. Use denv
config env copy which does this validation.
denv_env_var_set a space-separate list of key=value pairs that will be
set as environment variables within the denv. These values override
any values that could be copied from the host. There are restrictions
on the names and values that can be kept here so editing this value di‐
rectly is not recommended. Use denv config env copy to edit this value
while validating that the rules are followed.
denv_network a boolean flag signalling if denv should connect the con‐
tainer to the host network ("true") or disable all network connection
("false").
Since denv v1, this configuration is considered stable. Any new con‐
figuration options that are desirable to introduce new features will be
optional and thus are not required to reside within this file.
SEE ALSO
denv(1), denv-init(1), denv-check(1)
denv Aug 2024 DENV(1)