This is an automated email from the ASF dual-hosted git repository.
zhangliang2022 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 c1c519118f docs: installation Guide to ask users to generate the
ENCRYPTION_SECRET (#550)
c1c519118f is described below
commit c1c519118fe2ab70c3d76615e329462523d1e7e8
Author: abeizn <[email protected]>
AuthorDate: Tue Jun 13 15:32:43 2023 +0800
docs: installation Guide to ask users to generate the ENCRYPTION_SECRET
(#550)
* docs: installation Guide to ask users to generate the ENCRYPTION_SECRET
* fix: lint
* docs: installation Guide to ask users to generate the ENCRYPTION_SECRET
* docs: add please note
* docs: add .env optional docs
* fix: file exist
* docs: add upgrade notes
---
docs/GettingStarted/DockerComposeSetup.md | 21 +++++++++++++++++---
docs/GettingStarted/HelmSetup.md | 33 +++++++++++++++++++++++++------
docs/GettingStarted/Upgrade.md | 28 +++++---------------------
3 files changed, 50 insertions(+), 32 deletions(-)
diff --git a/docs/GettingStarted/DockerComposeSetup.md
b/docs/GettingStarted/DockerComposeSetup.md
index 1f1fc72167..ad63f82a6f 100644
--- a/docs/GettingStarted/DockerComposeSetup.md
+++ b/docs/GettingStarted/DockerComposeSetup.md
@@ -14,7 +14,24 @@ sidebar_position: 1
1. Download `docker-compose.yml` and `env.example` from the [latest
release](https://github.com/apache/incubator-devlake/releases/tag/v0.17.0-beta11)
into a folder.
2. Rename `env.example` to `.env`. For Mac/Linux users, please run `mv
env.example .env` in the terminal. This file contains the environment variables
that the Devlake server will use. Additional ones can be found in the compose
file(s).
-3. Run `docker-compose up -d` if the version of Docker Desktop is too low to
use `docker compose up -d`.
+3. Generate a secure encryption key using a method such as OpenSSL. For
example, run the following command to generate a 128-character string
consisting of uppercase letters:
+ ```
+ openssl rand -base64 2000 | tr -dc 'A-Z' | fold -w 128 | head -n 1
+ ```
+ Copy the generated string. Set the value of the ENCRYPTION_SECRET
environment variable:
+
+- Method 1: In a terminal session, run the following command: export
ENCRYPTION_SECRET="copied string"
+- Method 2: Alternatively, you can set the ENCRYPTION_SECRET environment
variable in the .env file: ENCRYPTION_SECRET="copied string"
+
+ If you set the ENCRYPTION_SECRET environment variable in both the terminal
session and the .env file, the value set in the terminal session takes
precedence.
+
+ **Please make sure to keep the ENCRYPTION_SECRET safe as it is used to
encrypt sensitive information in the database, such as personal access tokens
and passwords. If ENCRYPTION_SECRET is lost, it may not be possible to decrypt
this sensitive information.**
+
+ **The .env file is now optional, and you can place the variables in the
environment instead, such as ENCRYPTION_SECRET and DB_URL. If both environment
variables and .env file exist, the values in the environment variables take
priority, but you need to ensure that these variables are set in one of them,
or devlake will fail.**
+
+ **If you are upgrading to version v0.18.0 from a previous version, please
note that the environment variable used for encryption was previously called
ENCODE_KEY. If you have previously set ENCODE_KEY in your environment or .env
file, please assign its value to the ENCRYPTION_SECRET environment variable
after upgrading to v0.18.0. This will ensure that the encryption process
continues to work as expected.**
+
+4. Run `docker-compose up -d` if the version of Docker Desktop is too low to
use `docker compose up -d`.
## Collect data and view dashboards
@@ -33,8 +50,6 @@ Please note: **Back up your Grafana dashboards** before
upgrade if you have modi
2. Open file "docker-compose.yml". Change the image tags of "grafana",
"devlake" and "config-ui" to the new version, and save;
3. Run `docker-compose up -d` to start DevLake services.
-Please check the [upgrade doc](Upgrade.md) for more information.
-
## FAQ
### Can I use a managed cloud database service instead of running database in
Docker?
diff --git a/docs/GettingStarted/HelmSetup.md b/docs/GettingStarted/HelmSetup.md
index 8a943f188b..34c5773ed4 100644
--- a/docs/GettingStarted/HelmSetup.md
+++ b/docs/GettingStarted/HelmSetup.md
@@ -16,13 +16,34 @@ sidebar_position: 2
### Install
-To install the chart with release name `devlake`:
+To install the chart with release name `devlake`,follow these steps:
+1. Generate a secure encryption key using a method such as OpenSSL. For
example, run the following command to generate a 128-character string
consisting of uppercase letters:
-```shell
-helm repo add devlake https://apache.github.io/incubator-devlake-helm-chart
-helm repo update
-helm install devlake devlake/devlake --version=0.17.0-beta11
-```
+ ```
+ openssl rand -base64 2000 | tr -dc 'A-Z' | fold -w 128 | head -n 1
+ ```
+
+2. Copy the generated string, set the value of the ENCRYPTION_SECRET
environment variable by running the following command:
+
+ ```
+ export ENCRYPTION_SECRET="copied string"
+ ```
+
+ This command will set the `ENCRYPTION_SECRET` environment variable to
the value of the copied string.
+
+ **Please make sure to keep the ENCRYPTION_SECRET safe as it is used to
encrypt sensitive information in the database, such as personal access tokens
and passwords. If ENCRYPTION_SECRET is lost, it may not be possible to decrypt
this sensitive information.**
+
+ **The .env file is now optional, and you can place the variables in the
environment instead, such as ENCRYPTION_SECRET and DB_URL. If both environment
variables and .env file exist, the values in the environment variables take
priority, but you need to ensure that these variables are set in one of them,
or devlake will fail.**
+
+ **If you are upgrading to version v0.18.0 from a previous version, please
note that the environment variable used for encryption was previously called
ENCODE_KEY. If you have previously set ENCODE_KEY in your environment or .env
file, please assign its value to the ENCRYPTION_SECRET environment variable
after upgrading to v0.18.0. This will ensure that the encryption process
continues to work as expected.**
+
+3. Install the chart by running the following commands:
+
+ ```shell
+ helm repo add devlake https://apache.github.io/incubator-devlake-helm-chart
+ helm repo update
+ helm install devlake devlake/devlake --version=0.17.0-beta10
+ ```
And visit your devlake from the node port (32001 by default).
diff --git a/docs/GettingStarted/Upgrade.md b/docs/GettingStarted/Upgrade.md
index 7709a48f9b..0e55d6d4b5 100644
--- a/docs/GettingStarted/Upgrade.md
+++ b/docs/GettingStarted/Upgrade.md
@@ -4,30 +4,12 @@ sidebar_position: 3
description: How to upgrade your Apache DevLake to a newer version
---
-## Upgrade Options
+## Upgrade Notes
+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.
-### Option 1: Update the image tags to a newer version
+2. .env file: The .env file is now optional. You have the flexibility to place
the variables in the environment instead. Some of the variables you need to
consider are ENCRYPTION_SECRET and DB_URL. If both environment variables and
.env file exist, the values in the environment variables take priority.
However, ensure that these variables are set in either one of them to avoid any
failures with DevLake.
-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).
+3. Upgrade to v0.18.0: If you are upgrading to version v0.18.0 from a previous
version, there is a change in the environment variable used for encryption.
Previously, it was called ENCODE_KEY. After upgrading to v0.18.0, if you have
previously set ENCODE_KEY in your environment or .env file, please assign its
value to the ENCRYPTION_SECRET environment variable. This will ensure that the
encryption process continues to work as expected.
+These notes provide guidance on upgrading your Apache DevLake to a newer
version. Ensure you follow them carefully to avoid any issues during the
upgrade process.
