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](https://www.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 `apt`y 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](#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.