[incubator-devlake-website] branch kw-4545-upgrade-doc created (now f9dbf1321e)

[kl...@apache.org]

This is an automated email from the ASF dual-hosted git repository.

klesh pushed a change to branch kw-4545-upgrade-doc
in repository https://gitbox.apache.org/repos/asf/incubator-devlake-website.git


      at f9dbf1321e docs: add upgrade doc

This branch includes the following new commits:

     new f9dbf1321e docs: add upgrade doc

The 1 revisions listed above as "new" are entirely new to this
repository and will be described in separate emails.  The revisions
listed as "add" were already present in the repository and have only
been added to this reference.

[incubator-devlake-website] 01/01: docs: add upgrade doc

[kl...@apache.org]

This is an automated email from the ASF dual-hosted git repository.

klesh pushed a commit to branch kw-4545-upgrade-doc
in repository https://gitbox.apache.org/repos/asf/incubator-devlake-website.git

commit f9dbf1321e096857083954e02db0dea605c4a7b9
Author: Klesh Wong <zh...@merico.dev>
AuthorDate: Wed Mar 8 14:16:26 2023 +0800

    docs: add upgrade doc
    
      Closes apache/incubator-devlake#4545
---
 docs/GettingStarted/Upgrade.md       | 29 +++++++++++++++++++++++++++++
 docs/Troubleshooting/Installation.md |  5 ++++-
 2 files changed, 33 insertions(+), 1 deletion(-)

diff --git a/docs/GettingStarted/Upgrade.md b/docs/GettingStarted/Upgrade.md
new file mode 100644
index 0000000000..7cf3e650e4
--- /dev/null
+++ b/docs/GettingStarted/Upgrade.md
@@ -0,0 +1,29 @@
+---
+title: "Upgrade"
+sidebar_position: 9
+description: How to upgrade your Apache DevLake to a newer version
+---
+
+
+## Preknowledge
+
+To upgrade an existing Apache Devlake instance to a newer version, there are 2 things have to be taken care of:
+
+1. Migrate the database including table schema and records to the required state.
+   Starting from [Release v0.10.0 · apache/incubator-devlake](https://github.com/apache/incubator-devlake/releases/tag/v0.10.0),
+   The Db migration was introduced to upgrade the existing database automatically, normally you don't need to do anything for the database. However, keep in mind the migration is one-way only, **downgrade is not supported**. You must back up your database if safety is your concern.
+2. Preserve your configuration.
+   Configuration refers to the settings control or impact the application behavior, Apache DevLake reads
+   and **writes** those settings from/to the `.env` file. A safe way to back up your configuration is to log into your `devlake` container and dump the file somewhere else. The file path in the container is `/app/.env` or `/app/config/.env` if you were using `helm`, unless the `ENV_PATH` Environment Variable was specified. 
+   The most important setting of all is the `ENCODE_KEY` generated by the `devlake` on the first boot, it is used to encrypt sensitive information (tokens/secrets) in the database. It is crucial to preserve the key if you decided to deploy a new instance while keeping the existing database.
+
+## Possible Approaches
+
+### Approach 1: Update the image tags to a newer version
+
+This is recommended way to upgrade your instance, it is the easiest way to go. However, the `docker-compose.yml` or `helm` might change over time, you may have to adopt these changes manually or opt for the next approach
+
+### Approach 2: Deploy a new instance while keeping the configuration
+
+1. Dump the `.env` file from the existing `devlake` container and shut it down
+2. Fire up the new container with the `.env` file mounted to the correct path
\ No newline at end of file
diff --git a/docs/Troubleshooting/Installation.md b/docs/Troubleshooting/Installation.md
index 65b7b05861..472ed091ac 100644
--- a/docs/Troubleshooting/Installation.md
+++ b/docs/Troubleshooting/Installation.md
@@ -5,7 +5,10 @@ description: >
   Installation Troubleshooting
 ---
 
-WIP
+### Seeing `panic: invalid encKey` error after upgrade
+
+The reason it happens is the `devlake` is trying to decrypt data in the database with the wrong key.
+Please check the [Upgrade](../GettingStarted/Upgrade.md) for more detail.
 
 ## None of them solve your problem?