Skip to content

Containers

New in version 0.6.

Note

To be able to generate containers on macOS, you will need to use a remote Linux builder.

The easiest way is to set the remote builder up using Nix.

Use devenv container <name> to generate an OCI container from your development environment.

By default, shell and processes containers are predefined. You can also craft your own!

Examples of what devenv container can do:

  • devenv container shell: Generate a container and start the environment, equivalent of using devenv shell.
  • devenv container processes: Generate a container and start processes, equivalent of using devenv up.
  • devenv container <name> --registry docker://ghcr.io/ --copy: Copy the container <name> into the GitHub package registry.
  • devenv container <name> --docker-run: Run the container <name> using Docker.

Entering the development environment

Given a simple environment, using Python:

devenv.nix
{
  name = "simple-python-app";

  languages.python.enable = true;
}

Generate a container specification that enters the environment:

$ devenv container shell
/nix/store/...-image-devenv.json

Let's test it locally using Docker:

$ devenv container shell --docker-run
...
(devenv) bash-5.2# python
Python 3.10.9 (main, Dec  6 2022, 18:44:57) [GCC 12.2.0] on linux
Type "help", "copyright", "credits" or "license" for more information.
>>> 

Running processes

A common deployment strategy is to run each process as an entrypoint to the container.

devenv.nix
{
  name = "myapp";

  packages = [ pkgs.procps ];

  processes.hello-docker.exec = "while true; do echo 'Hello Docker!' && sleep 1; done";
  processes.hello-nix.exec = "while true; do echo 'Hello Nix!' && sleep 1; done";

  # Exclude the source repo to make the container smaller.
  containers."processes".copyToRoot = null; 
}

You can now copy the newly created image and start the container:

$ devenv container processes --docker-run
...
06:30:06 system         | hello-docker.1 started (pid=15)
06:30:06 hello-docker.1 | Hello Docker!
06:30:06 system         | hello-nix.1 started (pid=16)
06:30:06 hello-nix.1    | Hello Nix!
06:30:07 hello-nix.1    | Hello Nix!
06:30:07 hello-docker.1 | Hello Docker!
06:30:08 hello-nix.1    | Hello Nix!
06:30:08 hello-docker.1 | Hello Docker!

Running a single process

You can specify the command to run when the container starts (instead of entering the default development environment):

devenv.nix
{
  processes.serve.exec = "python -m http.server";

  containers."serve".name = "myapp";
  containers."serve".startupCommand = config.processes.serve.exec;
}
$ devenv container serve --docker-run

Running artifacts

If you're building binaries as part of the development environment, you can choose to only include those in the final image:

devenv.nix
{
  # watch local changes and build the project to ./dist
  processes.build.exec = "${pkgs.watchexec}/bin/watchexec my-build-tool";

  containers."prod".copyToRoot = ./dist;
  containers."prod".startupCommand = "/mybinary serve";
}
$ devenv container prod --docker-run 
...

Copying a container to a registry

To copy a container into a registry, pass it a --copy operation:

$ devenv container processes --copy --registry docker:// 

Another common example is deploying to fly.io. Any arguments passed to --copy-args are forwarded to skopeo copy:

$ devenv container processes --copy --registry docker://registry.fly.io/ --copy-args="--dest-creds x:$(flyctl auth token)"

You can also specify these options declaratively:

devenv.nix
{
  containers."processes".registry = "docker://registry.fly.io/";
  containers."processes".defaultCopyArgs = [
    "--dest-creds"
    "x:\"$(${pkgs.flyctl}/bin/flyctl auth token)\""
  ];
}

See this fly.io example for how to get started.

Changing the environment based on the build type

If you want to provide the openssl package to native and container environments, but git only for native environments:

devenv.nix
{ pkgs, config, lib, ... }:

{
  packages = [ pkgs.openssl ] 
    ++ lib.optionals (!config.container.isBuilding) [ pkgs.git ];
}

You can also conditionalize based on the particular container that is being built, for example, config.containers."processes".isBuilding.