Motivation

We want users to be able to use a variety of erlang programs, which means they need to know how to install an erlang runtime that can run our programs. On any given day this will have a well defined answer, but as erlang changes, and as our dependencies change, the exact installation process might change too. In order to reliably recreate the experience of a new user, on a variety of possible distributions, we create a collection of chroot environments, one for each distribution we want to document, and then use those chroot environments to develop and maintain install scripts.

These install scripts will check every dependency needed, even on a totally fresh installation of the corresponding linux distribution, because that is exactly what the chroot environments will be. This means that the install scripts will work on any install, whether it has been used for a long time, or whether it is also a fresh install, if you're mining on a VPS, or custom hardware, or whatever else.

Usage

At the moment there is only one distribution, Debian, which you can test in the chroot_sandboxes/debian subdirectory. From there you can run a variety of posix shell scripts to create, enter, and delete chroot environments.

Create Environment

cd into debian and run sudo ./create_environment to automatically download debootstrap from debian.org, and create a debian system with it. If you already have debootstrap installed, then that version will be used instead. debootstrap can be installed with apt, if you are already on an apty system. Running make install in debian/debootstrap is not recommended, since your distribution's package manager won't be able to uninstall it for you.

A minimal debian system will be created under debian/clean_environment, and then copied over to debian/test_environment. This way if you run sudo ./create_environment again, instead of downloading the whole distribution again, it can simply overwrite test_environment with a new copy, allowing rapid iteration of install scripts, run on totally fresh systems every time.

The script also sets up the mount points and /tmp directory in debian/test_environment, each time that it is copied from debian/clean_environment. This means debian/clean_environment is always an ordinary file hierarchy with no mount points, that can be recursively deleted, whereas debian/test_environment needs to be handled more carefully, see Destroy Environment for instructions.

Finally, the script will copy all install scripts in debian/install_scripts into the chroot environment, and perform the chroot itself. The chroot is instructed to run install_scripts/user_setup with this new root directory, and this script will install sudo, create a user with passwordless sudo rights, and su into that user. You can then freely test whatever scripts you want as that user, and leave the environment.

If you don't want to do anything interactive as that user, but instead want to run a single script and then exit, pass that script and its arguments to sudo ./create_environment and they will be passed down into the chroot environment, and run instead of the default /bin/bash that is normally run by su. Remember that the command will be run inside the chroot environment, with /home/user as the working directory, so the script will need to be accessed relative to that. e.g. sudo ./create_environment ./install_scripts/your_script or sudo ./create_environment ~/install_scripts/your_script.

Opening Windows

To access an X11 server, clients need two things, access to /tmp/.X11-unix, and authorisation in X11's "access control" model. The former is automatically bound by the create_environment script, but to get the latter you will need to change the access control yourself. On a single-user device the simplest way to do this is to disable X11 access control altogether, using xhost +, but if for some reason you are testing these install scripts on a multi-user system, you'll want to find some way to protect your X11 server from other users, while still allowing your chroot host to access it.

Once you have disabled access control, any X11 applications you like can be installed with apt or zx, and run, and the windows will open in your window manager, despite still being attached to the chroot. This means different programs can be installed, configured, and run, without access to any of the parent system's configs, allowing us not only to test that we have all the dependencies needed to run the X11 application, but also to test any configurations of the application that we might want to do automatically, from that script. (e.g. adding realms to zx, creating default wallets, whatever.)

Destroy Environment

The create_environment and enter_environment scripts try to clean up the mounts that they create, and the mounts will all disappear on reboot, but just in case they are still present, you can run sudo ./cleanup to delete the test_environment safely. If you want to delete both environments and debootstrap in one go, then sudo ./cleanup everything will safely unmount test_environment and then delete all three directories.

cleanup has other options too. For example, if you want to chroot into the environment as root, you can manually add the mount points back using sudo ./cleanup add_mounts, and then chroot in yourself. There is also sudo ./cleanup mounts to remove the mounts manually without deleting test_environment.

Reuse an Existing Environment

If you want to enter an environment again, run sudo ./enter_environment, and it will chroot into the environment without deleting and recreating it, without installing sudo again, and without creating a new user.

To run a script, just like with create_environment, you can pass arguments, as long as the paths involved are relative to the new root and home directory. e.g. sudo ./enter_environment ~/install_scripts/your_script.

If you reboot your machine, the mount points of the chroot environment will be missing, (unless you put them in your system-wide fstab, you sicko,) but sudo ./enter_environment will detect this and add the mount points back automatically.

If you are iterating an install script, then it's usually more useful to just run the whole thing again using create_environment, but if you want to compose multiple operations together in a script outside of the chroot, or if you want to enter an interactive environment again after running some more expensive script, then this might be useful. For example, you could test create_environment itself on other distributions, by running it inside of a chroot.