instructions.rst

Instructions
============

This document contains instructions for a few tasks that you might have to do as
a Stackspin developer.

Building a new version of Zulip
-------------------------------

As long as Zulip version 5 is not released yet, you need to build it from the
source code's ``main`` branch every once in a while. In order to do so, you need
the following:

1. The commit ref of the version of the `Zulip repository
   <https://github.com/zulip/zulip>`__ you want to build, e.g.
   ``5e90b32f40ad45d59e00a4e5c08cc6f180e04d30``
2. An abbreviated version of the commit ref. We take the first ten characters of
   the whole ref, ``5e90b32f40`` in our example.
3. A local copy of our fork of `the docker-zulip repository
   <https://github.com/greenhost/docker-zulip>`__ (at least until `our pull
   request is merged <https://github.com/zulip/docker-zulip/pull/325>`__).

   This is necessary because we have added the ``SOCIAL_AUTH_OIDC_ENABLED_IDPS``
   variable to the ``entrypoint.sh`` docker entrypoint script. Without our
   changes, setting OIDC settings through environment variables is impossible.

Once you have these two things, you can run the following build command to build
the image:

.. code::

   docker build \
     --build-arg "ZULIP_GIT_REF=5e90b32f40ad45d59e00a4e5c08cc6f180e04d30" \
     -t open.greenhost.net:4567/stackspin/stackspin/zulip:5e90b32f40 \
     .

The build argument ZULIP_GIT_REF tells the Dockerfile to use that ref when
checking out and building Zulip. The tag is necessary so you can push the new
Zulip image to our registry after building with the following command:

.. code::

   docker push open.greenhost.net:4567/stackspin/stackspin/zulip:5e90b32f40

Once the push is completed, you can edit the tag in
``flux2/apps/zulip/zulip-values-configmap.yaml`` and create a PR to update Zulip
in Stackspin.

Once our PR has been merged **and** Zulip version 5 has been released, this
guide is obsolete and Stackspin can use docker images as provided by Zulip on
Docker hub.