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`.

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.