chroot_sandboxes/README.md

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.