This is an automated email from the ASF dual-hosted git repository.
klesh pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/incubator-devlake-website.git
The following commit(s) were added to refs/heads/main by this push:
new 7d07a72304 docs: add upgrade doc (#461)
7d07a72304 is described below
commit 7d07a72304e257b8c6a197b1385c0cf05c207b65
Author: Klesh Wong <[email protected]>
AuthorDate: Tue Mar 14 15:52:45 2023 +0800
docs: add upgrade doc (#461)
* docs: add upgrade doc
Closes apache/incubator-devlake#4545
* fix: refine according to feedback
* fix: link to upgrade doc
* feat: polish the .env file section
---------
Co-authored-by: Hezheng Yin <[email protected]>
---
docs/GettingStarted/Upgrade.md | 33 +++++++++++++++++++++++++++++++++
docs/Troubleshooting/Installation.md | 5 ++++-
2 files changed, 37 insertions(+), 1 deletion(-)
diff --git a/docs/GettingStarted/Upgrade.md b/docs/GettingStarted/Upgrade.md
new file mode 100644
index 0000000000..dc836933c6
--- /dev/null
+++ b/docs/GettingStarted/Upgrade.md
@@ -0,0 +1,33 @@
+---
+title: "Upgrade"
+sidebar_position: 9
+description: How to upgrade your Apache DevLake to a newer version
+---
+
+## Upgrade Options
+
+
+### Option 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 the `helm chart` might change over time
(e.g., a new persistent volume is required for new feature to work properly),
you may have to adopt these changes manually or opt for the next option.
+
+### Option 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
+
+
+## Two Things to Note
+
+
+1. Database migration.
+ Starting from [Release v0.10.0 ยท
apache/incubator-devlake](https://github.com/apache/incubator-devlake/releases/tag/v0.10.0),
+ DevLake auto-migrates your table schema and records to the newer version.
Normally you don't need to do anything for the migration. However, please keep
in mind the migration is one-way only, **downgrade is not supported**. Please
consider backing up your database if there's any data you'd like to keep.
+2. Preserve the `.env` file.
+ DevLake reads and writes some configurations from/to the `.env` file. An
example is the `ENCODE_KEY` generated by the `devlake` container during the
first boot. `ENCODE_KEY` is used to encrypt sensitve information in the
database, e.g., personal access tokens and passwords. Normally, users don't
need to worry about the `.env` file during upgrade. But in the following
scenarios, users may want to back up the `.env` file:
+
+ 1. When a user deploys a new DevLake instance and points it to an existing
cloud managed database. Since the existing database is encrypted with the
`ENCODE_KEY` in the `.env` file, the user needs to port the old `.env` file to
the new DevLake instance.
+ 2. When a user deploys DevLake to AWS ECS but did not properly persist the
`.env` file.
+
+ To back up `.env` file, users can log into the `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 is specified).
+
diff --git a/docs/Troubleshooting/Installation.md
b/docs/Troubleshooting/Installation.md
index 65b7b05861..eb176fc18b 100644
--- a/docs/Troubleshooting/Installation.md
+++ b/docs/Troubleshooting/Installation.md
@@ -5,7 +5,10 @@ description: >
Installation Troubleshooting
---
-WIP
+### `panic: invalid encKey` error
+
+The cause is the `devlake` container trying to decrypt data in the database
with the wrong key.
+Please check the [GettingStarted/Upgrade](../GettingStarted/Upgrade.md) doc
for more detail.
## None of them solve your problem?
