This is an automated email from the ASF dual-hosted git repository.
hez pushed a commit to branch kw-4545-upgrade-doc
in repository https://gitbox.apache.org/repos/asf/incubator-devlake-website.git
The following commit(s) were added to refs/heads/kw-4545-upgrade-doc by this
push:
new 6673439de3 feat: polish the .env file section
6673439de3 is described below
commit 6673439de374688d6c329bd3e60bd444af2d6b1a
Author: Hezheng Yin <[email protected]>
AuthorDate: Tue Mar 14 00:12:14 2023 -0400
feat: polish the .env file section
---
docs/GettingStarted/Upgrade.md | 32 ++++++++++++++++++--------------
docs/Troubleshooting/Installation.md | 2 +-
2 files changed, 19 insertions(+), 15 deletions(-)
diff --git a/docs/GettingStarted/Upgrade.md b/docs/GettingStarted/Upgrade.md
index 717d42938b..dc836933c6 100644
--- a/docs/GettingStarted/Upgrade.md
+++ b/docs/GettingStarted/Upgrade.md
@@ -4,21 +4,9 @@ sidebar_position: 9
description: How to upgrade your Apache DevLake to a newer version
---
-
-## Preknowledge
-
-To upgrade an existing Apache Devlake deployment to a newer version, please
note two things:
-
-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 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.
-
## 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.
@@ -26,4 +14,20 @@ This is recommended way to upgrade your instance, it is the
easiest way to go. H
### 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
\ No newline at end of file
+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 d10682d740..eb176fc18b 100644
--- a/docs/Troubleshooting/Installation.md
+++ b/docs/Troubleshooting/Installation.md
@@ -7,7 +7,7 @@ description: >
### `panic: invalid encKey` error
-The cause is the `devlake` trying to decrypt data in the database with the
wrong key.
+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?
