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.

Destroy Environment

Because chroot environments require multiple mounted directories to work, you can't simply rm -r a chroot environment you created, or the repository as a whole, without unmounting the mount points first. If you have rebooted your machine since setting up the chroot environments, then you don't need to worry, part or all of the repository can be straight-forwardly deleted, but if you are working with the repository and want to delete something yourself, there are two helper scripts that can be used to clean up the mount points and chroot environments properly.

First sudo ./destroy_environment will unmount and delete test_environment, allowing you to remove an old environment without immediately creating a new one. Anything else in the repository can be straight-forwardly deleted with sudo rm -r, so with this you can put the repository in whatever state you want it to be in.

If you want to conveniently remove all debian/debootstrap tools added, then sudo ./clean_everything will run destroy_environment, and then delete clean_environment and debootstrap for you, as well as debootstrap.tar.gz if that got left behind by accident. Think of this as the 'distclean', for one specific distribution.

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.