Software Environments

By default, projects run a pre-built default software environment image. You can build your own project images, though.

Once you have one or more custom images on your own Docker registry, you need to tell your CoCalc deployment about that.

In a nutshell, the global.software dict in my-values.yaml defines default settings and a list of environments, where each one of them consists of a title, description, docker image tag and registry. Users can then choose from these environments when creating a new project, or changing the software environment of an existing project in the project settings.

Note

The keys in that software dict must be unique and stable. It is recommended to use simple alphanumeric names like the ones you see below ([a-z0-9]+) They are used by CoCalc to store the selected image for each project in the database.

When a project pod is created, the configuration is looked up. Do not modify a key’s name after it is in use, because then you end up with unexpected behavior. Instead, you can always change the configuration (registry and tag), though, which will have an impact the next time the project starts.

By default, the registry is the one defined globally. It is recommended to set the path to your registry and image name in the registry field. The container’s image field in the Pod definition will be the concatenation of $registry:$tag. You probably have to do something like for the fictional foobar2000 image below.

The group field is optional (default Default) and helps organizing the entries in the drop down selector.

The prepull field is optional and disabled by default. If it is set, you also have to enable the Prepull service. The images marked as prepull: true will be added as setup containers to the main prepull image, such that all images, maked in that way, will be pulled onto the project nodes.

Here is an example how to configure several software environments:

software:
  specialized:
    foobar2000:
      title: "foobar2000"
      descr: "This is a specialized environment for the **FooBar2000** research group."
      registry: "my-own.registry.tld/research/foobar2000"
      tag: "version42"
      prepull: true
    ubuntu2204:
      title: "Ubuntu 22.04"
      group: "Legacy"
      descr: "The standard software environment up until August 2024"
      tag: "software-20240612-1225"
    datascience:
      title: "Jupyter DataScience Notebook"
      group: "Jupyter"
      descr: "This is based on Jupyter's Datascience Docker images. [more info](https://jupyter-docker-stacks.readthedocs.io/en/latest/using/selecting.html#jupyter-datascience-notebook)"
      registry: "hsysmi/cocalc-cloud"
      tag: "datascience-20240527"
    texlive:
      title: "TeXLive"
      group: "LaTeX"
      tag: "texlive-20240605"
      prepull: false
      descr: |
        This is based on the [TexLive](https://hub.docker.com/r/texlive/texlive) docker image.
    cuda:
      title: "CUDA 12.1"
      tag: "cuda12.1-ubuntu2204-20240618"
      group: "GPU"
      prepull: true
      descr: |
        Ubuntu 22.04 based image with CUDA 12.1 by Nvidia and PyTorch 2.0. This image should work with GPUs!

Note: To change the default image, change manage.project.tag and the software.environments.default definition – see notes in cocalc/values.yaml.

Note

Regarding your users, the net result of the above is that they will be able to change the software environment of their projects. The above configuration will be in the selector when a new project is created or in Project Settings → Project Control → Software Environment.