📦 Stencila in reproducible computing environments
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Type Name Latest commit message Commit time
Failed to load latest commit information.


stencila/environs : Stencila within reproducible execution environments

experimental Build status Community Chat

This repository provides environs and tools for using Stencila within containers. Use cases include:

  • using Stencila packages for R, Python and Node.js without having to install them individually

  • collaborating on a Stencila document using an identical computing environment

  • publishing a Stencila document as a self-contained, reproducible, computational bundle


The minimal base images have just the bare essentials necessary for running a Stencila Host (the thing that provides execution contexts and other resources for each language). The "comprehensive" images have a large number of packages installed and are intended to be sufficient for most data analysis tasks without having to install more packages.

Image Summary
base A base image with Stencila packages for Python, R and/or Node.js
core An image with commonly used packages for data analysis in each language
mega Comprehensive images with a lot of packages for each language

To use these images simply run them with the container's port 2000 bound to a port on the host. Use a value in the range 2010-2100 so that it will be automatically be detected by the Stencila client (e.g. Stencila Desktop) without clashing:

docker run -it --rm -p 2100:2000 stencila/core


Some of these images are large (i.e. ~1GB compressed). The shrink-docker.sh script provides a way to shrink an image down to the minimum size necessary to reproduce your document.


Updating Node.js packages

Node.js environments, such as nix/core/node, are built using node2nix. You can install node2nix using:

nix-env -f '<nixpkgs>' -iA nodePackages.node2nix

node2nix generates the files node2nix/default.nix, node2nix/node-packages.nix and node2nix/node-env.nix from packages.json. If you update a packages.json then re-generate these files using node2nix directly:

cd nix/core/node/node2nix
node2nix -6 -i ../packages.json

or using the Makefile recipe:

make nix/core/node/node2nix

Adding package fetched from git

Use nix-prefetch-git to get the sha256 when specifying a package using nixpkgs.fetchgit e.g.

nix-prefetch-git https://github.com/stencila/r 4ebd3a8106294060316574eb340c7108542f722a

Run Stencila in a Nix shell

On NixOS or other linux with Nix installed run:

nix-shell core


nix-shell core/r

Within the Nix shell, three Stencila scripts are available

  • stencila-manifest: display a JSON manifest of the Stencila hosts and the packages installed within each
  • stencila-register: register the Stencila hosts so that they can discover each another within the environment
  • stencila-run: run the primary Stencila host in the environment

Run Stencila in a Docker Container

On NixOS, or Linux with Nix installed, run:

nix-build core/r

This will create a tar archived Docker container in your Nix store e.g. /nix/store/ci3k7fwnza75r9hg3wv0ab9c8544hmj8-docker-image-core-r.tar.gz and a symlink to that file in the current directory called result.

Load that tar archive as a Docker image using:

docker load -i result

Then run the image:

docker run -it --rm -p 2100:2000 stencila/core/r

To recover space you can clean up the Docker tar archive with:

nix-store --delete /nix/store/*-docker-image-stencila-*.tar.gz