Distrobox: Difference between revisions

(16 intermediate revisions by 6 users not shown)

Line 1:

[https://distrobox.it Distrobox] offers you to use any linux distribution inside your terminal as a simple wrapper for Docker.

[https://distrobox.it Distrobox] offers you to use any linux distribution inside your terminal as a simple wrapper for [[Podman]], [[Docker]] or Lilipod.

== Setup ==

Distrobox uses Docker internally to fetch and run system images. Easily get started by enabling Podman with Docker-compatibility mode.<syntaxhighlight lang="nix">

virtualisation.podman = {

enable = true;

dockerCompat = true;

};

environment.systemPackages = [ pkgs.distrobox ];

</syntaxhighlight>

== Usage ==

Setup container with latest [https://archlinux.org ~~Archlinux~~] image

Setup container with latest [https://archlinux.org Arch Linux] image

# distrobox create --name archlinux --init --image archlinux:latest

distrobox create --root --name archlinux --init --image archlinux:latest

</syntaxhighlight>

Enter ~~Archlinux~~ container

Enter Arch Linux container

# distrobox enter ~~archlinux~~

distrobox enter --root archlinux

</syntaxhighlight>

For further usage, please refer to the [https://distrobox.it/#distrobox Distrobox] documentation.

== Tips and tricks ==

=== Using different architecture ===

The following example will run an Ubuntu container with a different architecture than the host, in this case arm64.

Add following line to your system configuration, apply it and then reboot the system.<syntaxhighlight lang="nix">

boot.binfmt.emulatedSystems = [ "aarch64-linux" ];

</syntaxhighlight>Run a Debian container with arm64 architecture<syntaxhighlight lang="nix">

sudo podman run --rm --privileged multiarch/qemu-user-static --reset -p yes

distrobox create -n debian --image arm64v8/debian

distrobox enter debian

</syntaxhighlight>

=== "potentially insufficient UIDs and GUIDs" error ===

When setting up containers that do not run as root, as <code>podman</code> does by default, you may see an error along the following lines: (this example uses podman, lilipod has a different error)

# distrobox create container

...

Error: copying system image from manifest list: writing blob: adding layer with blob ...:

unpacking failed (error: exit status 1;

output: potentially insufficient UIDs or GIDs available in user namespace (requested 1000:1000 for /home/container): Check /etc/subuid and /etc/subgid if configured locally and run "podman system migrate": lchown /home/container: invalid argument)

</syntaxhighlight>

To fix it, adding the following to your config might help:

users.users.YOURUSERNAME = {

extraGroups = [ "podman" ];

subGidRanges = [

{

count = 65536;

startGid = 1000;

}

];

subUidRanges = [

{

count = 65536;

startUid = 1000;

}

];

};

</syntaxhighlight>

Rebuild your system, run <code>podman system migrate</code>, and try creating the distrobox container again.

=== Exposing your profile ===

If you get errors like <code>/home/user/.zshenv:.:2: no such file or directory: /etc/profiles/per-user/user/etc/profile.d/hm-session-vars.sh</code> or <code>_atuin_preexec: command not found: atuin</code> that is because your shell init is referencing paths that are not accessible to Distrobox. By default, Distrobox only gets access to your home directory. You can mount additional volumes with <code>distrobox create --volume /your/custom/volume/path</code>, but it is more convenient to define defaults in <code>distrobox.conf</code>: <syntaxhighlight lang="nix">environment.etc."distrobox/distrobox.conf".text = ''

container_additional_volumes="/nix/store:/nix/store:ro /etc/profiles/per-user:/etc/profiles/per-user:ro /etc/static/profiles/per-user:/etc/static/profiles/per-user:ro"

''; </syntaxhighlight>

[[Category:Applications]]

[[Category:Container]]

@@ Line 1: / Line 1: @@
-[https://distrobox.it Distrobox] offers you to use any linux distribution inside your terminal as a simple wrapper for Docker.
+[https://distrobox.it Distrobox] offers you to use any linux distribution inside your terminal as a simple wrapper for [[Podman]], [[Docker]] or Lilipod.
+== Setup ==
+Distrobox uses Docker internally to fetch and run system images. Easily get started by enabling Podman with Docker-compatibility mode.<syntaxhighlight lang="nix">
+virtualisation.podman = {
+  enable = true;
+  dockerCompat = true;
+};
+environment.systemPackages = [ pkgs.distrobox ];
+</syntaxhighlight>
 == Usage ==
-Setup container with latest [https://archlinux.org Archlinux] image
+Setup container with latest [https://archlinux.org Arch Linux] image
 <syntaxhighlight lang="console">
-# distrobox create --name archlinux --init --image archlinux:latest
+distrobox create --root --name archlinux --init --image archlinux:latest
 </syntaxhighlight>
-Enter Archlinux container
+Enter Arch Linux container
 <syntaxhighlight lang="console">
-# distrobox enter archlinux
+distrobox enter --root archlinux
+</syntaxhighlight>
+For further usage, please refer to the [https://distrobox.it/#distrobox Distrobox] documentation.
+== Tips and tricks ==
+=== Using different architecture ===
+The following example will run an Ubuntu container with a different architecture than the host, in this case arm64.
+Add following line to your system configuration, apply it and then reboot the system.<syntaxhighlight lang="nix">
+boot.binfmt.emulatedSystems = [ "aarch64-linux" ];
+</syntaxhighlight>Run a Debian container with arm64 architecture<syntaxhighlight lang="nix">
+sudo podman run --rm --privileged multiarch/qemu-user-static --reset -p yes
+distrobox create -n debian --image arm64v8/debian
+distrobox enter debian
 </syntaxhighlight>
+=== "potentially insufficient UIDs and GUIDs" error ===
+When setting up containers that do not run as root, as <code>podman</code> does by default, you may see an error along the following lines: (this example uses podman, lilipod has a different error)
+<syntaxhighlight lang="console">
+# distrobox create container
+...
+Error: copying system image from manifest list: writing blob: adding layer with blob ...:
+unpacking failed (error: exit status 1;
+output: potentially insufficient UIDs or GIDs available in user namespace (requested 1000:1000 for /home/container): Check /etc/subuid and /etc/subgid if configured locally and run "podman system migrate": lchown /home/container: invalid argument)
+</syntaxhighlight>
+To fix it, adding the following to your config might help:
+<syntaxhighlight lang="nix">
+  users.users.YOURUSERNAME = {
+      extraGroups = [ "podman" ];
+      subGidRanges = [
+          {
+              count = 65536;
+              startGid = 1000;
+          }
+      ];
+      subUidRanges = [
+          {
+              count = 65536;
+              startUid = 1000;
+          }
+      ];
+  };
+</syntaxhighlight>
+Rebuild your system, run <code>podman system migrate</code>, and try creating the distrobox container again.
+=== Exposing your profile ===
+If you get errors like <code>/home/user/.zshenv:.:2: no such file or directory: /etc/profiles/per-user/user/etc/profile.d/hm-session-vars.sh</code> or <code>_atuin_preexec: command not found: atuin</code> that is because your shell init is referencing paths that are not accessible to Distrobox. By default, Distrobox only gets access to your home directory. You can mount additional volumes with <code>distrobox create --volume /your/custom/volume/path</code>, but it is more convenient to define defaults in <code>distrobox.conf</code>: <syntaxhighlight lang="nix">environment.etc."distrobox/distrobox.conf".text = ''
+  container_additional_volumes="/nix/store:/nix/store:ro /etc/profiles/per-user:/etc/profiles/per-user:ro /etc/static/profiles/per-user:/etc/static/profiles/per-user:ro"
+''; </syntaxhighlight>
 [[Category:Applications]]
 [[Category:Container]]