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 91f1746f09 docs: highlight dashboard backup in the upgrade docs (#725)
91f1746f09 is described below
commit 91f1746f09ba2b953b232becabcd2c7f204cd26a
Author: Louis.z <[email protected]>
AuthorDate: Mon Feb 26 13:52:52 2024 +0800
docs: highlight dashboard backup in the upgrade docs (#725)
Co-authored-by: Startrekzky <[email protected]>
---
docs/GettingStarted/DockerComposeSetup.md | 11 ++++----
docs/GettingStarted/HelmSetup.md | 30 ++++++++++++----------
docs/GettingStarted/Upgrade.md | 8 ++++++
.../GettingStarted/DockerComposeSetup.md | 9 ++++---
.../version-v0.21/GettingStarted/HelmSetup.md | 30 ++++++++++++----------
.../version-v0.21/GettingStarted/Upgrade.md | 8 ++++++
6 files changed, 61 insertions(+), 35 deletions(-)
diff --git a/docs/GettingStarted/DockerComposeSetup.md
b/docs/GettingStarted/DockerComposeSetup.md
index 915b016cb5..8144808bdd 100644
--- a/docs/GettingStarted/DockerComposeSetup.md
+++ b/docs/GettingStarted/DockerComposeSetup.md
@@ -42,18 +42,19 @@ sidebar_position: 2
- We use [Grafana](https://grafana.com/) to visualize the DevOps
[data](/Overview/SupportedDataSources.md) and build dashboards.
- For how to customize and provision dashboards, please see our [Grafana
doc](../Configuration/Dashboards/GrafanaUserGuide.md).
-## Upgrade to a newer version
+## Upgrade
-Please note:
+:::caution
-Note 1: **Back up your Grafana dashboards** before upgrading if you have
modified/customized any dashboards. You can re-import these dashboards to
Grafana after the upgrade.
+- **Back up your Grafana dashboards** before upgrading if you have
modified/customized any dashboards. You can re-import these dashboards to
Grafana after the upgrade.
+- **If you are upgrading from DevLake v0.17.x or earlier versions to v0.18.x
or later versions**, you need to find the ENCODE_KEY value in the .env file of
devlake container, and assign the value to ENCRYPTION_SECRET via .env file or
environment variable in docker-compose.yml
-Note 2: **If you're upgrading from DevLake v0.17.x or earlier versions to
v0.18.x or later versions**, you need to find the ENCODE_KEY value in the .env
file of devlake container, and assign the value to ENCRYPTION_SECRET via .env
file or environment variable in docker-compose.yml
+:::
1. Run `docker-compose down` to stop services;
2. Download `docker-compose.yml` and `env.example` from the [latest
release](https://github.com/apache/incubator-devlake/releases).
3. Use the new `docker-compose.yml` and `env.example` to replace the old
`docker-compose.yml` and `.env`; Or if you have modified/customized values in
the old files, compare the new files with the old ones, adjust the old files
according to the new ones.
-4. If upgrading from earlier versions to v0.18.0+, set the ENCRYPTION_SECRET
environment variable in docker-compose.yml or .env file, refer to above Note 2.
+4. [Optional] If you are upgrading from earlier versions to v0.18.0+, set the
ENCRYPTION_SECRET environment variable in docker-compose.yml or .env file,
refer to the second caution.
5. Run `docker-compose up -d` to start DevLake services.
## FAQ
diff --git a/docs/GettingStarted/HelmSetup.md b/docs/GettingStarted/HelmSetup.md
index db010dbcf3..654e945a61 100644
--- a/docs/GettingStarted/HelmSetup.md
+++ b/docs/GettingStarted/HelmSetup.md
@@ -72,29 +72,33 @@ grafana by url `http://YOUR-NODE-IP:30091`
### Upgrade
-**Note:**
+:::caution
**Back up your Grafana dashboards** before upgrading if you have
modified/customized any dashboards. You can re-import these dashboards to
Grafana after the upgrade.
-**If you're upgrading from DevLake v0.17.x or earlier versions to v0.18.x or
later versions:**
+:::
-1. Copy the ENCODE_KEY value from /app/config/.env of the lake pod (e.g.
devlake-lake-0), and replace the <ENCRYPTION_SECRET> in the upgrade command
below.
-
-2. You may encounter the below error when upgrading because the built-in
grafana has been replaced by the official grafana dependency. So you may need
to delete the grafana deployment first.
-
-> Error: UPGRADE FAILED: cannot patch "devlake-grafana" with kind Deployment:
Deployment.apps "devlake-grafana" is invalid: spec.selector: Invalid value:
v1.LabelSelector{MatchLabels:map[string]string{"app.kubernetes.io/instance":"devlake",
"app.kubernetes.io/name":"grafana"},
MatchExpressions:[]v1.LabelSelectorRequirement(nil)}: field is immutable
+**If you are upgrading from DevLake v0.18.x or later versions:**
```shell
helm repo update
-helm upgrade devlake devlake/devlake --version=0.20.0-beta8 --set
lake.encryptionSecret.secret=<ENCRYPTION_SECRET>
+helm upgrade devlake devlake/devlake --version=0.20.0-beta8
```
-**If you're upgrading from DevLake v0.18.x or later versions:**
+<br/>
-```shell
-helm repo update
-helm upgrade devlake devlake/devlake --version=0.20.0-beta8
-```
+**If you are upgrading from DevLake v0.17.x or earlier versions to v0.18.x or
later versions:**
+
+1. Copy the ENCODE_KEY value from /app/config/.env of the lake pod (e.g.
devlake-lake-0), and replace the <ENCRYPTION_SECRET> in the upgrade command
below.
+
+2. You may encounter the below error when upgrading because the built-in
grafana has been replaced by the official grafana dependency. So you may need
to delete the grafana deployment first.
+
+ > Error: UPGRADE FAILED: cannot patch "devlake-grafana" with kind
Deployment: Deployment.apps "devlake-grafana" is invalid: spec.selector:
Invalid value:
v1.LabelSelector{MatchLabels:map[string]string{"app.kubernetes.io/instance":"devlake",
"app.kubernetes.io/name":"grafana"},
MatchExpressions:[]v1.LabelSelectorRequirement(nil)}: field is immutable
+
+ ```shell
+ helm repo update
+ helm upgrade devlake devlake/devlake --version=0.20.0-beta8 --set
lake.encryptionSecret.secret=<ENCRYPTION_SECRET>
+ ```
### Uninstall
diff --git a/docs/GettingStarted/Upgrade.md b/docs/GettingStarted/Upgrade.md
index c54fbd1b84..5dccff41ae 100644
--- a/docs/GettingStarted/Upgrade.md
+++ b/docs/GettingStarted/Upgrade.md
@@ -4,6 +4,14 @@ sidebar_position: 3
description: How to upgrade your Apache DevLake to a newer version
---
+## How to Upgrade to a new version
+Please follow the guide for detailed information:
+
+- Upgrade via [Docker Compose](DockerComposeSetup.md#upgrade)
+- Upgrade via [Helm](HelmSetup.md#upgrade)
+
+## Key points
+
1. ENCRYPTION_SECRET: It is important to keep the ENCRYPTION_SECRET safe as it
is used to encrypt sensitive information in the database, such as personal
access tokens and passwords. Losing the ENCRYPTION_SECRET may result in the
inability to decrypt this sensitive information.
2. .env file: The .env file is now optional. You can choose to store your
variables in the environment instead. Remember to consider important variables
such as ENCRYPTION_SECRET and DB_URL. If both the environment variables and the
.env file exist, the values in the environment variables will take precedence.
However, make sure that these variables are defined in either one of them to
avoid any issues with DevLake.
diff --git a/versioned_docs/version-v0.21/GettingStarted/DockerComposeSetup.md
b/versioned_docs/version-v0.21/GettingStarted/DockerComposeSetup.md
index 915b016cb5..1cacc1d63f 100644
--- a/versioned_docs/version-v0.21/GettingStarted/DockerComposeSetup.md
+++ b/versioned_docs/version-v0.21/GettingStarted/DockerComposeSetup.md
@@ -42,13 +42,14 @@ sidebar_position: 2
- We use [Grafana](https://grafana.com/) to visualize the DevOps
[data](/Overview/SupportedDataSources.md) and build dashboards.
- For how to customize and provision dashboards, please see our [Grafana
doc](../Configuration/Dashboards/GrafanaUserGuide.md).
-## Upgrade to a newer version
+## Upgrade
-Please note:
+:::caution
-Note 1: **Back up your Grafana dashboards** before upgrading if you have
modified/customized any dashboards. You can re-import these dashboards to
Grafana after the upgrade.
+- **Back up your Grafana dashboards** before upgrading if you have
modified/customized any dashboards. You can re-import these dashboards to
Grafana after the upgrade.
+- **If you are upgrading from DevLake v0.17.x or earlier versions to v0.18.x
or later versions**, you need to find the ENCODE_KEY value in the .env file of
devlake container, and assign the value to ENCRYPTION_SECRET via .env file or
environment variable in docker-compose.yml
-Note 2: **If you're upgrading from DevLake v0.17.x or earlier versions to
v0.18.x or later versions**, you need to find the ENCODE_KEY value in the .env
file of devlake container, and assign the value to ENCRYPTION_SECRET via .env
file or environment variable in docker-compose.yml
+:::
1. Run `docker-compose down` to stop services;
2. Download `docker-compose.yml` and `env.example` from the [latest
release](https://github.com/apache/incubator-devlake/releases).
diff --git a/versioned_docs/version-v0.21/GettingStarted/HelmSetup.md
b/versioned_docs/version-v0.21/GettingStarted/HelmSetup.md
index bade88d772..fa397d0fcb 100644
--- a/versioned_docs/version-v0.21/GettingStarted/HelmSetup.md
+++ b/versioned_docs/version-v0.21/GettingStarted/HelmSetup.md
@@ -72,29 +72,33 @@ grafana by url `http://YOUR-NODE-IP:30091`
### Upgrade
-**Note:**
+:::caution
**Back up your Grafana dashboards** before upgrading if you have
modified/customized any dashboards. You can re-import these dashboards to
Grafana after the upgrade.
-**If you're upgrading from DevLake v0.17.x or earlier versions to v0.18.x or
later versions:**
+:::
-1. Copy the ENCODE_KEY value from /app/config/.env of the lake pod (e.g.
devlake-lake-0), and replace the <ENCRYPTION_SECRET> in the upgrade command
below.
-
-2. You may encounter the below error when upgrading because the built-in
grafana has been replaced by the official grafana dependency. So you may need
to delete the grafana deployment first.
-
-> Error: UPGRADE FAILED: cannot patch "devlake-grafana" with kind Deployment:
Deployment.apps "devlake-grafana" is invalid: spec.selector: Invalid value:
v1.LabelSelector{MatchLabels:map[string]string{"app.kubernetes.io/instance":"devlake",
"app.kubernetes.io/name":"grafana"},
MatchExpressions:[]v1.LabelSelectorRequirement(nil)}: field is immutable
+**If you are upgrading from DevLake v0.18.x or later versions:**
```shell
helm repo update
-helm upgrade devlake devlake/devlake --version=0.21.0-beta1 --set
lake.encryptionSecret.secret=<ENCRYPTION_SECRET>
+helm upgrade devlake devlake/devlake --version=0.20.0-beta8
```
-**If you're upgrading from DevLake v0.18.x or later versions:**
+<br/>
-```shell
-helm repo update
-helm upgrade devlake devlake/devlake --version=0.21.0-beta1
-```
+**If you are upgrading from DevLake v0.17.x or earlier versions to v0.18.x or
later versions:**
+
+1. Copy the ENCODE_KEY value from /app/config/.env of the lake pod (e.g.
devlake-lake-0), and replace the <ENCRYPTION_SECRET> in the upgrade command
below.
+
+2. You may encounter the below error when upgrading because the built-in
grafana has been replaced by the official grafana dependency. So you may need
to delete the grafana deployment first.
+
+ > Error: UPGRADE FAILED: cannot patch "devlake-grafana" with kind
Deployment: Deployment.apps "devlake-grafana" is invalid: spec.selector:
Invalid value:
v1.LabelSelector{MatchLabels:map[string]string{"app.kubernetes.io/instance":"devlake",
"app.kubernetes.io/name":"grafana"},
MatchExpressions:[]v1.LabelSelectorRequirement(nil)}: field is immutable
+
+ ```shell
+ helm repo update
+ helm upgrade devlake devlake/devlake --version=0.20.0-beta8 --set
lake.encryptionSecret.secret=<ENCRYPTION_SECRET>
+ ```
### Uninstall
diff --git a/versioned_docs/version-v0.21/GettingStarted/Upgrade.md
b/versioned_docs/version-v0.21/GettingStarted/Upgrade.md
index c54fbd1b84..5dccff41ae 100644
--- a/versioned_docs/version-v0.21/GettingStarted/Upgrade.md
+++ b/versioned_docs/version-v0.21/GettingStarted/Upgrade.md
@@ -4,6 +4,14 @@ sidebar_position: 3
description: How to upgrade your Apache DevLake to a newer version
---
+## How to Upgrade to a new version
+Please follow the guide for detailed information:
+
+- Upgrade via [Docker Compose](DockerComposeSetup.md#upgrade)
+- Upgrade via [Helm](HelmSetup.md#upgrade)
+
+## Key points
+
1. ENCRYPTION_SECRET: It is important to keep the ENCRYPTION_SECRET safe as it
is used to encrypt sensitive information in the database, such as personal
access tokens and passwords. Losing the ENCRYPTION_SECRET may result in the
inability to decrypt this sensitive information.
2. .env file: The .env file is now optional. You can choose to store your
variables in the environment instead. Remember to consider important variables
such as ENCRYPTION_SECRET and DB_URL. If both the environment variables and the
.env file exist, the values in the environment variables will take precedence.
However, make sure that these variables are defined in either one of them to
avoid any issues with DevLake.
