docs(env): add secret-encryption-key env variable (#149)

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.

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'
 ```

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.
+
+<!-- truncate -->
+
+## 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
+    ```

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 |

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:

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'
 ```

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
       - <your-path>/appdata:/appdata
+    environment:
+      - SECRET_ENCRYPTION_KEY=your_64_character_hex_string # <--- can be generated with `openssl rand -hex 32`
     ports:
       - '7575:7575'
 ```

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'
 ```