From d814076508b8fc4017e1fe64f52296bb24788d07 Mon Sep 17 00:00:00 2001 From: Meier Lukas Date: Tue, 31 Dec 2024 11:28:22 +0100 Subject: [PATCH] docs(env): add secret-encryption-key env variable (#149) --- blog/2024/09-23-version-1.0/index.mdx | 1 + blog/2024/12-17-open-beta-1.0/index.mdx | 2 + .../index.mdx | 54 +++++++++++++++++++ docs/advanced/environment-variables/index.mdx | 12 +++++ docs/advanced/proxy/index.mdx | 3 ++ docs/getting-started/installation/docker.mdx | 2 + .../installation/portainer.mdx | 2 + docs/integrations/containers.mdx | 2 + 8 files changed, 78 insertions(+) create mode 100644 blog/2024/12-31-migrate-secret-enryption-key/index.mdx diff --git a/blog/2024/09-23-version-1.0/index.mdx b/blog/2024/09-23-version-1.0/index.mdx index d02a58c2..a13c0cbe 100644 --- a/blog/2024/09-23-version-1.0/index.mdx +++ b/blog/2024/09-23-version-1.0/index.mdx @@ -43,6 +43,7 @@ Please consult the breaking changes list & upgrade guide if you used third-party - Removed support for ``arm/v7`` -> upgrade to newer architectures as an alternative - Renamed image from ``ghcr.io/ajnart/homarr`` to ``ghcr.io/homarr-labs/homarr``. We now use semantic versioning for our release numbers. - Environment Variables + - New required env variable ``SECRET_ENCRYPTION_KEY`` used for encryption of secrets in the database - Removed ``DISABLE_ANALYTICS``, can now be configured via UI - Renamed ``AUTH_PROVIDER`` to ``AUTH_PROVIDERS`` - Renamed ``DATABASE_URL`` to ``DB_URL`` and made it optional conditionally. If ``DB_HOST`` is set, this is optional - otherwise it's required. diff --git a/blog/2024/12-17-open-beta-1.0/index.mdx b/blog/2024/12-17-open-beta-1.0/index.mdx index 1eb6a46b..91f0a7b6 100644 --- a/blog/2024/12-17-open-beta-1.0/index.mdx +++ b/blog/2024/12-17-open-beta-1.0/index.mdx @@ -28,6 +28,8 @@ services: volumes: - /var/run/docker.sock:/var/run/docker.sock # Optional, only if you want docker integration - ./homarr/appdata:/appdata + environment: + - SECRET_ENCRYPTION_KEY=your_64_character_hex_string # <--- can be generated with `openssl rand -hex 32` ports: - '7575:7575' ``` diff --git a/blog/2024/12-31-migrate-secret-enryption-key/index.mdx b/blog/2024/12-31-migrate-secret-enryption-key/index.mdx new file mode 100644 index 00000000..59155e18 --- /dev/null +++ b/blog/2024/12-31-migrate-secret-enryption-key/index.mdx @@ -0,0 +1,54 @@ +--- +authors: + - meierschlumpf +--- + +# Migrate Secret Encryption Key + +In the release `v1.0.0-beta.10` we introduced a newly required env variable `SECRET_ENCRYPTION_KEY`. +This key is used to encrypt sensitive data in the database. +Before this release, the key was generated automatically and stored in the anonymous volume `/secrets`. +Because of the deletion of anonymous volumes between updates, by some installation methods, we decided to move this key to an environment variable. + + + +## How to migrate + +When you want to keep your integration secrets working after the update, you need to migrate your existing key to the new environment variable. +To do this, you can use the following steps: + +1. Print your current secret key with the following command: + ```bash + docker exec -it homarr cat /secrets/encryptionKey + ``` + +2. Copy the output of the command and set it as the new environment variable + +3. Change your docker-compose.yml to include the new environment variable: + + ```yml title="docker-compose.yml" + services: + homarr: + container_name: homarr + image: ghcr.io/homarr-labs/homarr:beta + restart: unless-stopped + volumes: + - /var/run/docker.sock:/var/run/docker.sock # Optional, only if you want docker integration + - ./homarr/appdata:/appdata + environment: + - SECRET_ENCRYPTION_KEY=your_64_character_hex_string # <--- can be generated with `openssl rand -hex 32` + ports: + - '7575:7575' + ``` + +4. Update the container: + + ```bash + docker compose pull + ``` + +5. Restart the container: + + ```bash + docker compose up -d + ``` \ No newline at end of file diff --git a/docs/advanced/environment-variables/index.mdx b/docs/advanced/environment-variables/index.mdx index 4a37726a..2cb554a5 100644 --- a/docs/advanced/environment-variables/index.mdx +++ b/docs/advanced/environment-variables/index.mdx @@ -32,6 +32,18 @@ Using the `PUID` and `PGID` will require you to set the correct permissions on t See [Single Sign-On](/docs/advanced/single-sign-on) for more informations. +## Security + +The `SECRET_ENCRYPTION_KEY` is required. If none is specified before starting the container, a random key will be shown in the error message and the container will exit. + +| Environment Variable | Description | Possible values | Default | +| ------------------------ | ----------- | --------------- | ------- | +| ``SECRET_ENCRYPTION_KEY`` | Secret used to encrypt secrets in database. | 64 character hex string | - | + +:::info +A random secret can be generated by using the following command: `openssl rand -hex 32` +::: + ## Docker | Environment Variable | Description | Possible values | Default | diff --git a/docs/advanced/proxy/index.mdx b/docs/advanced/proxy/index.mdx index f771b5c1..dcc3e97d 100644 --- a/docs/advanced/proxy/index.mdx +++ b/docs/advanced/proxy/index.mdx @@ -37,6 +37,7 @@ docker run \ -p 7575:7575 \ -v ./homarr/appdata:/appdata \ -e NODE_TLS_REJECT_UNAUTHORIZED=0 \ + - e SECRET_ENCRYPTION_KEY=your_64_character_hex_string \ -d ghcr.io/homarr-labs/homarr:latest ``` @@ -56,6 +57,7 @@ services: - ./homarr/appdata:/appdata environment: NODE_TLS_REJECT_UNAUTHORIZED: 0 + SECRET_ENCRYPTION_KEY: your_64_character_hex_string # <--- can be generated with `openssl rand -hex 32` ports: - '7575:7575' ``` @@ -79,6 +81,7 @@ services: - ./homarr/appdata:/appdata environment: - BASE_URL=your.internal.dns.address.here.com + - SECRET_ENCRYPTION_KEY=your_64_character_hex_string # <--- can be generated with `openssl rand -hex 32` networks: - proxy labels: diff --git a/docs/getting-started/installation/docker.mdx b/docs/getting-started/installation/docker.mdx index 43ddad34..e36a9563 100644 --- a/docs/getting-started/installation/docker.mdx +++ b/docs/getting-started/installation/docker.mdx @@ -27,6 +27,8 @@ services: volumes: - /var/run/docker.sock:/var/run/docker.sock # Optional, only if you want docker integration - ./homarr/appdata:/appdata + environment: + - SECRET_ENCRYPTION_KEY=your_64_character_hex_string # <--- can be generated with `openssl rand -hex 32` ports: - '7575:7575' ``` diff --git a/docs/getting-started/installation/portainer.mdx b/docs/getting-started/installation/portainer.mdx index 5ee98b4c..450dc8e3 100644 --- a/docs/getting-started/installation/portainer.mdx +++ b/docs/getting-started/installation/portainer.mdx @@ -20,6 +20,8 @@ services: volumes: - /var/run/docker.sock:/var/run/docker.sock # Optional, only if you want docker integration - /appdata:/appdata + environment: + - SECRET_ENCRYPTION_KEY=your_64_character_hex_string # <--- can be generated with `openssl rand -hex 32` ports: - '7575:7575' ``` diff --git a/docs/integrations/containers.mdx b/docs/integrations/containers.mdx index 60ceddfd..03287dfb 100644 --- a/docs/integrations/containers.mdx +++ b/docs/integrations/containers.mdx @@ -19,6 +19,8 @@ services: volumes: - /var/run/docker.sock:/var/run/docker.sock # <--- add this line here! - ./homarr/appdata:/appdata + environment: + - SECRET_ENCRYPTION_KEY=your_64_character_hex_string # <--- can be generated with `openssl rand -hex 32` ports: - '7575:7575' ```