From 93ab41085771821219fd64d5efcb73ad38d979a2 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jan=20B=C3=B6hmer?= Date: Sun, 7 Jun 2026 22:37:47 +0200 Subject: [PATCH] Added documentation about changing the APP_SECRET env on installation --- docs/configuration.md | 19 ++++++++--- docs/installation/installation_docker.md | 33 +++++++++++++------ .../installation/installation_guide-debian.md | 9 +++++ src/Services/System/AppSecretChecker.php | 1 + 4 files changed, 48 insertions(+), 14 deletions(-) diff --git a/docs/configuration.md b/docs/configuration.md index 7ba716c6..ea86f3a6 100644 --- a/docs/configuration.md +++ b/docs/configuration.md @@ -114,10 +114,21 @@ bundled with Part-DB. Set `DATABASE_MYSQL_SSL_VERIFY_CERT` if you want to accept * `datastructure_create`: Creation of a new data structure (e.g. category, manufacturer, ...) * `CHECK_FOR_UPDATES` (default `1`): Set this to 0 if you do not want Part-DB to connect to GitHub to check for new versions, or if your server cannot connect to the internet. -* `APP_SECRET` (env only): This variable is a configuration parameter used for various security-related purposes, - particularly for securing and protecting various aspects of your application. It's a secret key that is used for - cryptographic operations and security measures (session management, CSRF protection, etc..). Therefore this - value should be handled as confidential data and not shared publicly. +* `APP_SECRET` (env only): A secret key used by Symfony for cryptographic operations — signing cookies, generating + CSRF tokens, and other security-sensitive tasks. **You must change this from the default value before exposing + Part-DB to any network.** The default value shipped with Part-DB is publicly known; leaving it in place would allow + an attacker to forge signed cookies and bypass CSRF protection. + + Generate a secure value and add it to `.env.local`: + ```bash + echo "APP_SECRET=$(openssl rand -hex 32)" >> .env.local + ``` + For Docker, pass it in the `environment` section of your `docker-compose.yaml`: + ```yaml + environment: + - APP_SECRET= + ``` + Part-DB displays a warning on the homepage (visible to administrators only) as long as the default value is in use. * `SHOW_PART_IMAGE_OVERLAY`: Set to 0 to disable the part image overlay, which appears if you hover over an image in the part image gallery * `IPN_SUGGEST_REGEX`: A global regular expression, that part IPNs have to fulfill. Enforce your own format for your users. diff --git a/docs/installation/installation_docker.md b/docs/installation/installation_docker.md index ab07e010..97b1e662 100644 --- a/docs/installation/installation_docker.md +++ b/docs/installation/installation_docker.md @@ -47,7 +47,10 @@ services: - DATABASE_URL=sqlite:///%kernel.project_dir%/var/db/app.db # In docker env logs will be redirected to stderr - APP_ENV=docker - + # Secret key used to sign cookies and CSRF tokens. MUST be changed to a unique random value before going live! + # Generate one with: openssl rand -hex 32 + - APP_SECRET=CHANGE_ME + # Uncomment this, if you want to use the automatic database migration feature. With this you have you do not have to # run the doctrine:migrations:migrate commands on installation or upgrade. A database backup is written to the uploads/ # folder (under .automigration-backup), so you can restore it, if the migration fails. @@ -89,7 +92,11 @@ services: 4. Customize the settings by changing the environment variables (or adding new ones). See [Configuration]({% link configuration.md %}) for more information. -5. Inside the folder, run +5. Make sure to change the `APP_SECRET` variable to a unique random value (32 characters). You can generate one with the following command: +```bash +openssl rand -hex 32 +``` +6. Inside the folder, run ```bash docker-compose up -d @@ -100,7 +107,7 @@ services: > Otherwise Part-DB console might use the wrong configuration to execute commands. -6. Create the initial database with +7. Create the initial database with ```bash docker exec --user=www-data partdb php bin/console doctrine:migrations:migrate @@ -108,7 +115,7 @@ docker exec --user=www-data partdb php bin/console doctrine:migrations:migrate and watch for the password output -6. Part-DB is available under `http://localhost:8080` and you can log in with the username `admin` and the password shown +8. Part-DB is available under `http://localhost:8080` and you can log in with the username `admin` and the password shown before The docker image uses a SQLite database and all data (database, uploads, and other media) is put into folders relative to @@ -121,6 +128,7 @@ If you want to use MySQL as a database, you can use the following docker-compose {: .warning } > You have to replace the values for MYSQL_ROOT_PASSWORD and MYSQL_PASSWORD with your own passwords!! > You have to change MYSQL_PASSWORD in the database section and for the DATABASE_URL in the partdb section. +> Generate a random string for APP_SECRET. ```yaml version: '3.3' @@ -142,14 +150,19 @@ services: environment: # Replace SECRET_USER_PASSWORD with the value of MYSQL_PASSWORD from below - DATABASE_URL=mysql://partdb:SECRET_USER_PASSWORD@database:3306/partdb + + # Secret key used to sign cookies. MUST be changed to a unique random value before going live! + # Generate one with: openssl rand -hex 32 + - APP_SECRET=CHANGE_ME + # In docker env logs will be redirected to stderr - APP_ENV=docker - - # Uncomment this, if you want to use the automatic database migration feature. With this you do not have to - # run the doctrine:migrations:migrate commands on installation or upgrade. A database backup is written to the uploads/ - # folder (under .automigration-backup), so you can restore it, if the migration fails. - # This feature is currently experimental, so use it at your own risk! - # - DB_AUTOMIGRATE=true + + # Uncomment this, if you want to use the automatic database migration feature. With this you do not have to + # run the doctrine:migrations:migrate commands on installation or upgrade. A database backup is written to the uploads/ + # folder (under .automigration-backup), so you can restore it, if the migration fails. + # This feature is currently experimental, so use it at your own risk! + # - DB_AUTOMIGRATE=true # You can configure Part-DB using the webUI or environment variables # However you can add any other environment configuration you want here diff --git a/docs/installation/installation_guide-debian.md b/docs/installation/installation_guide-debian.md index b3c61126..e9f500b8 100644 --- a/docs/installation/installation_guide-debian.md +++ b/docs/installation/installation_guide-debian.md @@ -136,6 +136,15 @@ cp .env .env.local In your `.env.local` you can configure Part-DB according to your wishes and overwrite web interface settings. A full list of configuration options can be found [here](../configuration.md). +{: .important } +> **Change `APP_SECRET` before going live.** The default value shipped with Part-DB is publicly known and must not be +> used in production — it would allow an attacker to forge signed cookies and bypass CSRF protection. +> Generate a new value and add it to your `.env.local`: +> ```bash +> echo "APP_SECRET=$(openssl rand -hex 32)" >> .env.local +> ``` +> or edit the file with a text editor and add a new value for `APP_SECRET` (you can generate a random value with `openssl rand -hex 32`). + Please check that the configured base currency matches your mainly used currency, as this can not be changed after creating price information. diff --git a/src/Services/System/AppSecretChecker.php b/src/Services/System/AppSecretChecker.php index d5a29ba5..7a4b1fcf 100644 --- a/src/Services/System/AppSecretChecker.php +++ b/src/Services/System/AppSecretChecker.php @@ -33,6 +33,7 @@ final readonly class AppSecretChecker public const INSECURE_SECRETS = [ 'a03498528f5a5fc089273ec9ae5b2849', // default in .env '318b5d659e07a0b3f96d9b3a83b254ca', // default in .env.dev + 'CHANGE_ME' //example secret used in documentation and error messages ]; public function __construct(