From 29c9aefd48a3e187e8f40782e55242cf396d1c92 Mon Sep 17 00:00:00 2001
From: Maarten de Waard <maarten@greenhost.nl>
Date: Thu, 12 Aug 2021 17:53:45 +0200
Subject: [PATCH] update upgrade docs

---
 docs/upgrading.rst | 24 +++++++++++++++---------
 1 file changed, 15 insertions(+), 9 deletions(-)

diff --git a/docs/upgrading.rst b/docs/upgrading.rst
index 7a543d70e..6d9f8a0c4 100644
--- a/docs/upgrading.rst
+++ b/docs/upgrading.rst
@@ -4,8 +4,8 @@ Upgrading OpenAppStack
 Upgrading to 0.7.0
 ------------------
 
-Because of [problems with Helm and secret
-management](https://open.greenhost.net/openappstack/openappstack/-/issues/891)
+Because of `problems with Helm and secret management
+<https://open.greenhost.net/openappstack/openappstack/-/issues/891>`__
 we had to move away from using a helm chart for secrets, and now use scripts
 that run during installation to manage secrets. Because we have removed the
 ``oas-secrets`` helm chart, Flux will try to remove the secrets that it has
@@ -14,7 +14,7 @@ from ``v0.6`` to ``v0.7``!**
 
 To back-up your secrets, run the following script: 
 
-.. code::bash
+.. code:: bash
 
    bash
    #!/usr/bin/env bash
@@ -35,11 +35,15 @@ To back-up your secrets, run the following script:
 This script assumes you have all applications enabled. You might get an error
 like: 
 
-.. code::bash
+.. code:: bash
 
    Error from server (NotFound): secrets "oas-wekan-variables" not found
 
-This is not a problem.
+This is not a problem, but it *does* mean you need to add an oauth secret for
+Wekan to the file ``secrets-backup/oas-oauth-variables.yaml``. Copy the
+wordpress line, rename the field to ``wordpress_oauth_client_secret`` and enter
+a different random password. Make sure to base64 encode it (``echo "<your random
+password>" | base64``).
 
 This script creates a directory called ``secrets-backup`` and places the secrets
 that have been generated by Helm in it as ``yaml`` files.
@@ -56,7 +60,7 @@ because important secrets do not exist anymore.
 As soon as the ``oas-secrets`` helmrelease does not exist anymore, you can run
 the following code:
 
-.. code::bash
+.. code:: bash
 
    #!/usr/bin/env bash
 
@@ -75,14 +79,16 @@ the following code:
 Again this script assumes you have all applications installed. If you get the
 following error, you can ignore it:
 
-.. code::bash
+.. code:: bash
 
    error: error validating "STDIN": error validating data: [apiVersion not set, kind not set]; if you choose to ignore these errors, turn validation off with --validate=false
 
 Now Flux should succeed in finishing the update. Some helmreleases or
 kustomizations might have already failed because the secrets did not exist. Once
 failed, you can retrigger reconciliation of a kustomization using the commands
-``flux reconcile kustomization ...`` or ``flux reconcile helmrelease ...``.
+``flux reconcile kustomization ...`` or ``flux reconcile helmrelease ...``. This
+can take quite a while (over an hour some times), because Flux waits for some
+long timeouts before giving up and re-starting a reconciliation.
 
 Some errors we've seen during our own upgrade process, and how to solve them
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -147,7 +153,7 @@ production.
 Upgrading from 0.4.0 to 0.5.0
 -----------------------------
 
-Unfortunatly we can’t ensure a smooth upgrade for this version neither.
+Unfortunately we can’t ensure a smooth upgrade for this version neither.
 Please read the section below on how to do an upgrade by installing a
 the new OAS version from scratch after backing up your data.
 
-- 
GitLab