Node Packaged Masterfully

    @magland/epoxy

    0.1.11 • Public • Published

    epoxy

    Sort of like binder, sort of like repo2docker.

    What does it do?

    Epoxy can be used in two ways.

    In the first usage, much like repo2docker, it takes as input a repository or local source directory and builds and runs a docker container with environment inferred from the contents of the repository. It then opens a jupyterlab or other interactive session to interact with the source code. Unlike repo2docker, if the input is a directory on the local machine, the directory can be mounted in the container and therefore the source files can be edited both inside and outside the container.

    In the second usage, much like binder, it is a web server that provides, on demand, the same live, interactive session in a web browser without installing any software locally.

    Prerequisites

    • docker, and make sure your user is in the docker group
    • nodejs -- a recent version
    • If you are going to use this with local directories as described below, you will want to configure docker to map the container's root user to the host's non-root user. See below.

    Installation

    git clone git@github.com:magland/epoxy.git
    cd epoxy
    npm install
    

    Example usage

    Launch an interactive jupyter session for a remote git repository:

    epoxy-jupyterlab https://github.com/flatironinstitute/mountainsort_examples
    

    (Note that you may need to refresh the browser page after the new tab is created)

    Launch an interactive jupyter session for a local directory:

    epoxy-jupyterlab /home/magland/src/mountainsort_examples
    

    Note: when using a local directory you will almost certainly want the container to correspond to your non-root user on the host. To configure docker to do this, see the relevant section below.

    You can also launch other types of interactive sessions such as bash:

    epoxy-bash https://github.com/flatironinstitute/mountainsort_examples
    

    Notes

    Right now, epoxy expects the following two files in the repository:

    environment.yml
    postBuild
    

    Ultimately it will support the other ways of specifying the environment (used by repo2docker and binder).

    Mapping the docker root user to the host's non-root user

    You will probably want the docker container to act as your non-root user when it modifies files in the workspace. This requires a special docker configuration on your local machine. The following instructions are based on this excellent guide: https://blog.yadutaf.fr/2016/04/14/docker-for-your-users-introducing-user-namespace/

    You'll need to know your user name and uid. These can be obtained via:

    echo $USER
    echo $UID
    

    Suppose your user name is [user] and your uid is [uid].

    Do the following:

    cat /etc/subuid
    

    You should see something like

    [user]:165536:65536
    

    where [user] is your user name. Depending on the other users on the system, the 165536 might be a different number -- that's okay. Now edit this file

    sudo nano /etc/subuid
    

    You will need to insert a line before the entry and decrement the final 65536 by 1 to get 65535. So in the above example you would get

    [user]:[uid]:1
    [user]:165536:65535
    

    Now do the same thing for /etc/subgid:

    sudo nano /etc/subgid
    

    Next, configure docker to map the root user in the container to [user] on the host:

    sudo nano /etc/docker/daemon.json
    

    and (assuming it was empty before), set the contents to

    {
            "userns-remap": "[user]"
    }
    

    Again, [user] is your user name. Now restart the docker daemon:

    sudo systemctl restart docker
    

    Now, the root user within docker containers will correspond to your non-root user on the host. To test that this is indeed the case do the following:

    docker run -v $PWD:/my_current_dir -it ubuntu /bin/bash -c "cd /my_current_dir && bash"
    

    Once inside this test container, try

    touch who_owns_this.txt
    exit
    

    Now you're back on the host, so check who owns who_owns_this.txt

    ls -l
    

    We hope it is owned by [user] and not root.

    Keywords

    none

    Install

    npm i @magland/epoxy

    DownloadsWeekly Downloads

    7

    Version

    0.1.11

    License

    Apache-2.0

    Unpacked Size

    35.5 kB

    Total Files

    30

    Last publish

    Collaborators

    • magland