From 0ffa95c50569f261ef61d73be9b8fab67d56cbf2 Mon Sep 17 00:00:00 2001 From: Thomas Date: Sun, 6 Sep 2026 15:31:40 +0200 Subject: [PATCH] docs: make environment examples safe and current (#6777) * docs: make SQLite environment example runnable * docs: remove unsafe source secret examples * docs(auth): remove unsafe SSO environment values * docs(auth): clarify OIDC credential placeholders --- .env.example | 16 +++++++----- .../docs/advanced/single-sign-on/index.mdx | 26 ++++++++++--------- .../getting-started/installation/source.mdx | 9 ++++--- 3 files changed, 28 insertions(+), 23 deletions(-) diff --git a/.env.example b/.env.example index e05862c3c..7fbb581d4 100644 --- a/.env.example +++ b/.env.example @@ -1,22 +1,24 @@ # Since .env is gitignored, you can use .env.example to build a new `.env` file when you clone the repo. -# Keep this file up-to-date when you add new variables to \`.env\`. +# Keep this file up-to-date when you add new variables to `.env`. # This file will be committed to version control, so make sure not to have any secrets in it. # If you are cloning this repo, create a copy of this file named `.env` and populate it with your secrets. -# The below secret is not used anywhere but required for Auth.js (Would encrypt JWTs and Mail hashes, both not used) -AUTH_SECRET="supersecret" +# Generate two different 64-character hex values with `openssl rand -hex 32` before starting Homarr. +# Never reuse these values or commit the populated `.env` file. +AUTH_SECRET= # The below secret is used to encrypt integration secrets in the database. -# It should be a 32-byte string, generated by running `openssl rand -hex 32` on Unix -# or starting the project without any (which will show a randomly generated one). -SECRET_ENCRYPTION_KEY=0000000000000000000000000000000000000000000000000000000000000000 +# Homarr will reject an empty or invalid value and print a randomly generated candidate. +SECRET_ENCRYPTION_KEY= LOG_LEVEL='info' # This is how you can use the sqlite driver: DB_DRIVER='better-sqlite3' -DB_URL='FULL_PATH_TO_YOUR_SQLITE_DB_FILE' +# Safe local source-development path. SQLite files are ignored by Git. +# Container images use /appdata/db/db.sqlite by default instead. +DB_URL='./db.sqlite' # Those are the two ways to use the mysql2 driver: # 1. Using the URL format: diff --git a/apps/docs/docs/advanced/single-sign-on/index.mdx b/apps/docs/docs/advanced/single-sign-on/index.mdx index 505fe9867..80209ae3a 100644 --- a/apps/docs/docs/advanced/single-sign-on/index.mdx +++ b/apps/docs/docs/advanced/single-sign-on/index.mdx @@ -244,18 +244,21 @@ Homarr supports multiple authentication options, from internal userbase (credent - Create a group (e.g., `homarr-admins`) and assign users who require admin access. **2. Example .env file:** + + Generate `SECRET_ENCRYPTION_KEY` with `openssl rand -hex 32`; do not copy an example key between installs. + ```env - OIDC_CLIENT_ID=identificationid #OIDC client ID - OIDC_CLIENT_SECRET=secretsecretsecret #OIDC client secret + OIDC_CLIENT_ID= + OIDC_CLIENT_SECRET= OIDC_SLUG=homarr #Application slug in Authentik AUTH_DOMAIN=auth.example.com #Authentik FQDN ADMIN_GROUP=homarr-admins #Authentik group for Homarr admins HOMARR_FQDN=homarr.example.com #Homarr FQDN - SECRET_ENCRYPTION_KEY=encryptencryptencrypt #Homarr encryption key + SECRET_ENCRYPTION_KEY= ``` **3. Example Docker Compose configuration:** - ```yaml {14-26} + ```yaml {14-24} services: homarr: image: ghcr.io/homarr-labs/homarr:latest @@ -269,8 +272,6 @@ Homarr supports multiple authentication options, from internal userbase (credent environment: - TZ=America/Los_Angeles - SECRET_ENCRYPTION_KEY=${SECRET_ENCRYPTION_KEY} - - BASE_URL=https://${HOMARR_FQDN} - - NEXTAUTH_URL=https://${HOMARR_FQDN} - AUTH_PROVIDERS=oidc #(optional: include ',credentials' to keep local accounts as fallback) - AUTH_OIDC_CLIENT_ID=${OIDC_CLIENT_ID} - AUTH_OIDC_CLIENT_SECRET=${OIDC_CLIENT_SECRET} @@ -322,15 +323,18 @@ Homarr supports multiple authentication options, from internal userbase (credent - Record the `Client-ID` and `Client Key` (secret). **2. Example .env file (Homarr):** + + Generate `SECRET_ENCRYPTION_KEY` with `openssl rand -hex 32`; do not copy an example key between installs. + ```env - OIDC_CLIENT_ID=identificationid #Google Client-ID - OIDC_CLIENT_SECRET=secretsecretsecret #Google Client Key (secret) + OIDC_CLIENT_ID= + OIDC_CLIENT_SECRET= HOMARR_FQDN=homarr.example.com #Homarr FQDN - SECRET_ENCRYPTION_KEY=encryptencryptencrypt #Homarr encryption key + SECRET_ENCRYPTION_KEY= ``` **3. Example Docker Compose configuration (Homarr):** - ```yaml {16-22} + ```yaml {14-20} services: homarr: image: ghcr.io/homarr-labs/homarr:latest @@ -344,8 +348,6 @@ Homarr supports multiple authentication options, from internal userbase (credent environment: - TZ=Europe/Berlin - SECRET_ENCRYPTION_KEY=${SECRET_ENCRYPTION_KEY} - - BASE_URL=https://${HOMARR_FQDN} - - NEXTAUTH_URL=https://${HOMARR_FQDN} - AUTH_PROVIDERS=oidc #(optional: include ',credentials' to keep local accounts as fallback) - AUTH_OIDC_CLIENT_ID=${OIDC_CLIENT_ID} - AUTH_OIDC_CLIENT_SECRET=${OIDC_CLIENT_SECRET} diff --git a/apps/docs/docs/getting-started/installation/source.mdx b/apps/docs/docs/getting-started/installation/source.mdx index 838f0d0a2..3544fb1be 100644 --- a/apps/docs/docs/getting-started/installation/source.mdx +++ b/apps/docs/docs/getting-started/installation/source.mdx @@ -38,13 +38,14 @@ This method is only useful, when you want to develop on Homarr or extend it with Install all dependencies using pnpm install
  • - Copy the `.env.example` file to `.env` and replace `DB_URL` with the full path you want to use for the sqlite - database file. For example `DB_URL='/home/username/homarr/db.sqlite` + Copy the `.env.example` file to `.env`. Its `DB_URL='./db.sqlite'` value is ready for local use and stores the + database in the cloned repository. Replace it with an absolute writable path such as + `DB_URL='/home/username/homarr/db.sqlite'` if you want to store the database elsewhere.
  • - Replace `AUTH_SECRET` and `SECRET_ENCRYPTION_KEY` both with a secure random string by using `openssl rand -hex 32` + Run `openssl rand -hex 32` twice and set `AUTH_SECRET` and `SECRET_ENCRYPTION_KEY` to the two different generated + values. Keep both values secret and preserve `SECRET_ENCRYPTION_KEY` with your backups.
    • -
  • Replace `CRON_JOB_API_KEY` with a secure random string by using `openssl rand -base64 32`
  • Run `pnpm run db:migration:sqlite:run` and wait that it completes
  • Build the source using `pnpm build`