Docker: Difference between revisions

Line 5:

== Installation ==

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

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

Line 13:

[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 ~~or reboot.~~

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]! <br> Consider using rootless mode below~~.}}

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:

Line 47:

Line 42:

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

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

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>].

Line 57:

Line 52:

</syntaxHighlight>

== Docker Containers as systemd Services ==

=== Docker Containers as systemd Services ===

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

To make sure some docker containers are running as systemd services, you can use 'oci-containers':

Line 72:

Line 66:

</syntaxHighlight>

See https://mynixos.com/options/virtualisation.oci-containers.containers.%3Cname%3E for further options

See [https://mynixos.com/options/virtualisation.oci-containers.containers.%3Cname%3E oci-containers] for further options

= Creating images =

= Creating images with Nix =

== Building a docker image with nixpkgs ==

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

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:

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 126:

Line 118:

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 155:

Line 147:

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

== Docker Compose ~~with Nix~~ ==

== 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 165:

Line 163:

</syntaxHighlight>

After that you can access its options under

After that, you can access its options under

virtualisation.arion = {}

Line 184:

Line 182:

};

</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 =

Line 192:

Line 215:

* [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 ==

=== Change default address pool ===

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 =

@@ Line 5: / Line 5: @@
 == Installation ==
-To install docker, add the following to your your NixOS configuration:
+To install docker, add the following to your NixOS configuration:
 <syntaxHighlight lang=nix>
@@ Line 13: / Line 13: @@
 [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>
+<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 or reboot.
+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]! <br> Consider using rootless mode below.}}
-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:
 <syntaxHighlight lang=nix>
@@ Line 47: / Line 42: @@
 === Changing Docker Daemon's Data Root ===
-By default, the Docker daemon will store images, containers, and build context on the root filesystem.
+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>].
@@ Line 57: / Line 52: @@
 </syntaxHighlight>
-== Docker Containers as systemd Services ==
+=== Docker Containers as systemd Services ===
+To make sure some docker containers are running as systemd services, you can use <code>oci-containers</code>:
-To make sure some docker containers are running as systemd services, you can use 'oci-containers':
 <syntaxHighlight lang=nix>
@@ Line 72: / Line 66: @@
 </syntaxHighlight>
-See https://mynixos.com/options/virtualisation.oci-containers.containers.%3Cname%3E for further options
+See [https://mynixos.com/options/virtualisation.oci-containers.containers.%3Cname%3E oci-containers] for further options
-=  Creating images =
+=  Creating images with Nix =
-== Building a docker image with nixpkgs ==
+=== Building a docker image with nixpkgs ===
+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:
-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:
 <syntaxHighlight lang=nix>
@@ Line 126: / Line 118: @@
 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
 <syntaxHighlight lang=nix>
 pkgs.dockerTools.pullImage{
@@ Line 155: / Line 147: @@
 This will significantly reduce data duplication and the time it takes to pull images.
-== Docker Compose with Nix ==
+== 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:
 <syntaxHighlight lang=nix>
@@ Line 165: / Line 163: @@
 </syntaxHighlight>
-After that you can access its options under
+After that, you can access its options under
 <syntaxHighlight lang=nix>
 virtualisation.arion = {}
@@ Line 184: / Line 182: @@
 };
 </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 =
@@ Line 192: / Line 215: @@
 * [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 ==
+=== Change default address pool ===
+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 =