Docker: Difference between revisions

(18 intermediate revisions by 13 users not shown)

Line 3:

== Installation ==

To install docker, add the following to ~~your~~ your NixOS configuration:

To install docker, add the following to your NixOS configuration:

Line 11:

[https://search.nixos.org/options?from=0&size=50&sort=alpha_asc&query=virtualisation.docker More options] are available.

~~Adding users~~ to the <code>docker</code> group ~~will provide them access to~~ the ~~socket~~:

To get access to the docker socket, you have to be in the <code>docker</code> group:{{Warning|Beware that the docker group membership is effectively [https://github.com/moby/moby/issues/9976 equivalent to being root]! <br> Consider using rootless mode below.}}

<~~syntaxHighlight~~ lang=nix>

users.users.<myuser>.extraGroups = [ "docker" ];

</~~syntaxHighlight>~~

</syntaxhighlight>

~~If you prefer, you could achieve the same with this:~~

~~<syntaxHighlight lang=nix>~~

~~users.extraGroups.docker.members = [ "username-with-access-to-socket" ];~~

~~</syntaxHighlight~~>

~~If you're still unable to get access to~~ the ~~socket~~, ~~you might have to~~ re-login.

After changing the group, a reboot or re-login might be required.

~~{{Warning|Beware that the docker group membership is effectively [https://github.com/moby/moby/issues/9976 equivalent to being root]!}}~~

Note: If you use the [[btrfs]] ~~filesystem~~, you might need to set the storageDriver option:

===== Docker on btrfs =====

Note: If you use the [[btrfs]] file system, you might need to set the <code>storageDriver</code> option:

virtualisation.docker.storageDriver = "btrfs"

virtualisation.docker.storageDriver = "btrfs";

</syntaxHighlight>

Line 44:

Line 39:

The <code>setSocketVariable</code> option sets the <code>DOCKER_HOST</code> variable to the rootless Docker instance for normal users by default.

== ~~Building~~ a docker ~~image~~ with ~~nixpkgs~~ ==

=== Changing Docker Daemon's Data Root ===

By default, the Docker daemon will store images, containers, and build context on the root file system.

If you want to change the location that Docker stores its data, you can configure a new <code>data-root</code> for the daemon by setting the <code>data-root</code> property of the [https://search.nixos.org/options?show=virtualisation.docker.daemon.settings&from=0&size=50&sort=alpha_asc&type=packages&query=virtualisation.docker <code>virtualisation.docker.daemon.settings</code>].

virtualisation.docker.daemon.settings = {

data-root = "/some-place/to-store-the-docker-data";

};

</syntaxHighlight>

=== Docker Containers as systemd Services ===

To make sure some docker containers are running as systemd services, you can use <code>oci-containers</code>:

virtualisation.oci-containers = {

backend = "docker";

containers = {

foo = {

# ...

};

</syntaxHighlight>

See [https://search.nixos.org/options?from=0&size=50&sort=alpha_asc&query=virtualisation.oci-containers oci-containers] for further options.

== Creating images with Nix ==

There is an entry for [https://nixos.org/nixpkgs/manual/#sec-pkgs-dockerTools dockerTools] in the ~~nixpkgs~~ manual for reference.

=== Building a docker image with nixpkgs ===

In the linked page they give the following example config:

There is an entry for [https://nixos.org/nixpkgs/manual/#sec-pkgs-dockerTools dockerTools] in the Nixpkgs manual for reference. In the linked page, they give the following example config:

Line 82:

Line 104:

More examples can be found in the [https://github.com/NixOS/nixpkgs/blob/master/pkgs/build-support/docker/examples.nix nixpkgs] repo.

Also check out the excellent article by [~~http~~://~~lethalman~~.~~blogspot~~.de/2016/04/cheap-docker-images-with-nix_15.html lethalman] about building minimal docker images with nix.

Also check out the excellent article by [https://lucabrunox.github.io/2016/04/cheap-docker-images-with-nix_15.html lethalman] about building minimal docker images with nix.

=== Reproducible image dates ===

Line 94:

Line 116:

The <code>sha256</code> argument of the <code>dockerTools.pullImage</code> function is the checksum of the archive generated by Skopeo. Since the archive contains the name and the tag of the image, Skopeo arguments used to fetch the image have to be identical to those used by the <code>dockerTools.pullImage</code> function.

For instance, the ~~sha~~ of the following image

For instance, the SHA of the following image

pkgs.dockerTools.pullImage{

Line 117:

Line 139:

</syntaxHighlight>

== Docker Compose with Nix ==

=== Directly Using Nix in Image Layers ===

Instead of copying Nix packages into Docker image layers, Docker can be configured to directly utilize the <code>nix-store</code> by integrating with [https://github.com/pdtpartners/nix-snapshotter nix-snapshotter].

This will significantly reduce data duplication and the time it takes to pull images.

== Docker Compose ==

Currently, there are two options to use Docker Compose with NixOS: Arion or Compose2Nix.

With Arion, you can specify most Docker Compose options in Nix Syntax, and Arion will generate a <code>docker-compose.yml</code> file internally. The result is a systemd service that starts and stops the container.

Compose2Nix, generates all necessary configs directly from the <code>docker-compose.yml</code>, which is easier when using an already existing Docker Compose project. The result is similar to that from Arion: a systemd service is created that handles starting and stopping the container.

=== Arion ===

[https://docs.hercules-ci.com/arion/ Arion] is created for running Nix-based projects in Docker Compose. It uses the NixOS module system for configuration, it can bypass <code>docker build</code> and lets you use dockerTools or use the store directly in the containers. The images/containers can be typical dockerTools style images or full NixOS configs.

To use Arion, you first need to add its module to ~~you~~ NixOS configuration:

To use Arion, you first need to add its module to your NixOS configuration:

Line 127:

Line 161:

</syntaxHighlight>

After that you can access its options under

After that, you can access its options under

virtualisation.arion = {}

Line 138:

Line 172:

backend = "docker";

projects = {

"db" = settings.services."db".service = {

"db".settings.services."db".service = {

image = "";

restart = "unless-stopped";

Line 146:

Line 180:

};

</syntaxHighlight>

=== Compose2Nix ===

With [https://github.com/aksiksi/compose2nix compose2nix] you can generate [https://search.nixos.org/options?query=virtualisation.oci-containers oci-containers] config from a <code>docker-compose.yaml</code>.

===== Install =====

To use <code>compose2nix</code> with <code>nix-shell</code> you can use<syntaxhighlight lang="bash">

nix shell github:aksiksi/compose2nix

compose2nix -h

</syntaxhighlight>To install <code>compose2nix</code> to NixOS, add the repo to your flake inputs<syntaxhighlight lang="nix">

compose2nix = {

url = "github:aksiksi/compose2nix";

inputs.nixpkgs.follows = "nixpkgs";

};

</syntaxhighlight>and add the package to your configuration<syntaxhighlight lang="nix">

environment.systemPackages = [

inputs.compose2nix.packages.x86_64-linux.default

];

</syntaxhighlight>

===== Usage =====

After you have installed <code>compose2nix</code>, you can run <code>compose2nix</code> in the directory with your <code>docker-compose.yml</code>, which will output a <code>docker-compose.nix</code>.

Alternatively, you can specify the input and output files with the following flags<syntaxhighlight lang="bash">

compose2nix -inputs input.yml -output output.nix -runtime docker

</syntaxhighlight>The <code>-runtime</code> flag specifies the runtime. Here, we select <code>docker</code>. Options are <code>podman</code> and <code>docker</code>. The default is <code>podman</code>

== Using Nix in containers ==

While [https://nixos.org/manual/nixpkgs/stable/#sec-pkgs-dockerTools dockerTools] allows to build lightweight containers, it requires <code>nix</code> to be installed on the host system. An alternative are docker images with nix preinstalled:

* [https://hub.docker.com/r/nixos/nix/tags nixos/nix] (official)

* [https://hub.docker.com/r/nixpkgs/nix nixpkgs/nix] (built from https://github.com/nix-community/docker-nixpkgs)

NixOS can be run in containers [https://docs.hercules-ci.com/arion/#_nixos_run_full_os using Arion].

== Troubleshooting ==

=== Cannot connect to public Wi-Fi, when using Docker ===

When connecting to a public Wi-Fi, where the login page's IP-Address is within the Docker network range, accessing the Internet might not be possible. This has been [https://unix.stackexchange.com/a/539258 reported] when trying to connect to the WIFIonICE of the Deutsche Bahn (DB). They use the <code>172.18.x.x</code> address range.

This can be resolved by changing the default address pool that Docker uses.<syntaxhighlight lang="nix">

virtualisation.docker = {

enable = true;

daemon.settings = {

"default-address-pools" = [

{ "base" = "172.27.0.0/16"; "size" = 24; }

];

};

</syntaxhighlight>Restarting, the container or Docker might be required.

== See also ==

[[Workgroup:Container]]

~~As of 22.05 [https://search.nixos.org/options?query=virtualisation.docker.rootless rootless] docker is available.~~ Alternatively you can use [~~https://nixos.wiki/wiki/Podman~~ Podman].

Alternatively you can use [[Podman | podman]].

[[Category:Cookbook]]

[[Category:~~NixOS~~]]

[[Category:Software]]

[[Category:~~nixpkgs~~]]

[[Category:Server]]

[[Category:~~incomplete]]~~

[[Category:Container]]

~~[[Category:Applications]]~~

~~[[Category:Docker~~]]