3.9 KiB

Raw Blame History

Testing the installer

Zulip's install process is tested as part of its continuous integrations suite, but that only tests the most common configurations; when making changes to more complicated installation options, Zulip provides tooling to repeatedly test the installation process in a clean environment each time.

Configuring

Using the test installer framework requires a Linux operating system; it will not work on WSL, for instance. It requires at least 3G of RAM, in order to accommodate the VMs and the steps which build the release assets.

To begin, install the LXC toolchain:

sudo apt-get install lxc lxc-utils

All LXC commands (and hence many parts of the test installer) will need to be run as root.

Running a test install

Build and unpack a release tarball

You only need to do this step once per time you work on a set of changes, to refresh the package that the installer uses. The installer doesn't work cleanly out of a source checkout; it wants a release checkout, so we build a tarball of one of those first:

./tools/build-release-tarball test-installer

This will produce a file in /tmp, which it will print out the path to as the last step; for example, /tmp/tmp.fepqqNBWxp/zulip-server-test-installer.tar.gz

Next, unpack that file into a local directory; we will make any changes we want in our source checkout and copy them into this directory. The test installer needs the release directory to be named zulip-server, so we rename it and move it appropriately. In the first line, you'll need to substitute the actual path that you got for the tarball, above:

tar xzf /tmp/tmp.fepqqNBWxp/zulip-server-test-installer.tar.gz
mkdir zulip-test-installer
mv zulip-server-test-installer zulip-test-installer/zulip-server

You should delete and re-create this zulip-test-installer directory (using these steps) if you are working on a different installer branch, or a significant time has passed since you last used it.

Test an install

The test-install tooling takes a distribution release name (e.g., "jammy"), the path to an unpacked release directory or tarball, and then any of the normal options you want to pass down into the installer.

For example, to test an install onto Ubuntu 22.04 "Jammy", we might call:

sudo ./tools/test-install/install \
  -r jammy \
  ./zulip-test-installer/ \
  --hostname=zulip.example.net \
  --email=username@example.net

The first time you run this command for a given distribution, it will build a "base" image for that to use on subsequent times; this will take a while.

See running containers after installation

Regardless of if the install succeeds or fails, it will stay running so you can inspect it. You can see all of the containers which are running, and their randomly-generated names, by running:

sudo lxc-ls -f

Connect to a running container

After using lxc-ls to list containers, you can choose one of them and connect to its terminal:

sudo lxc-attach --clear-env -n zulip-install-jammy-PUvff

Stopping and destroying containers

To destroy all containers (but leave the base containers, which speed up the initial install):

sudo ./tools/test-install/destroy-all -f

To destroy just one container:

sudo lxc-destroy -f -n zulip-install-jammy-PUvff

Iterating on the installer

Iterate on the installer by making changes to your source tree, copying them into the release directory, and re-running the installer, which will start up a new container. Here, we update just the scripts and puppet directories of the release directory:

rsync -az scripts puppet zulip-test-installer/zulip-server/

sudo ./tools/test-install/install \
 -r jammy \
 ./zulip-test-installer/ \
 --hostname=zulip.example.net \
 --email=username@example.net

3.9 KiB Raw Blame History