{"id":13617820,"url":"https://github.com/stencila/dockta","last_synced_at":"2025-04-13T00:43:36.815Z","repository":{"id":38984012,"uuid":"151520823","full_name":"stencila/dockta","owner":"stencila","description":"🐳 A Docker image builder for researchers","archived":false,"fork":false,"pushed_at":"2025-04-10T02:33:25.000Z","size":6244,"stargazers_count":120,"open_issues_count":49,"forks_count":12,"subscribers_count":7,"default_branch":"master","last_synced_at":"2025-04-13T00:43:29.875Z","etag":null,"topics":["docker","dockerfile","nodejs","python","r","reproducibility"],"latest_commit_sha":null,"homepage":"https://stencila.github.io/dockta/","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/stencila.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2018-10-04T05:00:17.000Z","updated_at":"2025-04-02T19:07:49.000Z","dependencies_parsed_at":"2023-12-24T15:42:06.362Z","dependency_job_id":"da6854c8-31e8-4a45-93dd-9cfba2fc7893","html_url":"https://github.com/stencila/dockta","commit_stats":{"total_commits":612,"total_committers":17,"mean_commits":36.0,"dds":0.6405228758169934,"last_synced_commit":"1385811d73c443f0f264ef596029b22491fd7b8d"},"previous_names":["stencila/dockter"],"tags_count":105,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/stencila%2Fdockta","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/stencila%2Fdockta/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/stencila%2Fdockta/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/stencila%2Fdockta/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/stencila","download_url":"https://codeload.github.com/stencila/dockta/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248650418,"owners_count":21139672,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["docker","dockerfile","nodejs","python","r","reproducibility"],"created_at":"2024-08-01T20:01:48.564Z","updated_at":"2025-04-13T00:43:36.795Z","avatar_url":"https://github.com/stencila.png","language":"TypeScript","funding_links":[],"categories":["TypeScript"],"sub_categories":[],"readme":"# Dockta: a container image builder for researchers\n\n[![All Contributors](https://img.shields.io/badge/all_contributors-7-orange.svg?style=flat-square)](#contributors)\n[![Build status](https://travis-ci.org/stencila/dockta.svg?branch=master)](https://travis-ci.org/stencila/dockta)\n[![Code coverage](https://codecov.io/gh/stencila/dockta/branch/master/graph/badge.svg)](https://codecov.io/gh/stencila/dockta)\n[![NPM](http://img.shields.io/npm/v/@stencila/dockta.svg?style=flat)](https://www.npmjs.com/package/@stencila/dockta)\n[![Docs](https://img.shields.io/badge/docs-latest-blue.svg)](https://stencila.github.io/dockta/)\n[![Chat](https://badges.gitter.im/stencila/stencila.svg)](https://gitter.im/stencila/stencila)\n\nDocker is a useful tool for creating reproducible computing environments. But creating truly reproducible Docker images can be difficult - even if you already know how to write a `Dockerfile`.\n\nDockta makes it easier for researchers to create Docker images for their research projects. Dockta generates a `Dockerfile` and builds a image, for _your_ project, based on _your_ source code.\n\n\u003c!-- Automatically generated TOC. Don't edit, `make docs` instead\u003e\n\n\u003c!-- toc --\u003e\n\n- [Features](#features)\n  * [Builds a Docker image based on your source code](#builds-a-docker-image-based-on-your-source-code)\n    + [R](#r)\n    + [Python](#python)\n    + [Node.js](#nodejs)\n    + [JATS](#jats)\n    + [Jupyter](#jupyter)\n  * [Automatically determines system requirements](#automatically-determines-system-requirements)\n  * [Faster re-installation of language packages](#faster-re-installation-of-language-packages)\n  * [Generates structured meta-data for your project](#generates-structured-meta-data-for-your-project)\n  * [Easy to pick up, easy to throw away](#easy-to-pick-up-easy-to-throw-away)\n- [Demo](#demo)\n- [Install](#install)\n- [Use](#use)\n  * [Compile a project](#compile-a-project)\n  * [Build a Docker image](#build-a-docker-image)\n  * [Execute a Docker image](#execute-a-docker-image)\n  * [Docter who?](#docter-who)\n  * [Predefined images](#predefined-images)\n    + [Image versions](#image-versions)\n    + [Getting the images](#getting-the-images)\n    + [Running the images](#running-the-images)\n    + [Extending the images](#extending-the-images)\n- [Contributors](#contributors)\n- [See also](#see-also)\n- [FAQ](#faq)\n- [Acknowledgments](#acknowledgments)\n\n\u003c!-- tocstop --\u003e\n\n## Features\n\n\u003e 🦄 Features that are planned, but not yet implemented, are indicated by unicorn emoji. Usually they have a link next to them, like this 🦄 [#2](https://github.com/stencila/dockta/issues/2), indicating the relevant issue where you can help make the feature a reality. It's [readme driven development](http://tom.preston-werner.com/2010/08/23/readme-driven-development.html) with calls to action to chase after mythical vaporware creatures! So hip.\n\n### Builds a Docker image based on your source code\n\nDockta scans your project and builds a custom Docker image for it. If the the folder already has a `Dockerfile`, Dockta will build the image from that. If not, Dockta will scan the source code files in the folder and generate one for you. Dockta currently handles R, Python and Node.js source code. A project can have a mix of these languages.\n\n#### R\n\nIf the folder contains a R package [`DESCRIPTION`](http://r-pkgs.had.co.nz/description.html) file then Dockta will install the R packages listed under `Imports` into the image. e.g.\n\n```\nPackage: myrproject\nVersion: 1.0.0\nDate: 2017-10-01\nImports:\n   ggplot2\n```\n\nThe `Package` and `Version` fields are required in a `DESCRIPTION` file. The `Date` field is used to define which CRAN snapshot to use. MRAN daily snapshots began [2014-09-08](https://cran.microsoft.com/snapshot/2014-09-08) so the date should be on or after that.\n\nIf the folder does not contain a `DESCRIPTION` file then Dockta will scan all the R files (files with the extension `.R` or `.Rmd`) in the folder for package import or usage statements, like `library(package)` and `package::function()`, and create a `.DESCRIPTION` file for you.\n\n#### Python\n\nIf the folder contains a [`requirements.txt`](https://pip.readthedocs.io/en/1.1/requirements.html) file, or a 🦄 [#4](https://github.com/stencila/dockta/issues/4) [`Pipfile`](https://github.com/pypa/pipfile), Dockta will copy it into the Docker image and use `pip` to install the specified packages.\n\nIf the folder does not contain either of those files then Dockta will scan all the folder's `.py` files for `import` statements and create a `.requirements.txt` file for you.\n\n#### Node.js\n\nIf the folder contains a [`package.json`](https://docs.npmjs.com/files/package.json) file, Dockta will copy it into the Docker image and use `npm` to install the specified packages.\n\nIf the folder does not contain a `package.json` file, Dockta will scan all the folder's `.js` files for `require` calls and create a `.package.json` file for you.\n\n#### JATS\n\nIf the folder contains any [JATS](https://en.wikipedia.org/wiki/Journal_Article_Tag_Suite) files (`.xml` files with `\u003c!DOCTYPE article PUBLIC \"-//NLM//DTD JATS (Z39.96) ...`), 🦄 [#52](https://github.com/stencila/dockta/issues/52) Docker will scan reproducible elements defined in the [Dar JATS extension](https://github.com/substance/dar/blob/master/DarArticle.md) for any package import statements (e.g. Python `import`, R `library`, or Node.js `require`) and install the necessary packages into the image.\n\n#### Jupyter\n\nIf the folder contains any Jupyter [`.ipynb`](http://jupyter.org/) files, 🦄 [#9](https://github.com/stencila/dockta/issues/9) Dockta will scan the code cells in those files for any package import statements (e.g. Python `import`, R `library`, or Node.js `require`) and install the necessary packages into the image. It will also 🦄 [#10](https://github.com/stencila/dockta/issues/10) add the necesary Jupyter kernels to the built Docker image.\n\n### Automatically determines system requirements\n\nOne of the headaches researchers face when hand writing Dockerfiles is figuring out which system dependencies your project needs. Often this involves a lot of trial and error.\n\nDockta automatically checks if any of your dependencies (or dependencies of dependencies, or dependencies of...) requires system packages and installs those into the image. For example, let's say you have a project with an R script that requires the `rgdal` package for geospatial analyses,\n\n```R\nlibrary(rgdal)\n```\n\nWhen you run `dockta compile` in this project, Dockta will generate a `Dockerfile` with the following section which installs R, plus the three system dependencies required `gdal-bin`, `libgdal-dev`, and `libproj-dev`:\n\n```Dockerfile\n# This section installs system packages required for your project\n# If you need extra system packages add them here.\nRUN apt-get update \\\n \u0026\u0026 DEBIAN_FRONTEND=noninteractive apt-get install -y \\\n      gdal-bin \\\n      libgdal-dev \\\n      libproj-dev \\\n      r-base \\\n \u0026\u0026 apt-get autoremove -y \\\n \u0026\u0026 apt-get clean \\\n \u0026\u0026 rm -rf /var/lib/apt/lists/*\n```\n\nFor R, Dockta does this by querying the https://sysreqs.r-hub.io/ database. For Python, Dockta includes a mapping of system requirements of packages that users can [contribute to](CONTRIBUTING.md#python-system-dependencies).\n\nNo more trial and error of build, fail, add dependency, repeat... cycles!\n\n### Faster re-installation of language packages\n\nIf you have built a Docker image before, you'll know that it can be frustrating waiting for _all_ your project's dependencies to reinstall when you simply add or remove one of them.\n\nThe reason this happens is that, due to Docker's layered filesystem, when you update a requirements file, Docker throws away all the subsequent layers - including the one where you previously installed your dependencies. That means that all those packages need to get reinstalled.\n\nDockta takes a different approach. It leaves the installation of language packages to the language package managers: Python's [`pip`](https://pypi.org/project/pip/) , Node.js's `npm`, and R's `install.packages`. These package managers are good at the job they were designed for - to check which packages need to be updated and to only update them. The result is much faster rebuilds, especially for R packages, which often involve compilation.\n\nDockta does this by looking for a special `# dockta` comment in a `Dockerfile`. Instead of throwing away subsequent image layers, it executes all instructions after this comment in the same layer - thus reusing packages that were previously installed.\n\nHere's a simple motivating [example](fixtures/tests/py-pandas). It's a Python project with a `requirements.txt` file which specifies that the project depends upon `pandas` which, to ensure reproducibility, is pinned to version `0.23.0`,\n\n```\npandas==0.23.0\n```\n\nThe project also has a `Dockerfile` which specifies which Python version we want to use, copies `requirements.txt` into the image, and uses `pip` to install the packages:\n\n```Dockerfile\nFROM python:3.7.0\n\nCOPY requirements.txt .\nRUN pip install -r requirements.txt\n```\n\nYou could build a Docker image for that project using Docker,\n\n```bash\ndocker build .\n```\n\nDocker will download the base Python image (if you don't yet have it), download five packages (`pandas` and it's four dependencies) and install them. This took over 9 minutes when we ran it.\n\nNow, let's say that we want to get the latest version of `pandas` and increment the version in the `requirements.txt` file,\n\n```\npandas==0.23.1\n```\n\nWhen we do `docker build .` again to update the image, Docker notices that the `requirements.txt` file has changed and so throws away that layer and all subsequent ones. This means that it will download and install _all_ the necessary packages again, including the ones that we previously installed. For a more contrived illustration of this, simply add a space to one of the lines in the `requirements.txt` file and notice how the package install gets repeated all over again.\n\nNow, let's add a special `# dockta` comment to the Dockerfile before the `COPY` directive,\n\n```Dockerfile\nFROM python:3.7.0\n\n# dockta\n\nCOPY requirements.xt .\nRUN pip install -r requirements.txt\n```\n\nThe comment is ignored by Docker but tells `dockta` to run all subsequent instructions in a single filesystem layer,\n\n```bash\ndockta build .\n```\n\nNow, if you change the `requirements.txt` file, instead of reinstalling everything again, `pip` will only reinstall what it needs to - the updated `pandas` version. The output looks like:\n\n```\nStep 1/1 : FROM python:3.7.0\n ---\u003e a9d071760c82\nSuccessfully built a9d071760c82\nSuccessfully tagged dockta-5058f1af8388633f609cadb75a75dc9d:system\nDockta 1/2 : COPY requirements.txt requirements.txt\nDockta 2/2 : RUN pip install -r requirements.txt\nCollecting pandas==0.23.1 (from -r requirements.txt (line 1))\n\n  \u003csnip\u003e\n\nSuccessfully built pandas\nInstalling collected packages: pandas\n  Found existing installation: pandas 0.23.0\n    Uninstalling pandas-0.23.0:\n      Successfully uninstalled pandas-0.23.0\nSuccessfully installed pandas-0.23.1\n\n```\n\n### Generates structured meta-data for your project\n\nDockta uses [JSON-LD](https://json-ld.org/) as it's internal data structure. When it parses your project's source code it generates a JSON-LD tree using a vocabularies from [schema.org](https://schema.org) and [CodeMeta](https://codemeta.github.io/index.html).\n\nFor example, It will parse a `Dockerfile` into a schema.org [`SoftwareSourceCode`](https://schema.org/SoftwareSourceCode) node extracting meta-data about the Dockerfile.\n\nDockta also fetches meta data on your project's dependencies, which could be used to generate a complete software citation for your project.\n\n```json\n{\n  \"name\": \"myproject\",\n  \"datePublished\": \"2017-10-19\",\n  \"description\": \"Regression analysis for my data\",\n  \"softwareRequirements\": [\n    {\n      \"description\": \"\\nFunctions to Accompany J. Fox and S. Weisberg,\\nAn R Companion to Applied Regression, Third Edition, Sage, in press.\",\n      \"name\": \"car\",\n      \"urls\": [\n        \"https://r-forge.r-project.org/projects/car/\",\n        \"https://CRAN.R-project.org/package=car\",\n        \"http://socserv.socsci.mcmaster.ca/jfox/Books/Companion/index.html\"\n      ],\n      \"authors\": [\n        {\n          \"name\": \"John Fox\",\n          \"familyNames\": [\n            \"Fox\"\n          ],\n          \"givenNames\": [\n            \"John\"\n          ]\n        },\n```\n\n### Easy to pick up, easy to throw away\n\nDockta is designed to make it easier to get started creating Docker images for your project. But it's also designed not to get in your way or restrict you from using bare Docker. You can easily, and individually, override any of the steps that Dockta takes to build an image.\n\n- _Code analysis_: To stop Dockta doing code analysis and take over specifying your project's package dependencies, just remove the leading '.' from the `.DESCRIPTION`, `.requirements.txt` or `.package.json` file that Dockta generates.\n\n- _Dockerfile generation_: Dockta aims to generate readable Dockerfiles that conform to best practices. They include comments on what each section does and are a good way to start learning how to write your own Dockerfiles. To stop Dockta generating a `.Dockerfile`, and start editing it yourself, just rename it to `Dockerfile`.\n\n- _Image building_: Dockta manages incremental builds using a special comment in the `Dockerfile`, so you can stop using Dockta altogether and build the same image using Docker (it will just take longer if you change you project dependencies).\n\n## Demo\n\n\u003ca href=\"https://asciinema.org/a/pOHpxUqIVkGdA1dqu7bENyxZk?size=medium\u0026cols=120\u0026autoplay=1\" target=\"_blank\"\u003e\u003cimg src=\"https://asciinema.org/a/pOHpxUqIVkGdA1dqu7bENyxZk.svg\" /\u003e\u003c/a\u003e\n\n## Install\n\nDockta is available as a Node.js package with a command line interface (CLI). If you want to use Dockta to build Docker images, you will need to [install Docker](https://docs.docker.com/install/) if you don't already have it.\n\n```bash\nnpm install @stencila/dockta\n```\n\n## Use\n\nThe command line tool has three primary commands `compile`, `build` and `execute`. To get an overview of the commands available use the `--help` option i.e.\n\n```bash\ndockta --help\n```\n\nTo get more detailed help on a particular command, also include the command name e.g\n\n```bash\ndockta compile --help\n```\n\n### Compile a project\n\nThe `compile` command compiles a project folder into a specification of a software environment. It scans the folder for source code and package requirement files, parses them, and creates an `.environ.jsonld` file. This file contains the information needed to build a Docker image for your project.\n\nFor example, let's say your project folder has a single R file, `main.R` which uses the R package `lubridate` to print out the current time:\n\n```R\nlubridate::now()\n```\n\nLet's compile that project and inspect the compiled software environment. Change into the project directory and run the `compile` command.\n\n```bash\ndockta compile\n```\n\nYou should find three new files in the folder created by Dockta:\n\n- `.DESCRIPTION`: A R package description file containing a list of the R packages required and other meta-data\n\n- `.envrion.jsonld`: A JSON-LD document containing structure meta-data on your project and all of its dependencies\n\n- `.Dockerfile`: A `Dockerfile` generated from `.environ.jsonld`\n\nTo stop Dockta generating any of these files and start editing it yourself, remove the leading `.` from the name of the file you want to take over creating.\n\n### Build a Docker image\n\nUsually, you'll compile and build a Docker image for your project in one step using the `build` command. This command runs the `compile` command and builds a Docker image from the generated `.Dockerfile` (or handwritten `Dockerfile`):\n\n```bash\ndockta build\n```\n\nAfter the image has finished building you should have a new docker image on your machine, called `rdate`:\n\n```bash\n\u003e docker images\nREPOSITORY        TAG                 IMAGE ID            CREATED              SIZE\nrdate             latest              545aa877bd8d        About a minute ago   766MB\n```\n\nIf you want to build your image with bare Docker rename `.Dockerfile` to `Dockerfile` and run `docker build .` instead. This might be a good approach when you have finished the exploratory phase of your project (i.e. there is litte or no churn in your package dependencies) and want to create a more final image.\n\n\u003e 🛈 Docker images can get very large (2-3 GB is not unusual for an image with R and/or Python and associated packages).\n\u003e You might want to occasionally do a clean up of 'dangling' images using `docker image prune` to save disk space.\n\u003e See the Docker [documentation for more on cleaning up](https://docs.docker.com/config/pruning/) unused images and containers.\n\n### Execute a Docker image\n\nYou can use Docker to run the created image. Or use Dockta's `execute` command to compile, build and run your image in one:\n\n```bash\n\u003e dockta execute\n2018-10-23 00:58:39\n```\n\nDockta's `execute` also mounts the folder into the container and sets the users and group ids. This allows you to read and write files into the project folder from within the container. It's equivaluent to running Docker with these arguments:\n\n```bash\ndocker run --rm --volume $(pwd):/work --workdir=/work --user=$(id -u):$(id -g) \u003cimage\u003e\n```\n\n### Docter who?\n\nDockta compiles a meta-data tree of all the packages that your project relies on. Use the `who` command to get a list of the authors of those packages:\n\n```bash\n\u003e dockta who\nRoger Bivand (rgdal, sp), Tim Keitt (rgdal), Barry Rowlingson (rgdal), Edzer Pebesma (sp)\n```\n\nUse the `depth` option to restrict the listing to a particular depth in the dependency tree. For example, to list the authors of the packages that your project directly relies upon use:\n\n```bash\n\u003e dockta who --depth=1\n```\n\n### Predefined images\n\nThis repository defines a number of compute environments that can be built using Dockta.\n\nThe `stencila/executa-all` image installs all known executor packages (e.g. `basha`, `pyla`) into a container. It is built, with the latest versions of those packages, and pushed to [Docker Hub](https://hub.docker.com/repository/docker/stencila/executa), on each push to master and daily at midnight UTC.\n\nThe image `stencila/executa-all` image is the base for other images, each of which add popular packages for various programming languages. See the [`images`](images) folder for the definitions of those environments.\n\n#### Image versions\n\nAll images are built at least nightly (so that they have the latest versions of packages installed in them) and tagged with a dated build number. See the Docker Hub for the latest versions:\n\n- [`stencila/executa-all`](https://hub.docker.com/r/stencila/executa-all/tags?page=1\u0026ordering=last_updated)\n- [`stencila/executa-midi`](https://hub.docker.com/r/stencila/executa-midi/tags?page=1\u0026ordering=last_updated)\n\n#### Getting the images\n\nYou can get the latest version using `docker pull` e.g.\n\n```bash\ndocker pull stencila/executa-all\n```\n\nOr, grab a particular, date stamped, build e.g. the first build on 2020-10-22:\n\n```bash\ndocker pull stencila/executa-all:20202022.1\n```\n\nAlternatively, you can build the image locally using `dockta`:\n\n```bash\ndockta build images/executa-all\n```\n\n#### Running the images\n\nRun the images like this,\n\n```bash\ndocker run -it --rm -p 9000:9000 stencila/executa-midi\n```\n\nThat will serve Executa from within the container and make it available at ws://localhost:9000.\n\n#### Extending the images\n\nThere are several ways that you can extend the images, for example to add a package that you need for your analysis.\n\n##### Make a pull request\n\nThe `executa-midi` image is intended to be a fairly comprehensive image containing most of the commonly download packages for R and Python. We regularly query download stats from [CRAN](https://cran.r-project.org/) and [PyPI](https://pypi.org/) and take the top 150 most downloaded packages (minus some exclusions, plus some inclusions). The list of current packages are:\n\n- [`DESCRIPTION`](images/executa-midi/DESCRIPTION) for R packages\n- [`requirements.txt`](images/executa-midi/requirements.txt) for Python packages\n- [`package.json`](images/executa-midi/package.json) for Node.js packages\n\nIf you think that a popular package is missing and should be included then please submit a pull request which adds the package to one of the following files:\n\n- [`images/packages/r/executa-midi.json`](images/packages/r/executa-midi.json) for R packages\n- [`images/packages/python/executa-midi.json`](images/packages/python/executa-midi.json) for python packages\n\n##### Create your own image\n\nYou can create an image with extra packages by (a) creating a new folder with a new `DESCRIPTION`, `requirements.txt`, and/or `package.json` file that list those extra packages and (b) using the `--from` option. e.g.\n\n```bash\ncd my-custom-image/\ndockta build --from stencila/executa-midi\n```\n\n##### Write your own `Dockerfile`\n\nIf you want the most control (and responsibility ;) you can always write your own `Dockerfile` using one of our images in the `FROM` directive e.g.\n\n```Dockerfile\nFROM stencila/executa-midi\n\n# Use `root` user for installing new packages\nUSER root\n\n# Install a Python package\nRUN python3 -m pip install some-package\n\n# Install a R package from a particular date\nRUN install.packages(\"somePackage\", repos=\"https://mran.microsoft.com/snapshot/2020-10-21\")\n\n# Go back to `guest` user for better security when the container is run\nUSER guest\n```\n\nYou can run `docker build` on this Dockerfile, push it to a Docker container registry, and then specify it as image to use for your project on Stencila Hub.\n\n## Contributors\n\nWe 💕 contributions! All contributions: ideas 🤔, examples 💡, bug reports 🐛, documentation 📖, code 💻, questions 💬. See [CONTRIBUTING.md](CONTRIBUTING.md) for more details.\n\nThis project follows the [all-contributors](https://github.com/kentcdodds/all-contributors) specification. Thanks 🙏 to these wonderful ✨ people who have contributed so far 💖!\n\n\u003c!-- ALL-CONTRIBUTORS-LIST:START - Do not remove or modify this section --\u003e\n\u003c!-- prettier-ignore --\u003e\n\u003ctable\u003e\n  \u003ctr\u003e\n    \u003ctd align=\"center\"\u003e\u003ca href=\"https://remirampin.com/\"\u003e\u003cimg src=\"https://avatars3.githubusercontent.com/u/426784?v=4\" width=\"100px;\" alt=\"Remi Rampin\"/\u003e\u003cbr /\u003e\u003csub\u003e\u003cb\u003eRemi Rampin\u003c/b\u003e\u003c/sub\u003e\u003c/a\u003e\u003cbr /\u003e\u003ca href=\"https://github.com/stencila/dockta/issues?q=author%3Aremram44\" title=\"Bug reports\"\u003e🐛\u003c/a\u003e \u003ca href=\"https://github.com/stencila/dockta/commits?author=remram44\" title=\"Code\"\u003e💻\u003c/a\u003e \u003ca href=\"#ideas-remram44\" title=\"Ideas, Planning, \u0026 Feedback\"\u003e🤔\u003c/a\u003e\u003c/td\u003e\n    \u003ctd align=\"center\"\u003e\u003ca href=\"http://bbit.co.nz\"\u003e\u003cimg src=\"https://avatars1.githubusercontent.com/u/292725?v=4\" width=\"100px;\" alt=\"Ben\"/\u003e\u003cbr /\u003e\u003csub\u003e\u003cb\u003eBen\u003c/b\u003e\u003c/sub\u003e\u003c/a\u003e\u003cbr /\u003e\u003ca href=\"https://github.com/stencila/dockta/commits?author=beneboy\" title=\"Code\"\u003e💻\u003c/a\u003e \u003ca href=\"#ideas-beneboy\" title=\"Ideas, Planning, \u0026 Feedback\"\u003e🤔\u003c/a\u003e\u003c/td\u003e\n    \u003ctd align=\"center\"\u003e\u003ca href=\"http://stenci.la\"\u003e\u003cimg src=\"https://avatars2.githubusercontent.com/u/2358535?v=4\" width=\"100px;\" alt=\"Aleksandra Pawlik\"/\u003e\u003cbr /\u003e\u003csub\u003e\u003cb\u003eAleksandra Pawlik\u003c/b\u003e\u003c/sub\u003e\u003c/a\u003e\u003cbr /\u003e\u003ca href=\"https://github.com/stencila/dockta/commits?author=apawlik\" title=\"Code\"\u003e💻\u003c/a\u003e \u003ca href=\"#example-apawlik\" title=\"Examples\"\u003e💡\u003c/a\u003e \u003ca href=\"https://github.com/stencila/dockta/issues?q=author%3Aapawlik\" title=\"Bug reports\"\u003e🐛\u003c/a\u003e\u003c/td\u003e\n    \u003ctd align=\"center\"\u003e\u003ca href=\"https://github.com/nokome\"\u003e\u003cimg src=\"https://avatars0.githubusercontent.com/u/1152336?v=4\" width=\"100px;\" alt=\"Nokome Bentley\"/\u003e\u003cbr /\u003e\u003csub\u003e\u003cb\u003eNokome Bentley\u003c/b\u003e\u003c/sub\u003e\u003c/a\u003e\u003cbr /\u003e\u003ca href=\"https://github.com/stencila/dockta/commits?author=nokome\" title=\"Code\"\u003e💻\u003c/a\u003e \u003ca href=\"https://github.com/stencila/dockta/commits?author=nokome\" title=\"Tests\"\u003e⚠️\u003c/a\u003e\u003c/td\u003e\n    \u003ctd align=\"center\"\u003e\u003ca href=\"http://giorgiosironi.com\"\u003e\u003cimg src=\"https://avatars3.githubusercontent.com/u/160299?v=4\" width=\"100px;\" alt=\"Giorgio Sironi\"/\u003e\u003cbr /\u003e\u003csub\u003e\u003cb\u003eGiorgio Sironi\u003c/b\u003e\u003c/sub\u003e\u003c/a\u003e\u003cbr /\u003e\u003ca href=\"#review-giorgiosironi\" title=\"Reviewed Pull Requests\"\u003e👀\u003c/a\u003e \u003ca href=\"https://github.com/stencila/dockta/issues?q=author%3Agiorgiosironi\" title=\"Bug reports\"\u003e🐛\u003c/a\u003e \u003ca href=\"#ideas-giorgiosironi\" title=\"Ideas, Planning, \u0026 Feedback\"\u003e🤔\u003c/a\u003e \u003ca href=\"#question-giorgiosironi\" title=\"Answering Questions\"\u003e💬\u003c/a\u003e\u003c/td\u003e\n    \u003ctd align=\"center\"\u003e\u003ca href=\"http://bmpvieira.com\"\u003e\u003cimg src=\"https://avatars3.githubusercontent.com/u/263386?v=4\" width=\"100px;\" alt=\"Bruno Vieira\"/\u003e\u003cbr /\u003e\u003csub\u003e\u003cb\u003eBruno Vieira\u003c/b\u003e\u003c/sub\u003e\u003c/a\u003e\u003cbr /\u003e\u003ca href=\"https://github.com/stencila/dockta/commits?author=bmpvieira\" title=\"Code\"\u003e💻\u003c/a\u003e \u003ca href=\"#ideas-bmpvieira\" title=\"Ideas, Planning, \u0026 Feedback\"\u003e🤔\u003c/a\u003e \u003ca href=\"https://github.com/stencila/dockta/commits?author=bmpvieira\" title=\"Tests\"\u003e⚠️\u003c/a\u003e\u003c/td\u003e\n    \u003ctd align=\"center\"\u003e\u003ca href=\"https://gliptak.github.io/\"\u003e\u003cimg src=\"https://avatars0.githubusercontent.com/u/50109?v=4\" width=\"100px;\" alt=\"Gábor Lipták\"/\u003e\u003cbr /\u003e\u003csub\u003e\u003cb\u003eGábor Lipták\u003c/b\u003e\u003c/sub\u003e\u003c/a\u003e\u003cbr /\u003e\u003ca href=\"#infra-gliptak\" title=\"Infrastructure (Hosting, Build-Tools, etc)\"\u003e🚇\u003c/a\u003e \u003ca href=\"https://github.com/stencila/dockta/issues?q=author%3Agliptak\" title=\"Bug reports\"\u003e🐛\u003c/a\u003e\u003c/td\u003e\n  \u003c/tr\u003e\n\u003c/table\u003e\n\n\u003c!-- ALL-CONTRIBUTORS-LIST:END --\u003e\n\n## See also\n\nThere are several other projects that create Docker images from source code and/or requirements files including:\n\n- [`alibaba/derrick`](https://github.com/alibaba/derrick)\n- [`jupyter/repo2docker`](https://github.com/jupyter/repo2docker)\n- [`Gueils/whales`](https://github.com/Gueils/whales)\n- [`o2r-project/containerit`](https://github.com/o2r-project/containerit)\n- [`openshift/source-to-image`](https://github.com/openshift/source-to-image)\n- [`ViDA-NYU/reprozip`](https://github.com/ViDA-NYU/reprozip])\n\nDockta is similar to `repo2docker`, `containerit`, and `reprozip` in that it is aimed at researchers doing data analysis (and supports R) whereas most other tools are aimed at software developers (and don't support R). Dockta differs to these projects principally in that it:\n\n- performs static code analysis for multiple languages to determine package requirements.\n\n- uses package databases to determine package system dependencies and generate linked meta-data (`containerit` does this for R).\n\n- quicker installation of language package dependencies (which can be useful during research projects where dependencies often change).\n\n- by default, but optionally, installs Stencila packages so that Stencila client interfaces can execute code in the container.\n\nThe approach taken in Dockta to building Docker images is a mix of Dockerfile generation, as in `repo2docker`, and code injection and incremental builds as in `source-to-image`.\n\n`reprozip` and its extension `reprounzip-docker` may be a better choice if you want to share your existing local environment as a Docker image with someone else.\n\n`containerit` might suit you better if you only need support for R and don't want managed packaged installation.\n\n`repo2docker` is probably a better choice if you want to run Jupyter notebooks or RStudio in your container and don't need source code scanning to detect your requirements.\n\n`source-to-image` might suit you better if your focus is on web development (e.g. Ruby, Node.js) and want a more stable, feature complete implementation of incremental builds.\n\nIf you don't want to build a Docker image and just want a tool that helps determining the package dependencies of your source code check out:\n\n- Node.js: [`detective`](https://github.com/browserify/detective)\n- Python: [`modulefinder`](https://docs.python.org/3.7/library/modulefinder.html)\n- R: [`requirements`](https://github.com/hadley/requirements)\n\n## FAQ\n\n_Why go to the effort of generating a JSON-LD intermediate representation instead of writing a Dockerfile directly?_\n\nHaving an intermediate representation of the software environment allows this data to be used for other purposes (e.g. software citations, publishing, archiving). It also allows us to reuse much of this code for build targets other than Docker (e.g. Nix) and sources other than code files (e.g. a GUI).\n\n_Why is Dockta a Node.js package?_\n\nWe've implemented this as a Node.js package for easier integration into Stencila's Node.js based desktop and cloud deployments. We already had familiarity with using `dockerode` the Node.js package that we use to talk to Docker for incremental builds and container execution.\n\n_Why is Dockta implemented in Typescript?_\n\nTypescript's type-checking and type-annotations can reduce the number of runtime errors and improves developer experience. For this particular project, we wanted to use the Typescript type definitions for `SoftwarePackage`, `CreativeWork`, `Person` etc that are defined in [stencila/schema](https://github.com/stencila/schema).\n\n_Why didn't you use, and contribute to, an existing project rather than creating a new tool_\n\nWhen existing projects don't take the approach or provide the features you want, it's often a difficult decision to make whether to invest the time to understand and refactor an existing code base or to start fresh. In this case, we chose to start fresh for the reasons and differences outlined above. We felt it would take too much refactoring of existing projects to shoehorn in the approach we wanted to take. We also wanted to be able to reuse much of the code developed here in a sister project, [Nixster](https://github.com/stencila/nixster), which aims to make it easier for researchers to build Nix environments.\n\n_I'd love to help out! Where do I start?_\n\nSee [CONTRIBUTING.md](CONTRIBUTING.md) (OK, so this isn't asked _that_ frequently. But it's worth a try eh :woman_shrugging:.)\n\n## Acknowledgments\n\nDockta was inspired by, and combines ideas from, several similar tools including [`binder`](https://github.com/binder-project/binder), [`repo2docker`](https://github.com/jupyter/repo2docker), [`source-to-image`](https://github.com/openshift/source-to-image) and [`containerit`](https://github.com/o2r-project/containerit). It relies on many great open source projects, in particular:\n\n- [CodeMeta](https://codemeta.github.io/)\n- [`crandb`](https://github.com/metacran/crandb)\n- [`dockerode`](https://www.npmjs.com/package/dockerode)\n- [`docker-file-parser`](https://www.npmjs.com/package/docker-file-parser)\n- [`npm/registry`](https://github.com/npm/registry)\n- [`pypa`](https://warehouse.pypa.io)\n- [`sysreqsdb`](https://github.com/r-hub/sysreqsdb)\n- and of course, [Docker](https://www.docker.com/)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fstencila%2Fdockta","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fstencila%2Fdockta","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fstencila%2Fdockta/lists"}