Export translations

Settings

Group

Language

Format

Export for off-line translation

Export in native format

Export in CSV format

<languages/>
<div lang="en" dir="ltr" class="mw-content-ltr">
[https://www.docker.com/ Docker] is a platform for building, packaging, and distributing applications inside containers. Containers bundle an application's code, configurations, and dependencies into a single object that runs consistently across different computing environments. Docker works well with NixOS through the virtualization module.<ref>https://www.docker.com/resources/what-container/</ref>
</div>

<div lang="en" dir="ltr" class="mw-content-ltr">
== Installation ==
</div>

<div lang="en" dir="ltr" class="mw-content-ltr">
==== Shell ====
</div>

<div lang="en" dir="ltr" class="mw-content-ltr">
To temporarily use Docker in a shell environment, you can run:
</div>
<syntaxhighlight lang="bash">
nix-shell -p docker
</syntaxhighlight>
<div lang="en" dir="ltr" class="mw-content-ltr">
This will provide a shell with Docker CLI available, but note that the Docker daemon will not be running. For full functionality, you'll need a system-level installation.
</div>

<div lang="en" dir="ltr" class="mw-content-ltr">
==== System setup ====
</div>

<div lang="en" dir="ltr" class="mw-content-ltr">
To install Docker on NixOS, add the virtualization.docker module to your system configuration at <code>/etc/nixos/configuration.nix</code>:<ref>https://nixos.org/manual/nixos/stable/options#opt-virtualisation.docker.enable</ref>
</div>
<syntaxhighlight lang="nix">
# In /etc/nixos/configuration.nix
virtualisation.docker = {
  enable = true;
};

# Optional: Add your user to the "docker" group to run docker without sudo
users.users.<username>.extraGroups = [ "docker" ];
</syntaxhighlight>
{{Security Warning|Beware that the docker group membership is effectively [https://github.com/moby/moby/issues/9976 equivalent to being root]! <br> Consider using [[#Rootless Docker|rootless mode]].}}

<div lang="en" dir="ltr" class="mw-content-ltr">
For a comprehensive list of configuration options, refer to the {{nixos:option|virtualisation.docker}} module options.
</div>

<div lang="en" dir="ltr" class="mw-content-ltr">
== Configuration ==
</div>

<div lang="en" dir="ltr" class="mw-content-ltr">
==== Basic ====
</div>

<div lang="en" dir="ltr" class="mw-content-ltr">
The basic Docker configuration on NixOS includes several options you can set in your <code>configuration.nix</code> file:
</div>
<syntaxhighlight lang="nix">
virtualisation.docker = {
  enable = true;
  # Set up resource limits
  daemon.settings = {
    experimental = true;
    default-address-pools = [
      {
        base = "172.30.0.0/16";
        size = 24;
      }
    ];
  };
};
</syntaxhighlight>

<div lang="en" dir="ltr" class="mw-content-ltr">
==== Advanced ====
</div>

<div lang="en" dir="ltr" class="mw-content-ltr">
For more advanced configuration, you can customize Docker daemon options and networking:
</div>
<syntaxhighlight lang="nix">
virtualisation.docker = {
  enable = true;
  # Customize Docker daemon settings using the daemon.settings option
  daemon.settings = {
    dns = [ "1.1.1.1" "8.8.8.8" ];
    log-driver = "journald";
    registry-mirrors = [ "https://mirror.gcr.io" ];
    storage-driver = "overlay2";
  };
  # Use the rootless mode - run Docker daemon as non-root user
  rootless = {
    enable = true;
    setSocketVariable = true;
  };
};
</syntaxhighlight>

<div lang="en" dir="ltr" class="mw-content-ltr">
== Docker Compose ==
</div>
<div lang="en" dir="ltr" class="mw-content-ltr">
Currently, there are two options to use Docker Compose with NixOS: Arion or Compose2Nix.
</div>

<div lang="en" dir="ltr" class="mw-content-ltr">
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.
</div>

<div lang="en" dir="ltr" class="mw-content-ltr">
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.
</div>

<div lang="en" dir="ltr" class="mw-content-ltr">
=== Arion ===
</div>
<div lang="en" dir="ltr" class="mw-content-ltr">
[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.
</div>

<div lang="en" dir="ltr" class="mw-content-ltr">
To use Arion, you first need to add its module to your NixOS configuration:
</div>

<syntaxhighlight lang="nix">
modules = [ arion.nixosModules.arion ];
</syntaxhighlight>

<div lang="en" dir="ltr" class="mw-content-ltr">
After that, you can access its options under
</div>
<syntaxhighlight lang="nix">
virtualisation.arion = {}
</syntaxhighlight>

<div lang="en" dir="ltr" class="mw-content-ltr">
A config for a simple container could look like this:
</div>

<syntaxhighlight lang="nix">
virtualisation.arion = {
  backend = "docker";
  projects = {
    "db".settings.services."db".service = {
      image = "";
      restart = "unless-stopped";
      environment = { POSTGRESS_PASSWORD = "password"; };
    };
  };
};
</syntaxhighlight>

<div lang="en" dir="ltr" class="mw-content-ltr">
=== Compose2Nix ===
</div>
<div lang="en" dir="ltr" class="mw-content-ltr">
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>.
</div>

<div lang="en" dir="ltr" class="mw-content-ltr">
==== Install ====
</div>
<div lang="en" dir="ltr" class="mw-content-ltr">
To use <code>compose2nix</code> with <code>nix-shell</code> you can use
</div>
<syntaxhighlight lang="bash">
nix shell github:aksiksi/compose2nix
compose2nix -h
</syntaxhighlight>
<div lang="en" dir="ltr" class="mw-content-ltr">
To install <code>compose2nix</code> to NixOS, add the repo to your flake inputs
</div>
<syntaxhighlight lang="nix">
compose2nix = {
  url = "github:aksiksi/compose2nix";
  inputs.nixpkgs.follows = "nixpkgs";
};
</syntaxhighlight>
<div lang="en" dir="ltr" class="mw-content-ltr">
and add the package to your configuration
</div>
<syntaxhighlight lang="nix">
environment.systemPackages = [
  inputs.compose2nix.packages.x86_64-linux.default
];
</syntaxhighlight>

<div lang="en" dir="ltr" class="mw-content-ltr">
==== Usage ====
</div>
<div lang="en" dir="ltr" class="mw-content-ltr">
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>.
</div>

<div lang="en" dir="ltr" class="mw-content-ltr">
Alternatively, you can specify the input and output files with the following flags
</div>
<syntaxhighlight lang="bash">
compose2nix -inputs input.yml -output output.nix -runtime docker
</syntaxhighlight>
<div lang="en" dir="ltr" class="mw-content-ltr">
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>
</div>

<div lang="en" dir="ltr" class="mw-content-ltr">
== Tips and tricks ==
</div>

<div lang="en" dir="ltr" class="mw-content-ltr">
=== Docker on btrfs ===
</div>

<div lang="en" dir="ltr" class="mw-content-ltr">
If you use the [[btrfs]] file system, you might need to set the {{nixos:option|virtualisation.docker.storageDriver|storageDriver}} option:
</div>
<syntaxhighlight lang="nix">
virtualisation.docker.storageDriver = "btrfs";
</syntaxhighlight>

<div lang="en" dir="ltr" class="mw-content-ltr">
=== Rootless Docker ===
</div>

<div lang="en" dir="ltr" class="mw-content-ltr">
Rootless Docker lets you run the Docker daemon as a non-root user for improved security. Set the <code>rootless</code> option [[#Advanced|as shown above]]. The <code>setSocketVariable</code> option adds the <code>DOCKER_HOST</code> variable pointing to your rootless Docker instance.
</div>

<div lang="en" dir="ltr" class="mw-content-ltr">
After enabling rootless mode, Docker can be started with:
</div>
<syntaxhighlight lang="bash">
$ systemctl --user enable --now docker
</syntaxhighlight>

<div lang="en" dir="ltr" class="mw-content-ltr">
This creates the 'docker.service' file which is required to start Docker. Note that the service will not start at boot by this command. You will have to set it up in your NixOS configuration. Now the following command will work:
</div>
<syntaxhighlight lang="bash">
$ systemctl --user start docker
</syntaxhighlight>

<div lang="en" dir="ltr" class="mw-content-ltr">
Check its status with:
</div>
<syntaxhighlight lang="bash">
$ systemctl --user status docker
</syntaxhighlight>

<div lang="en" dir="ltr" class="mw-content-ltr">
=== Creating images with Nix ===
</div>

<div lang="en" dir="ltr" class="mw-content-ltr">
==== Building a docker image with nixpkgs ====
</div>
<div lang="en" dir="ltr" class="mw-content-ltr">
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:
</div>

<syntaxhighlight lang="nix">
buildImage {
  name = "redis";
  tag = "latest";

fromImage = someBaseImage;
  fromImageName = null;
  fromImageTag = "latest";

copyToRoot = pkgs.buildEnv {
    name = "image-root";
    paths = [ pkgs.redis ];
    pathsToLink = [ "/bin" ];
  };

runAsRoot = ''
    #!${pkgs.runtimeShell}
    mkdir -p /data
  '';

config = {
    Cmd = [ "/bin/redis-server" ];
    WorkingDir = "/data";
    Volumes = { "/data" = { }; };
  };

diskSize = 1024;
  buildVMMemorySize = 512;
}
</syntaxhighlight>

<div lang="en" dir="ltr" class="mw-content-ltr">
More examples can be found in the [https://github.com/NixOS/nixpkgs/blob/master/pkgs/build-support/docker/examples.nix nixpkgs] repo.
</div>

<div lang="en" dir="ltr" class="mw-content-ltr">
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.
</div>

<div lang="en" dir="ltr" class="mw-content-ltr">
==== Reproducible image dates ====
</div>

<div lang="en" dir="ltr" class="mw-content-ltr">
The manual advises against using <code>created = "now"</code>, as that prevents images from being reproducible.
</div>

<div lang="en" dir="ltr" class="mw-content-ltr">
An alternative, if using [[flakes]], is to do <code>created = builtins.substring 0 8 self.lastModifiedDate</code>, which uses the commit date, and is therefore reproducible.
</div>

<div lang="en" dir="ltr" class="mw-content-ltr">
==== Calculating the sha256 for a pulled Docker image ====
</div>

<div lang="en" dir="ltr" class="mw-content-ltr">
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.
</div>

<div lang="en" dir="ltr" class="mw-content-ltr">
For instance, the SHA of the following image
</div>
<syntaxhighlight lang="nix">
pkgs.dockerTools.pullImage{
  imageName = "lnl7/nix";
  finalImageTag = "2.0";
  imageDigest = "sha256:632268d5fd9ca87169c65353db99be8b4e2eb41833b626e09688f484222e860f";
  sha256 = "1x00ks05cz89k3wc460i03iyyjr7wlr28krk7znavfy2qx5a0hfd";
};
</syntaxhighlight>

<div lang="en" dir="ltr" class="mw-content-ltr">
can be manually generated with the following shell commands
</div>

<syntaxhighlight lang="bash">
skopeo copy docker://lnl7/nix@sha256:632268d5fd9ca87169c65353db99be8b4e2eb41833b626e09688f484222e860f docker-archive:///tmp/image.tgz:lnl7/nix:2.0
</syntaxhighlight>

<syntaxhighlight lang="bash">
nix-hash --base32 --flat --type sha256 /tmp/image.tgz 
</syntaxhighlight>
<syntaxhighlight lang="shell">
1x00ks05cz89k3wc460i03iyyjr7wlr28krk7znavfy2qx5a0hfd
</syntaxhighlight>

<div lang="en" dir="ltr" class="mw-content-ltr">
==== Directly Using Nix in Image Layers ====
</div>

<div lang="en" dir="ltr" class="mw-content-ltr">
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].
</div>

<div lang="en" dir="ltr" class="mw-content-ltr">
This will significantly reduce data duplication and the time it takes to pull images.
</div>

<div lang="en" dir="ltr" class="mw-content-ltr">
=== Using Podman as an alternative ===
</div>

<div lang="en" dir="ltr" class="mw-content-ltr">
Podman is a daemonless container engine that can run Docker containers without elevated privileges. It can be used as a drop-in replacement for Docker in many cases:
</div>
<syntaxhighlight lang="nix">
# Enable Podman in configuration.nix
virtualisation.podman = {
  enable = true;
  # Create the default bridge network for podman
  defaultNetwork.settings.dns_enabled = true;
};

# Optionally, create a Docker compatibility alias
programs.zsh.shellAliases = {
  docker = "podman";
};
</syntaxhighlight>

<div lang="en" dir="ltr" class="mw-content-ltr">
=== Changing Docker Daemon's Data Root ===
</div>

<div lang="en" dir="ltr" class="mw-content-ltr">
By default, the Docker daemon stores images, containers, and build context on the root file system. To use a different storage location, specify a new <code>data-root</code> in your configuration:
</div>
<syntaxhighlight lang="nix">
virtualisation.docker.daemon.settings = {
  data-root = "/some-place/to-store-the-docker-data";
};
</syntaxhighlight>

<div lang="en" dir="ltr" class="mw-content-ltr">
=== Docker Containers as systemd Services ===
</div>

<div lang="en" dir="ltr" class="mw-content-ltr">
You can run Docker containers as systemd services using the <code>oci-containers</code> module:
</div>
<syntaxhighlight lang="nix">
virtualisation.oci-containers = {
  # backend defaults to "podman"
  backend = "docker";
  containers = {
    foo = {
      # ...
    };
  };
};
</syntaxhighlight>

<div lang="en" dir="ltr" class="mw-content-ltr">
A more advanced example:
</div>
<syntaxhighlight lang="nix">
{ config, pkgs, ... }:

{
  config.virtualisation.oci-containers.containers = {
    hackagecompare = {
      image = "chrissound/hackagecomparestats-webserver:latest";
      ports = ["127.0.0.1:3010:3010"];
      volumes = [
        "/root/hackagecompare/packageStatistics.json:/root/hackagecompare/packageStatistics.json"
      ];
      cmd = [
        "--base-url"
        "\"/hackagecompare\""
      ];
    };
  };
}
</syntaxhighlight>

<div lang="en" dir="ltr" class="mw-content-ltr">
See [https://search.nixos.org/options?from=0&size=50&sort=alpha_asc&query=virtualisation.oci-containers oci-containers] for further options.
</div>

<div lang="en" dir="ltr" class="mw-content-ltr">
==== Usage ====
</div>
<div lang="en" dir="ltr" class="mw-content-ltr">
Unless otherwise specified, NixOS uses Podman to run OCI containers. Note that these are '''user-specific''', so running commands with or without sudo can change your output.
</div>

<div lang="en" dir="ltr" class="mw-content-ltr">
List containers
</div>
<syntaxhighlight lang="console">
# podman ps
</syntaxhighlight>
<div lang="en" dir="ltr" class="mw-content-ltr">
Update image
</div>
<syntaxhighlight lang="console">
# podman restart hackagecompare
</syntaxhighlight>
<div lang="en" dir="ltr" class="mw-content-ltr">
List images
</div>
<syntaxhighlight lang="console">
# podman ls
</syntaxhighlight>
<div lang="en" dir="ltr" class="mw-content-ltr">
Remove container
</div>
<syntaxhighlight lang="console">
# podman rm hackagecompare
</syntaxhighlight>
<div lang="en" dir="ltr" class="mw-content-ltr">
Remove image
</div>
<syntaxhighlight lang="console">
# podman rmi c0d9a5f58afe
</syntaxhighlight>
<div lang="en" dir="ltr" class="mw-content-ltr">
Update image
</div>
<syntaxhighlight lang="console">
# podman pull chrissound/hackagecomparestats-webserver:latest
</syntaxhighlight>
<div lang="en" dir="ltr" class="mw-content-ltr">
Run interactive shell in running container
</div>
<syntaxhighlight lang="console">
# podman exec -ti $ContainerId /bin/sh
</syntaxhighlight>

<div lang="en" dir="ltr" class="mw-content-ltr">
===== Exposing ports from the host =====
</div>
<div lang="en" dir="ltr" class="mw-content-ltr">
If you have a service running on the host that you want to connect to from the container, you could try connecting to the hostname <code>host.containers.internal</code> (or <code>host.docker.internal</code> for podman), but this might require additional networking setup
</div>

<div lang="en" dir="ltr" class="mw-content-ltr">
===== Exposing sockets from the host =====
</div>
<div lang="en" dir="ltr" class="mw-content-ltr">
If you have a service running on the host that exposes a socket, such as mariadb, you can also expose that socket to the container instead. You'll want to expose the folder the socket is in as a volume - so:
</div>
<syntaxhighlight lang="bash">
      volumes = [
        "/var/run/mysqld:/mysqld"
      ];
</syntaxhighlight>
<div lang="en" dir="ltr" class="mw-content-ltr">
to provide access to <code>/var/run/mysqld/mysqld.sock</code>
</div>

<div lang="en" dir="ltr" class="mw-content-ltr">
=== Running the docker daemon from nix-the-package-manager - not NixOS ===
</div>

<div lang="en" dir="ltr" class="mw-content-ltr">
This is not supported. You're better off installing the docker daemon [https://docs.docker.com/engine/install/ "the normal non-nix way"].
</div>

<div lang="en" dir="ltr" class="mw-content-ltr">
See the discourse discussion: [https://discourse.nixos.org/t/how-to-run-docker-daemon-from-nix-not-nixos/43413 How to run docker daemon from nix (not NixOS)] for more.
</div>

<div lang="en" dir="ltr" class="mw-content-ltr">
== Troubleshooting ==
</div>

<div lang="en" dir="ltr" class="mw-content-ltr">
=== Common issues ===
</div>

<div lang="en" dir="ltr" class="mw-content-ltr">
==== Cannot connect to the Docker daemon ====
</div>

<div lang="en" dir="ltr" class="mw-content-ltr">
If you encounter errors connecting to the Docker daemon, check that:
</div>
<div lang="en" dir="ltr" class="mw-content-ltr">
- The Docker service is running: `systemctl status docker`
</div>
<div lang="en" dir="ltr" class="mw-content-ltr">
- Your user is in the docker group: `groups | grep docker`
</div>
<div lang="en" dir="ltr" class="mw-content-ltr">
- You've logged out and back in after adding your user to the docker group
</div>

<div lang="en" dir="ltr" class="mw-content-ltr">
==== Storage space issues ====
</div>

<div lang="en" dir="ltr" class="mw-content-ltr">
When Docker uses too much disk space:
</div>
<syntaxhighlight lang="bash">
# Remove unused containers, networks, images, and volumes
docker system prune -a --volumes

# Configure Docker daemon to automatically prune in configuration.nix
virtualisation.docker.daemon.settings = {
  pruning = {
    enabled = true;
    interval = "24h";
  };
};
</syntaxhighlight>

<div lang="en" dir="ltr" class="mw-content-ltr">
==== Network conflicts ====
</div>

<div lang="en" dir="ltr" class="mw-content-ltr">
Docker's default subnet (`172.17.0.0/16`) might conflict with your existing network. Configure a different subnet in your `configuration.nix`:
</div>
<syntaxhighlight lang="nix">
virtualisation.docker.daemon.settings = {
  default-address-pools = [
    {
      base = "192.168.0.0/16";
      size = 24;
    }
  ];
};
</syntaxhighlight>

<div lang="en" dir="ltr" class="mw-content-ltr">
=== Cannot connect to public Wi-Fi, when using Docker ===
</div>

<div lang="en" dir="ltr" class="mw-content-ltr">
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 reported when trying to connect to the WIFIonICE of the Deutsche Bahn (DB). They use the <code>172.18.x.x</code> address range.
</div>

<div lang="en" dir="ltr" class="mw-content-ltr">
This can be resolved by changing the default address pool that Docker uses.
</div>
<syntaxhighlight lang="nix">
virtualisation.docker = {
  enable = true;
  daemon.settings = {
    "default-address-pools" = [
      { "base" = "172.27.0.0/16"; "size" = 24; }
    ];
  };
};
</syntaxhighlight>
<div lang="en" dir="ltr" class="mw-content-ltr">
Restarting the container or Docker might be required.
</div>

<div lang="en" dir="ltr" class="mw-content-ltr">
== References ==
</div>

[[Category:Applications]]
[[Category:Virtualization]]
[[Category:Cookbook]]
[[Category:Software]]
[[Category:Server]]
[[Category:Container]]