Runtimes and Environments

Every time you add a code cell in a new programming language inside your notebook, a new runtime is added. Let's look into what this means.

Container-based execution

A runtime is a process running inside a Docker container. The initial file system snapshot provided to the runtime is the environment. Nextjournal offers a list of default environments. What's more, you can also create, export, and reuse your own, custom environments as Docker images.

Each different runtime uses its own, isolated environment, shown right next to the runtime's name in the sidebar. Multiple code cells of the same language share the same runtime, and subsequently that runtime’s environment (unless you change this).

Under the hood, the Runner Application organizes the code execution in your notebook using a communication protocol implemented by the runtimes.

Runtime States

When executing code in a cell, a runtime goes through various states. You can get a quick overview of these by looking at the dot next to the runtimes and their cells at the sidebar:

A gray dot means that the runtime is stopped. This means that, once you execute a cell that uses this runtime, the runtime will go through a booting phase. Because of this phase, the first run will take a bit longer than subsequent runs.

Once the runtime is running (shown by a green dot), execution should be reasonably fast, depending on what you are trying to accomplish.

A red dot and an error message indicate that there was an error during execution or booting of the runtime.

The log of all runtime-related actions is shown in the top bar of the Nextjournal Editor:

There are some more states a runtime can show, like Preparing Download, Downloading, Restoring or Uploading but those are mainly indicating the housekeeping around the underlying environment’s Docker image.

Automatic shutdown

Keep in mind that a runtime will automatically shut down after 20 minutes of idle time.

Long-running cells

Some use cases, like training a neural net, can potentially take hours to run. At the moment, Nextjournal does not enforce limitations other than shutdown after 20 minutes of idle time. This means that your cell keeps running even when you close the browser window. Just make sure that you are writing your results to /results so that they are persisted and versioned.

So what?

The fact that you can run your code in isolated environments allows you to seamlessly use different programming languages and environments within the same notebook.

But most importantly, it enables you to export, and subsequently reuse your environments as snapshots of your file system (by importing them into other notebooks, or downloading them as Docker images). So you can fairly easily, e.g., extend someone else’s environment for your own needs. Simply import a saved environment, install any additional packages you need for your use case, and save it again so other notebooks can make use of it.