{"id":14128225,"url":"https://github.com/cloudwatt/nix-container-images","last_synced_at":"2026-01-16T16:40:58.498Z","repository":{"id":48007625,"uuid":"160204062","full_name":"cloudwatt/nix-container-images","owner":"cloudwatt","description":"Write container images as NixOS machines","archived":false,"fork":false,"pushed_at":"2022-02-07T06:56:00.000Z","size":86,"stargazers_count":55,"open_issues_count":0,"forks_count":7,"subscribers_count":8,"default_branch":"master","last_synced_at":"2024-08-16T16:22:24.825Z","etag":null,"topics":["container","container-image","declarative","docker","nix","nixos"],"latest_commit_sha":null,"homepage":null,"language":"Nix","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/cloudwatt.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2018-12-03T14:30:10.000Z","updated_at":"2024-06-17T07:06:13.000Z","dependencies_parsed_at":"2022-08-12T16:21:32.015Z","dependency_job_id":null,"html_url":"https://github.com/cloudwatt/nix-container-images","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cloudwatt%2Fnix-container-images","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cloudwatt%2Fnix-container-images/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cloudwatt%2Fnix-container-images/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cloudwatt%2Fnix-container-images/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/cloudwatt","download_url":"https://codeload.github.com/cloudwatt/nix-container-images/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":228571844,"owners_count":17938772,"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":["container","container-image","declarative","docker","nix","nixos"],"created_at":"2024-08-15T16:01:24.628Z","updated_at":"2026-01-16T16:40:58.449Z","avatar_url":"https://github.com/cloudwatt.png","language":"Nix","funding_links":[],"categories":["Nix"],"sub_categories":[],"readme":"# Declarative container images with Nix\n\n**warning: this project is no longer maintained**\n\nWith this project you can\n- make your image composable (thanks to the NixOS modules system)\n- integrate the [s6](https://www.skarnet.org/software/s6/) init system in your images\n- reuse some NixOS modules in a container... without relying on systemd\n- make a Nix a Docker image, built by Nix\n\n\n## Getting started\n\nTo build a Docker image named `hello` that runs `hello`.\n\n```nix\nlib.makeImage (\n  { pkgs, ... }: {\n    config.image = {\n      name = \"hello\";\n      entryPoint = [ \"${pkgs.hello}/bin/hello\" ];\n    };\n  })\n```\n\n- To build an empty image from CLI,\n  ```\n  nix-build -E 'with import ./default.nix{}; lib.makeImage{ config.image.name = \"empty\"; }'\n  ```\n\n- To use `lib.makeImage` in your project, add `overlay.nix` to your\n  [nixpkgs overlay list](https://nixos.org/nixpkgs/manual/#sec-overlays-install).\n\nThe [`image`](#module-image) module section for more information.\n\n\n## Use s6 as init system to run services\n\nThe [s6 module](#module-s6) can be used to build an image with an init\nsystem. The [s6 init system](https://www.skarnet.org/software/s6/) is\nused to run defined `s6.services`.\n\n```nix\nlib.makeImage ({ pkgs, ... }: {\n  config = {\n    image.name = \"s6\";\n    s6.services.nginx = {\n      execStart = ''${pkgs.nginx}/bin/nginx -g \"daemon off;\"'';\n    };\n  };\n})\n```\n\nSome goals of using an init system in a container are\n- Proper PID 1 (no zombie processes)\n- Run several services in one container\n- Processes debugging (if the process is killed or died, the container\n  is not necessarily killed)\n- Execute initialization tasks\n\n\nSee [s6 module](#module-s6) for details.\n\n\n## (Re)Use NixOS modules\n\nSome NixOS modules can be used, such as `users`, `etc`.\n\n```nix\nlib.makeImage ({ pkgs, ... }: {\n  config = {\n    image.name = \"nixos\";\n    environment.systemPackages = [ pkgs.coreutils ];\n    users.users.alice = {\n      isNormalUser = true;\n    };\n  };\n})\n```\n\nSee also [supported NixOS modules](#supported-nixos-modules).\n\n\n## Systemd support for NixOS modules :/\n\nIt is possible to run some NixOS modules defining systemd services\nthanks to a partial systemd implementation with s6.\n\nNote this implementation is fragile, experimental and partial!\n\n```nix\nlib.makeImage ({ pkgs, ... }: {\n  config = {\n    image.name = \"nginx\";\n    # Yeah! It is the NixOS module!\n    services.nginx.enable = true;\n  };\n})\n```\n\n\n## Predefined images\n\n- [nix](images/nix.nix): basic single user installation\n\nThese images can be built with `nix-build -A dockerImages`.\n\nMore configurations and images are also available in the\n[tests directory](./tests).\n\n\n## Module `image`\n\nThe `image` module defines common Docker image attributes, such as the\nimage name, the environment variables, etc. Please refer to\n[the `image` options documentation](docs/options-well-supported-generated.md#imageentrypoint).\n\n\n## Module `s6`\n\nThis module allows you to easily create services, managed by the\n[s6 init system](https://www.skarnet.org/software/s6/). Three types of\nservices can be defined:\n\n- `oneshot-pre` services are exectued sequentially at container start\n  time and must terminate. They can be ordered thanks to the `after`\n  option.\n- `long-run` services are for daemons and are managed by `s6`. There\n  is no notion of dependency for `long-run` services.\n- `oneshot-post` services are executed sequentially once all `long-run`\n  services have been started. They can also be ordered (`after`\n  option). They are generally used to provision started services.\n\nOptions are described in this\n[generated `s6` options documentation](docs/options-well-supported-generated.md#s6services).\n\n\n### How/when s6 main process is terminated\n\nBy default, if a s6 service fails, the `s6-svcscan` (PID 1 in a\ncontainer) process is terminated. A `long-run` service can set the\n`restartOnFailure` option to `true` to restart the service when it\nfails.\n\nIf the `S6_DONT_TERMINATE_ON_ERROR` environment variable is set,\n`s6-svscan` is not terminated on service failure. This can be used to\ndebug a failing service interactively.\n\n\n## Supported NixOS modules\n\n- `users`: create users and groups\n- `nix`: configure Nix\n- `environment.etc`: create files in `/etc`\n- `systemd`: a small subset of the systemd module is implemented with [s6](https://www.skarnet.org/software/s6/)\n- `nginx`: see its [test](./tests/nginx.nix)\n\nImportant: only a small subset of NixOS modules is supported. See the\n[tests directory](./tests) for supported (and tested) features.\n\n\n## Tests\n\n- [s6](tests/s6.nix): s6 tests executed in the Nix build environment (fast to run but limited)\n- [dockerImages](tests/): tests on Docker images executed in a NixOS VM.\n\n\n## Implementation of the NixOS systemd service interface\n\nA subset of the NixOS systemd services interface is supported and\nimplemented with the [s6](https://www.skarnet.org/software/s6/) init\nsystem.\n\nThere are several differences with the NixOS systemd\nimplementation. The main one is the service dependency model:\n\n- Services of type `simple` become `long-run` s6 services and dependencies are ignored.\n- Services of type `oneshot` become `onehost-pre` s6 services except\n  if they have an `after` dependency to a `simple` service. In this\n  case, they become `oneshot-post`. Dependencies between oneshot\n  services are respected.\n\n\n## Tips\n\n- To generate and run the container init script as user\n  ```\n  nix-build  -A dockerImages.example-systemd.init\n  ./result S6-STATE-DIR\n  ```\n- To get the image used by a test `nix-build -A tests.dockerImages.nginx.image`\n- The NixOS config of an image `nix-instantiate --eval -A tests.dockerImages.nginx.image.config`\n- The NixOS config of an s6 test `nix-instantiate --eval -A tests.s6.path.config.systemd`\n\n\n## Related projects\n\n- [s6-overlay](https://github.com/just-containers/s6-overlay)\n- [nix-docker-nix](https://github.com/garbas/nix-docker-nix)\n\n\n## Contributing\n\nContributions to nix-container-images through PRs are always\nwelcome. All PRs will be automatically tested by the [Hydra CI\nserver](https://hydra.nix.corp.cloudwatt.com/project/nix-container-images).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcloudwatt%2Fnix-container-images","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcloudwatt%2Fnix-container-images","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcloudwatt%2Fnix-container-images/lists"}