From bc26a283352e04b6a96a576367bbe63e4fdd05c0 Mon Sep 17 00:00:00 2001 From: Jan Sandbrink Date: Tue, 11 Nov 2025 09:17:49 +0100 Subject: [PATCH] Clarify task and docs around supported env vars The task did not always print out the name of an environment variable that we use during documentation, e.g. for OPENPROJECT_OPENID__CONNECT. By preferring the usage of the env_alias this has been fixed. Docs have been adapted to indicate when to expect certain variables to work. --- .../configuration/environment/README.md | 34 ++++++++++++++----- lib/tasks/setting.rake | 14 ++++++-- 2 files changed, 36 insertions(+), 12 deletions(-) diff --git a/docs/installation-and-operations/configuration/environment/README.md b/docs/installation-and-operations/configuration/environment/README.md index f6bb780e149..fd0f43198cc 100644 --- a/docs/installation-and-operations/configuration/environment/README.md +++ b/docs/installation-and-operations/configuration/environment/README.md @@ -58,6 +58,11 @@ Some of the provided variables are only applicable during the seeding of a new i These variables are prefixed with `OPENPROJECT_SEED_*` to identify them. Changing these variables to a new value in a running system of OpenProject will likely have no effect unless explicitly marked in the configuration guides. +These additional variables are also only useful during seeding: + +* `OPENPROJECT_OPENID__CONNECT`: A hash to configure OIDC providers seeded into the application +* `OPENPROJECT_SAML`: A hash to configure SAML providers seeded into the application + ## Passing data structures to the app The configuration uses YAML to parse overrides from ENV. Using YAML inline syntax, you can: @@ -95,7 +100,7 @@ enterprise: ## Supported environment variables -A list of all configuration variables that can be overridden by defining them in the environment from bash could be generated by executing the following rake task: +A list of all configuration variables that can be overridden using environment variables, could be generated by executing the following rake task: For packaged installations: @@ -106,12 +111,14 @@ sudo openproject run bundle exec rake setting:available_envs For Docker installations: ```shell -docker exec -it $(docker ps | grep web | cut -d' ' -f 1) bash -c "RAILS_ENV=production bundle exec rake setting:available_envs" +# Check correct container name with `docker ps` first +docker exec -it -e RAILS_ENV=production openproject-web-1 bundle exec rake setting:available_envs ``` The default value is also visible for each variable in parenthesis. The following are the correct values at the time of writing and that you should use the commands shown above to make sure to get the up-to-date list. ```shell +OPENPROJECT_2FA (default={"active_strategies" => [], "enforced" => false, "allow_remember_for_days" => 0}) OPENPROJECT_ACTIVITY__DAYS__DEFAULT (default=30) Days displayed on project activity OPENPROJECT_ADDITIONAL__HOST__NAMES (default=[]) Additional allowed host names for the application. OPENPROJECT_AFTER__FIRST__LOGIN__REDIRECT__URL (default=nil) URL users logging in for the first time will be redirected to (e.g., a help screen) @@ -158,6 +165,7 @@ OPENPROJECT_CACHE__FORMATTED__TEXT (default=true) Cache formatted text OPENPROJECT_CACHE__MEMCACHE__SERVER (default=nil) The memcache server host and IP OPENPROJECT_CACHE__NAMESPACE (default=nil) Namespace for cache keys, useful when multiple applications use a single memcache server OPENPROJECT_CACHE__REDIS__URL (default=nil) URL to the redis cache server +OPENPROJECT_COLLABORATIVE__EDITING__HOCUSPOCUS__URL (default=nil) The URL of the hocuspocus server used by BlockNoteJS editor to enable collaborative editing. OPENPROJECT_COMMIT__FIX__KEYWORDS (default="fixes,closes") Keywords to look for in commit for fixing work packages OPENPROJECT_COMMIT__FIX__STATUS__ID (default=nil) Assigned status when fixing keyword is found OPENPROJECT_COMMIT__LOGS__ENCODING (default="UTF-8") Encoding used to convert commit logs to UTF-8 @@ -212,13 +220,21 @@ OPENPROJECT_ENFORCE__TRACKING__START__AND__END__TIMES (default=false) Require st OPENPROJECT_ENTERPRISE__CHARGEBEE__SITE (default="openproject-enterprise") Site name for EE trial service OPENPROJECT_ENTERPRISE__PLAN (default="enterprise-on-premises---basic---euro---1-year") Default EE selected plan OPENPROJECT_ENTERPRISE__TRIAL__CREATION__HOST (default="https://start.openproject.com") Host for EE trial service +OPENPROJECT_FEATURE__BETA__WIDGETS__ACTIVE (default=false) Enables BETA versions of widgets. OPENPROJECT_FEATURE__BLOCK__NOTE__EDITOR__ACTIVE (default=false) Enables the block note editor for rich text fields where available. OPENPROJECT_FEATURE__BUILT__IN__OAUTH__APPLICATIONS__ACTIVE (default=false) Allows the display and use of built-in OAuth applications. -OPENPROJECT_FEATURE__CALCULATED__VALUE__PROJECT__ATTRIBUTE__ACTIVE (default=false) Allows the use of calculated values as a project attribute. +OPENPROJECT_FEATURE__CALCULATED__VALUE__PROJECT__ATTRIBUTE__ACTIVE (default=true) Allows the use of calculated values as a project attribute. OPENPROJECT_FEATURE__DEPLOY__TARGETS__ACTIVE (default=false) -OPENPROJECT_FEATURE__OIDC__GROUP__SYNC__ACTIVE (default=false) Allows to synchronize groups from OpenID Connect providers +OPENPROJECT_FEATURE__MEETING__ICAL__SUBSCRIPTION__ACTIVE (default=false) Allows users to subscribe to all of their meetings via iCalendar +OPENPROJECT_FEATURE__MINUTES__STYLING__MEETING__PDF__ACTIVE (default=false) Allow exporting a meeting with FITKO styling. See #65124 for details. +OPENPROJECT_FEATURE__NEW__PROJECT__OVERVIEW__ACTIVE (default=false) Enables the new project overview experience. +OPENPROJECT_FEATURE__OIDC__GROUP__SYNC__ACTIVE (default=true) Allows to synchronize groups from OpenID Connect providers +OPENPROJECT_FEATURE__PORTFOLIO__MODELS__ACTIVE (default=false) Enables the creation and management of portfolio and program work spaces. +OPENPROJECT_FEATURE__PROJECT__INITIATION__ACTIVE (default=false) Activate the project creation and initiation wizard OPENPROJECT_FEATURE__SCIM__API__ACTIVE (default=true) Enables SCIM API. +OPENPROJECT_FEATURE__SHAREPOINT__STORAGE__ACTIVE (default=false) OPENPROJECT_FEATURE__STORAGE__FILE__PICKING__SELECT__ALL__ACTIVE (default=false) +OPENPROJECT_FEATURE__WP__ACTIVITY__TAB__LAZY__PAGINATION__ACTIVE (default=false) Enables lazy pagination for the activity tab. OPENPROJECT_FEEDS__ENABLED (default=true) Enable Feeds OPENPROJECT_FEEDS__LIMIT (default=15) Feed content limit OPENPROJECT_FILE__MAX__SIZE__DISPLAYED (default=512) Max size of text files displayed inline @@ -275,6 +291,7 @@ OPENPROJECT_MAIL__HANDLER__BODY__DELIMITERS (default="") Truncate emails after o OPENPROJECT_MAIL__HANDLER__IGNORE__FILENAMES (default="signature.asc") Ignored mail attachments OPENPROJECT_MAIL__SUFFIX__SEPARATORS (default="+") OPENPROJECT_MAIN__CONTENT__LANGUAGE (default="english") Main content language for PostgreSQL full text features +OPENPROJECT_METRICS (default={"enabled" => false, "port" => 9394}) Publish a reduced set of puma metrics on a separate port for Prometheus consumption, providing autoscaling hints OPENPROJECT_MIGRATION__CHECK__ON__EXCEPTIONS (default=true) Check for missing migrations in internal errors OPENPROJECT_NEW__PROJECT__USER__ROLE__ID (default=nil) Role given to a non-admin user who creates a project OPENPROJECT_NOTIFICATIONS__HIDDEN (default=false) @@ -282,7 +299,8 @@ OPENPROJECT_NOTIFICATIONS__POLLING__INTERVAL (default=60000) OPENPROJECT_OAUTH__ALLOW__REMAPPING__OF__EXISTING__USERS (default=true) When set to false, prevent users from other identity providers to take over accounts that exist in OpenProject. OPENPROJECT_OMNIAUTH__DIRECT__LOGIN__PROVIDER (default=nil) Clicking on login sends a login request to the specified OmniAuth provider. OPENPROJECT_ONBOARDING__ENABLED (default=true) Enable or disable onboarding guided tour for new users -OPENPROJECT_ONBOARDING__VIDEO__URL (default="https://player.vimeo.com/video/163426858?autoplay=1") Onboarding guide instructional video URL +OPENPROJECT_OPENID__CONNECT (default={}) Provide a OIDC provider and sync its settings through ENV +OPENPROJECT_OPENTELEMETRY__ENABLED (default=false) Enable OpenTelemetry metrics OPENPROJECT_OVERRIDE__BCRYPT__COST__FACTOR (default=nil) Set a custom BCrypt cost factor for deriving a user's bcrypt hash. OPENPROJECT_PASSWORD__ACTIVE__RULES (default=["lowercase", "uppercase", "numeric", "special"]) Active character classes OPENPROJECT_PASSWORD__COUNT__FORMER__BANNED (default=0) Number of most recently used passwords banned for reuse @@ -306,7 +324,6 @@ OPENPROJECT_PLUGIN__OPENPROJECT__OPENID__CONNECT (default=nil) OPENPROJECT_PLUGIN__OPENPROJECT__RECAPTCHA (default={"recaptcha_type" => "disabled", "response_limit" => 5000}) OPENPROJECT_PLUGIN__OPENPROJECT__STORAGES (default=nil) OPENPROJECT_PLUGIN__OPENPROJECT__TEAM__PLANNER (default=nil) -OPENPROJECT_PLUGIN__OPENPROJECT__TWO__FACTOR__AUTHENTICATION (default={"active_strategies" => [], "enforced" => false, "allow_remember_for_days" => 0}) OPENPROJECT_PROJECT__GANTT__QUERY (default=nil) Project portfolio Gantt view OPENPROJECT_RAILS__ASSET__HOST (default=nil) Custom asset hostname for serving assets (e.g., Cloudfront) OPENPROJECT_RAILS__CACHE__STORE (default=:file_store) Set cache store implementation to use with OpenProject @@ -324,6 +341,7 @@ OPENPROJECT_REPOSITORY__LOG__DISPLAY__LIMIT (default=100) Maximum number of revi OPENPROJECT_REPOSITORY__STORAGE__CACHE__MINUTES (default=720) Repository disk size cache OPENPROJECT_REPOSITORY__TRUNCATE__AT (default=500) Maximum number of files displayed in the repository browser OPENPROJECT_REST__API__ENABLED (default=true) Enable REST web service +OPENPROJECT_SAML (default={}) Provide a SAML provider and sync its settings through ENV OPENPROJECT_SCM (default={}) OPENPROJECT_SCM__GIT__COMMAND (default=nil) OPENPROJECT_SCM__LOCAL__CHECKOUT__PATH (default="repositories") @@ -338,8 +356,6 @@ OPENPROJECT_SEED__ADMIN__USER__PASSWORD__RESET (default=true) Whether to force a OPENPROJECT_SEED__DESIGN (default=nil) Seed enterprise-edition theme colors and logos through ENV OPENPROJECT_SEED__ENTERPRISE__TOKEN (default=nil) Seed enterprise-edition token through ENV OPENPROJECT_SEED__LDAP (default=nil) Provide an LDAP connection and sync settings through ENV -OPENPROJECT_SEED__OIDC__PROVIDER (default={}) Provide a OIDC provider and sync its settings through ENV -OPENPROJECT_SEED__SAML__PROVIDER (default={}) Provide a SAML provider and sync its settings through ENV OPENPROJECT_SELF__REGISTRATION (default=2) Self-registration OPENPROJECT_SENDMAIL__ARGUMENTS (default="-i") Arguments to call sendmail with in case it is configured as outgoing email setup OPENPROJECT_SENDMAIL__LOCATION (default="/usr/sbin/sendmail") Location of sendmail to call if it is configured as outgoing email setup @@ -377,7 +393,7 @@ OPENPROJECT_USER__DEFAULT__TIMEZONE (default=nil) Users default time zone OPENPROJECT_USER__FORMAT (default=:firstname_lastname) Users name format OPENPROJECT_USERS__DELETABLE__BY__ADMINS (default=false) User accounts deletable by admins OPENPROJECT_USERS__DELETABLE__BY__SELF (default=false) Users allowed to delete their accounts -OPENPROJECT_WEB (default={"workers" => 2, "timeout" => 120, "wait_timeout" => 30, "min_threads" => 4, "max_threads" => 16}) Web worker count and threads configuration +OPENPROJECT_WEB (default={"workers" => 2, "timeout" => 120, "wait_timeout" => 30, "min_threads" => 4, "max_threads" => 16, "term_on_timeout" => 1}) Web worker count and threads configuration OPENPROJECT_WELCOME__ON__HOMESCREEN (default=false) Display welcome block on homescreen OPENPROJECT_WELCOME__TEXT (default=nil) Welcome block text OPENPROJECT_WELCOME__TITLE (default=nil) Welcome block title diff --git a/lib/tasks/setting.rake b/lib/tasks/setting.rake index 270744f0728..daf7e254b2a 100644 --- a/lib/tasks/setting.rake +++ b/lib/tasks/setting.rake @@ -1,3 +1,5 @@ +# frozen_string_literal: true + #-- copyright # OpenProject is an open source project management software. # Copyright (C) the OpenProject GmbH @@ -61,9 +63,15 @@ namespace :setting do desc "List the supported environment variables to override settings" task available_envs: :environment do - Settings::Definition.all.sort.each do |_name, definition| - puts "#{Settings::Definition.possible_env_names(definition).first} " \ - "(default=#{definition.default.inspect}) #{definition.description}" + names_and_definitions = Settings::Definition.all.map do |_, definition| + env_name = Settings::Definition.possible_env_names(definition).first + env_name = definition.env_alias if definition.env_alias&.start_with?("OPENPROJECT_") + + [env_name, definition] + end + + names_and_definitions.sort_by { |env_name, _| env_name.downcase }.each do |env_name, definition| + puts "#{env_name} (default=#{definition.default.inspect}) #{definition.description}" end end end