Installing bulker

Install from GitHub releases or from PyPI using pip:

  • pip install --user bulker: install into user space.
  • pip install --user --upgrade bulker: update in user space.
  • pip install bulker: install into an active virtual environment.
  • pip install --upgrade bulker: update in virtual environment.

See if your install worked by calling bulker -h on the command line. If the bulker executable in not in your $PATH, append this to your .bashrc or .profile (or .bash_profile on macOS):

export PATH=~/.local/bin:$PATH

Initializing a bulker configuration file

On a fresh install, bulker comes with a locally installed config file, which you can explore by typing bulker list. If you want a group-shared bulker config, or if you want to change the volumes, environment variables, or container engine, you will need to configure bulker. Start by initializing an empty bulker config file:

export BULKERCFG="bulker_config.yaml"
bulker init -c $BULKERCFG
Guessing container engine is docker.
Wrote new configuration file: bulker_config.yaml

This init command will create a default config file. It guesses if your system is set up to use docker or singularity. You can use -e docker or -e singularity to force it.

The bulker activate, load, and list commands require knowing where this config file is. You can pass it on the command line all the time (using the -c parameter), but this gets old. An alternative is to set up the $BULKERCFG environment variable. Bulker will automatically use the config file in this environmental variable if it exists. Add this line to your .bashrc or .profile if you want it to persist for future command-line sessions:

export BULKERCFG=/path/to/bulker_config.yaml

You can always specify -c if you want to override the value in the $BULKERCFG variable on an ad-hoc basis.

Configuring bulker

The bulker config file is where you put the container settings that will determine how your executables behave.

Example configuration file

Below you can find the details, but first, take a look at the config file to see what you can modify:

cat $BULKERCFG
bulker:
  volumes: ['/tmp']
  envvars: ['DISPLAY']
  default_crate_folder: ${HOME}/bulker_crates
  singularity_image_folder: ${HOME}/simages
  container_engine: docker
  default_namespace: bulker
  executable_template: templates/docker_executable.jinja2
  shell_template: templates/docker_shell.jinja2
  build_template: templates/docker_build.jinja2
  crates: null

File systems (volumes)

One of the first things you'll want to do to make bulker fit your host environment is add any file systems. By default, containers are isolated from the host file system. If you're using bulker to create drop-in replacements to your native tools, though, you probably want these tools to have access to the same file systems that a native tool would.

The volumes section in the bulker config file is where you specify what file systems you want mounted on your containers. Anything you put here will automatically be mounted on all your containers. By default, the config file will say:

bulker:
  volumes: ['$HOME', '/tmp']

This will make sure all your containers can see anything in $HOME or on /tmp. Add any others you require.

Environment variables

The other major host-specific information you'll need to add to your config file is the list of environment variables you want available within your containers. You should add these under envvars.

Other config options

The default_crate_folder will determine where the crates (folders with executables) are saved. The crates section is maintained by bulker -- it will add a new entry into this section whenever you run bulker load, and this is what it reads when you request bulker list or bulker activate.

You can also adjust the default_namespace to make it easier for you to load your own crates.

You can change the registry_url to point to a different bulker registry.