references/openproject
1
0
Fork 0
mirror of https://github.com/opf/openproject.git synced 2026-06-14 03:30:14 +00:00
Code Issues Packages Projects Releases Wiki Activity

Merge pull request #20993 from opf/env-settings-doc

Browse Source 
Clarify task and docs around supported env vars
This commit is contained in:
Jan Sandbrink
2025-11-21 15:32:29 +01:00
committed by GitHub
parent 9a49878292 bc26a28335
commit 73496dede3
2 changed files with 36 additions and 12 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/installation-and-operations/configuration/environment/README.md
+25 -9
View File
@@ -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
lib/tasks/setting.rake
+11 -3
View File
@@ -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