Merge branch '1127-update-zulip-fork' into 'main'

Resolve "Update Zulip Fork"

Closes #1127

See merge request stackspin/stackspin!812

docs/index.rst

@@ -49,10 +49,16 @@ For more information, go to `the Stackspin website`_.
    troubleshooting
    security
 
+.. toctree::
+   :maxdepth: 2
+   :caption: For Developers
+
+   design
+   instructions
+
 .. toctree::
    :maxdepth: 2
    :caption: Reference
 
    reference
    comparable_projects
-   design

docs/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.

flux2/apps/zulip/zulip-values-configmap.yaml

@@ -7,9 +7,10 @@ metadata:
 data:
   values.yaml: |
     image:
+      # Overrides the image to a version on Zulip's `main` branch because the
+      # most recent stable version (4.9) does not support OIDC (we need 5)
       repository: open.greenhost.net:4567/stackspin/stackspin/zulip
-      # Overrides the image tag whose default is the chart appVersion.
-      tag: "45062f8be0"
+      tag: "5e90b32f40"
 
     ingress:
       enabled: true
@@ -115,5 +116,8 @@ data:
         create-realm.sh: |
           #!/bin/bash
           #
-          # Creates a realm with the admin email and username
+          # Download create_realm.py from PR #20075
+          su zulip -c 'curl https://raw.githubusercontent.com/zulip/zulip/6b4b71ad04af551da6bea84127e0cd99cad434be/zerver/management/commands/create_realm.py -o /home/zulip/deployments/current/zerver/management/commands/create_realm.py'
+
+          # Use create_realm.py to create a realm with the admin email and username
           su zulip -c '/home/zulip/deployments/current/manage.py create_realm stackspin "${admin_email}" Admin --password "${admin_password}" --disable-invite-required'