Welcome to wharfrat’s documentation!

Introduction

wharfrat is intended to make it easy and convenient to use a development environment in a docker container. The benefits of this are:

  • Simple: A new development environment is setup with a single simple command, meaning new team members are ready to go immediately.
  • Shared: Everyone with access to the project (and docker) has access to the development environment.
  • Controlled: Everyone gets a development environment created from the same image - no more “works for me” issues.
  • Versioned: The configuration is version controlled, meaning you get the development environment that matches the code branch you are working on.

Installation

…

Basic Usage

…

Configuration

Crate Configuration

The table below lists the settings available for each crate, their types and default values (if the default is not empty):

cap-add array of strings capabilities to enable for the container
cap-drop array of strings capabilities to disable for the container
copy-groups array of strings groups to copy from the host to the container
env table of strings mapping from environment variable name to value
env-blacklist array of strings host environment variables to drop
env-whitelist array of strings host environment variables to keep
groups array of strings groups the user should be in
hostname string hostname for container (default: “dev”)
image string name of image to create container from
mount-home bool should /home be mounted into container (default: true)
ports array of strings ports to be exposed from container (-p option to docker)
project-mount string path to mount project in container
setup-post string script to run in container after unpacking tarballs
setup-pre string script to run in container before running tarballs
setup-prep string script to run locally before the other setup
shell string shell to use in the container
tarballs table of strings mapping from tarball location to install location
tmpfs array of strings paths in the container where tmpfs should be mounted
volumes array of strings list of volume mounts (-v option to docker)
working-dir string method to use to set working dir (default: “match”)
cap-add:

Add additional Linux capabilities to the container. The list of possible values can be found in the docker run reference (https://docs.docker.com/engine/reference/run/#runtime-privilege-and-linux-capabilities).

For example to add the ability to use ptrace inside the container:

cap-add = ["SYS_PTRACE"]
cap-drop:

Drop normally enabled Linux capabilities from the container. The list of possible values can be found in the docker run reference (https://docs.docker.com/engine/reference/run/#runtime-privilege-and-linux-capabilities).

For example to drop the ability to bind to privileged ports:

cap-drop = ["NET_BIND_SERVICE."]
copy-groups:

TODO …
env:

Specify environment variables to be set in the container. This consists of a table, where the keys are the variable names and the values are the variable values. For example to set SOME_VARIABLE to “some value”:

[crates.demo.env]
    "SOME_VARIABLE" = "some value"

Local Configuration

In addition to the shared project configuration each user can have a local configuration. This configuration allows changing the Docker URL, and adding extra steps to the container setup.

On Linux this file can be found at “$XDG_CONFIG_HOME/wharfrat/config.toml”. If $XDG_CONFIG_HOME is not set, then the default path is “$HOME/.config”, so the default location for the config is “$HOME/.config/wharfrat/config.toml”.

docker-url = "file:///var/run/docker.sock"
auto-clean = true

[[setups]]
    project = ".*/test"
    setup-prep = """
        echo "LOCAL PREP: $*"
        pwd
    """

    setup-pre = """
        echo "LOCAL PRE"
        pwd
    """

    setup-post = """
        echo "LOCAL POST"
    """

    [setups.tarballs]
        "path/to/tarball.tgz" = "/path/in/container/to/unpack"

    [setups.env]
        "LOCAL_CRATE_ENV" = "true"

[[setups]]
    setup-prep = """
        echo "LOCAL PREP: $*"
        pwd
    """

    setup-pre = """
        echo "LOCAL PRE"
        pwd
    """

    setup-post = """
        echo "LOCAL POST"
    """

    [setups.env]
        "LOCAL_CRATE_ENV" = "true"

The available settings are:

docker-url The URL to use to connect to Docker
auto-clean If set to true, then wharfrat run will automatically replace containers that were built from old config, or the wrong image.
setups project a regular expression that much match the project path for this setup to be applies. If not specified, then “.*” is used.
crate a regular expression that must match the crate name for this setup to be applied. If not specified, then “.*” is used.
setup-prep script to run locally before doing anything else
setup-pre script to run remotely before unpacking tarballs
setup-post script to run remotely after unpacking tarballs
tarballs a table to tarballs to be unpacked into the container, mapping tarball path to target path in the container
env a table of environment variables to set in the container, mapping name to value

Accessing Containers

Exposing Commands

It is possible to use the wr-exec command to expose commands from inside a container to the host. This is normally done by creating an executable config file with a #! line that invokes wr-exec. For example, if ./test contains:

#!/usr/bin/env wr-exec

project = "/path/to/project/file"
command = ["command", "arg1"]

Then, running ./test arg2 will run the command command arg1 arg2 in the container for the default crate defined in the wharfrat project file at /path/to/project/file.

Environments

Purpose

Environments are a convienient way to access a set of executables from the host system as if they are on the host.

They are based on approach taken by tools such as virtualenv, where the path is modified to inject executables from the environment earlier into the search path.

Creating an Environment

There are two parts to creating an environment:

  • Setting up one or more crates to export binaries
  • Creating the actual environment files

The first part is typically done once as part of the project configuration, and checked in. The second is done by each person that wishes to use an environment with that project.

Exporting Binaries

To export binaries from a crate into an environment the export-bin crate setting. This setting consists of a list of patterns, and any executable that matches any of these patterns will be exported into the environment.

Creating the Environment Files

The files for the environment are created using the wharfrat env create command. This command takes the path at which to create the environment. You can also optionally select a subset of the crates in the project that should be used to create the environment (the default being all crates in the project).

Using an Environment

Once an environment has been created, then is must be activated to be used. Activating the environment will change the shell’s PATH such that the exported binaries are first in the search path.

In addition to the binaries exported from the crates, the environment includes a cached copy of the wharfrat binary that was used to create the environment.

Once an environment has been activated, any new exported binaries will be noted against the commands that caused them to appear. This allows the commands to be re-run when the create has to be recreated (which is done automatically when running an exported command by default).

~/proj# wharfrat env create wrenv
~/proj# . wrenv/bin/activate
(wr: wrenv) ~/proj#

Examples

…

Indices and tables