From 70d137383e59c5bf839586e086b823b3325b734e Mon Sep 17 00:00:00 2001
From: Maarten de Waard <maarten@greenhost.nl>
Date: Thu, 10 Feb 2022 14:49:43 +0100
Subject: [PATCH] add developer-specific instructions to docs/instructions.rst
and include them in the ToC
---
docs/index.rst | 8 ++++++-
docs/instructions.rst | 51 +++++++++++++++++++++++++++++++++++++++++++
2 files changed, 58 insertions(+), 1 deletion(-)
create mode 100644 docs/instructions.rst
diff --git a/docs/index.rst b/docs/index.rst
index a6c9c7c17..4401d8985 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -48,10 +48,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
diff --git a/docs/instructions.rst b/docs/instructions.rst
new file mode 100644
index 000000000..0df9f0c30
--- /dev/null
+++ b/docs/instructions.rst
@@ -0,0 +1,51 @@
+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 container:
+
+.. 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 container 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.
--
GitLab