config/containers-and-vms/chroot: create more detailed chroot guide

- based on the section of installation/musl
- remove proot
- add xchroot and bwrap
- mention flatpak and OCI containers

supercedes:
- closes #300
- closes #610

Author: classabbyamp

src/SUMMARY.md

@@ -65,6 +65,7 @@
    - [External Applications](./config/external-applications.md)
    - [Printing](./config/print/index.md)
    - [Containers and Virtual Machines](./config/containers-and-vms/index.md)
+      - [Chroots and Containers](./config/containers-and-vms/chroot.md)
       - [libvirt](./config/containers-and-vms/libvirt.md)
       - [LXC](./config/containers-and-vms/lxc.md)
    - [OpenPGP](./config/openpgp.md)

src/config/containers-and-vms/chroot.md

@@ -0,0 +1,114 @@
+# Creating and using chroots and containers
+
+chroots and containers can be set up and used for many purposes, including:
+
+- running glibc software on musl (and vice versa)
+- running software in a more controlled or sandboxed environment
+- creating a rootfs for bootstrapping a system
+
+## Chroot Creation
+
+### xvoidstrap
+
+[`xvoidstrap(1)`](https://man.voidlinux.org/xvoidstrap.1) (from `xtools`) can be
+used to create the chroot:
+
+```
+# mkdir <chroot_dir>
+# XBPS_ARCH=<chroot_arch> xvoidstrap <chroot_dir> base-voidstrap <other_pkgs>
+```
+
+`<other_pkgs>` is only needed if you want to pre-install other packages in the
+chroot.
+
+### Manual Method
+
+Alternatively, this process can be done manually.
+
+Create a directory that will contain the chroot, then install a base system in
+it via the `base-voidstrap` package:
+
+```
+# mkdir -p "<chroot_dir>/var/db/xbps/keys"
+# cp -a /var/db/xbps/keys/* "<chroot_dir>/var/db/xbps/keys"
+# XBPS_ARCH=<chroot_arch> xbps-install -S -r <chroot_dir> -R <repository> base-voidstrap <other_pkgs>
+```
+
+The `<repository>` may [vary depending on
+architecture](../../xbps/repositories/index.md#the-main-repository).
+
+`<other_pkgs>` is only needed if you want to pre-install other packages in the
+chroot.
+
+## Chroot Usage
+
+### xchroot
+
+[`xchroot(1)`](https://man.voidlinux.org/xchroot.1) (from `xtools`) can be used
+to automatically set up and enter the chroot.
+
+### Manual Method
+
+Alternatively, this process can be done manually.
+
+If network access is required, copy `/etc/resolv.conf` into the chroot;
+`/etc/hosts` may need to be copied as well.
+
+Several directories then need to be mounted as follows:
+
+```
+# mount -t proc none <chroot_dir>/proc
+# mount -t sysfs none <chroot_dir>/sys
+# mount --rbind /dev <chroot_dir>/dev
+# mount --rbind /run <chroot_dir>/run
+```
+
+Use [chroot(1)](https://man.voidlinux.org/chroot.1) to change to the new root,
+then run programs and do tasks as usual. Once finished with the chroot, unmount
+the chroot using [umount(8)](https://man.voidlinux.org/umount.8). If any
+destructive actions are taken on the chroot directory without unmounting first,
+you may need to reboot to repopulate the affected directories.
+
+### Alternatives
+
+#### Bubblewrap
+
+[bwrap(1)](https://man.voidlinux.org/bwrap.1) (from the `bubblewrap` package)
+has additional features like the ability for sandboxing and does not require
+root access.
+
+`bwrap` is very flexible and can be used in many ways, for example:
+
+```
+$ bwrap --bind <chroot_dir> / \
+	--dev /dev \
+	--proc /proc \
+	--bind /sys /sys \
+	--bind /run /run \
+	--ro-bind /etc/resolv.conf /etc/resolv.conf \
+	--ro-bind /etc/passwd /etc/passwd \
+	--ro-bind /etc/group /etc/group \
+	<command>
+```
+
+In this example, you will not be able to add or edit users or groups. When
+running graphical applications with Xorg, you may need to also bind-mount
+`~/.Xauthority` or other files or directories.
+
+The [bwrap(1) manpage](https://man.voidlinux.org/bwrap.1) and the [Arch Wiki
+article](https://wiki.archlinux.org/title/Bubblewrap#Usage_examples) contain
+more examples of `bwrap` usage.
+
+#### Flatpak
+
+[Flatpak](../external-applications.md#flatpak) is a convenient option for
+running many applications, including graphical or proprietary ones, on both
+glibc and musl systems.
+
+#### Application Containers
+
+If a more integrated and polished solution is desired, Void also [provides OCI
+containers](https://github.com/void-linux/void-docker/pkgs/container/void-linux)
+that work with tools like [docker](https://www.docker.com) and
+[podman](https://man.voidlinux.org/podman.1). These containers do not require
+the creation of a chroot directory before usage.

src/config/containers-and-vms/index.md

@@ -5,5 +5,6 @@ software available on Void.
 
 ## Section Contents
 
+- [Chroots and Containers](./chroot.md)
 - [libvirt](./libvirt.md)
 - [LXC](./lxc.md)

src/installation/musl.md

@@ -29,28 +29,5 @@ compatibility.
 
 ### glibc chroot
 
-Software requiring glibc can be run in a glibc chroot.
-
-Create a directory that will contain the chroot, and install a base system in it
-via the `base-voidstrap` package. If network access is required, copy
-`/etc/resolv.conf` into the chroot; `/etc/hosts` may need to be copied as well.
-
-Several directories then need to be mounted as follows:
-
-```
-# mount -t proc none <chroot_dir>/proc
-# mount -t sysfs none <chroot_dir>/sys
-# mount --rbind /dev <chroot_dir>/dev
-# mount --rbind /run <chroot_dir>/run
-```
-
-Use [chroot(1)](https://man.voidlinux.org/chroot.1) to change to the new root,
-then run glibc programs as usual. Once you've finished using it, unmount the
-chroot using [umount(8)](https://man.voidlinux.org/umount.8).
-
-#### PRoot
-
-An alternative to the above is [proot(1)](https://man.voidlinux.org/proot.1), a
-user-space implementation of chroot, mount --bind, and binfmt_misc. By
-installing the `proot` package, unprivileged users can utilize a chroot
-environment.
+Software requiring glibc can be run in a glibc
+[chroot](../config/containers-and-vms/chroot.md).