Environment variables

NOTE: This documentation is for OpenProject on-premises Installations only, if you would like to setup similar in your OpenProject cloud instance, please contact us at support@openproject.com

When using environment variables, you can set the options by setting environment variables with the name of the options below in uppercase. So for example, to configure email delivery via an SMTP server, you can set the following environment variables:

EMAIL_DELIVERY_METHOD="smtp"
SMTP_ADDRESS="smtp.example.net"
SMTP_PORT="587"
SMTP_DOMAIN="example.net"
SMTP_AUTHENTICATION="plain"
SMTP_USER_NAME="user"
SMTP_PASSWORD="password"
SMTP_ENABLE_STARTTLS_AUTO="true"

In case you want to use environment variables, but you have no easy way to set them on a specific system, you can use the dotenv gem. It automatically sets environment variables written to a .env file for a Rails application.

Please be aware that only those variables shall be edited which are documented as not everything is meant to be configured or bend.

Nested values

You can override nested configuration values as well by joining the respective hash keys with underscores. Underscores within keys have to be escaped by doubling them. For example, given the following configuration:

storage:
  tmp_path: tmp

You can override it by defining the following environment variable:

OPENPROJECT_STORAGE_TMP__PATH=/some/other/path

You can also add new values this way. For instance you could add another field ‘type’ to the storage config above like this:

OPENPROJECT_STORAGE_TYPE=nfs

Passing data structures to the app

The configuration uses YAML to parse overrides from ENV. Using YAML inline syntax, you can:

  1. Pass a symbol as an override using OPENPROJECT_SESSION_STORE=":active_record_store"

  2. Pass arrays by wrapping values in brackets (e.g., [val1, val2, val3]).

  3. Pass hashes with {key: foo, key2: bar}.

To pass symbol arrays or hashes with symbol keys, use the YAML !ruby/symbol notation. Example: {!ruby/symbol key: !ruby/symbol value} will be parsed as { key: :value }.

Please note: The Configuration is a HashWithIndifferentAccess and thus it should be irrelevant for hashes to use symbol keys.

Here an Example:

Configured in the /etc/openproject/conf.d/env like this:

OPENPROJECT_ENTERPRISE_FAIL__FAST=true

# is the same as

OPENPROJECT_ENTERPRISE="{ fail_fast: true }"

# in the old configration.yml it looked like this

enterprise:
  fail_fast: true

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:

For packaged installations:

sudo openproject run bundle exec rake setting:available_envs

For Docker installations:

docker exec -it $(docker ps | grep web | cut -d' ' -f 1) bash -c "RAILS_ENV=production 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.

OPENPROJECT_ACTIVITY__DAYS__DEFAULT (default=30)
OPENPROJECT_ADDITIONAL__FOOTER__CONTENT (default=nil)
OPENPROJECT_AFTER__FIRST__LOGIN__REDIRECT__URL (default=nil)
OPENPROJECT_AFTER__LOGIN__DEFAULT__REDIRECT__URL (default=nil)
OPENPROJECT_APIV3__CORS__ENABLED (default=false)
OPENPROJECT_APIV3__CORS__ORIGINS (default=[])
OPENPROJECT_APIV3__DOCS__ENABLED (default=true)
OPENPROJECT_APIV3__ENABLE__BASIC__AUTH (default=true)
OPENPROJECT_APIV3__MAX__PAGE__SIZE (default=1000)
OPENPROJECT_APP__TITLE (default="OpenProject")
OPENPROJECT_APPSIGNAL__FRONTEND__KEY (default=nil)
OPENPROJECT_ATTACHMENT__MAX__SIZE (default=5120)
OPENPROJECT_ATTACHMENT__WHITELIST (default=[])
OPENPROJECT_ATTACHMENTS__GRACE__PERIOD (default=180)
OPENPROJECT_ATTACHMENTS__STORAGE (default=:file)
OPENPROJECT_ATTACHMENTS__STORAGE__PATH (default=nil)
OPENPROJECT_AUTH__SOURCE__SSO (default=nil)
OPENPROJECT_AUTHENTICATION (default=nil)
OPENPROJECT_AUTOFETCH__CHANGESETS (default=true)
OPENPROJECT_AUTOLOGIN (default=0)
OPENPROJECT_AUTOLOGIN__COOKIE__NAME (default="autologin")
OPENPROJECT_AUTOLOGIN__COOKIE__PATH (default="/")
OPENPROJECT_AUTOLOGIN__COOKIE__SECURE (default=false)
OPENPROJECT_AVAILABLE__LANGUAGES (default=["en", "de", "fr", "es", "pt", "pt-BR", "it", "zh-CN", "ko", "ru"])
OPENPROJECT_AVATAR__LINK__EXPIRY__SECONDS (default=86400)
OPENPROJECT_BACKUP__ATTACHMENT__SIZE__MAX__SUM__MB (default=1024)
OPENPROJECT_BACKUP__DAILY__LIMIT (default=3)
OPENPROJECT_BACKUP__ENABLED (default=true)
OPENPROJECT_BACKUP__INCLUDE__ATTACHMENTS (default=true)
OPENPROJECT_BACKUP__INITIAL__WAITING__PERIOD (default=86400)
OPENPROJECT_BCC__RECIPIENTS (default=true)
OPENPROJECT_BLACKLISTED__ROUTES (default=[])
OPENPROJECT_BOARDS__DEMO__DATA__AVAILABLE (default=false)
OPENPROJECT_BRUTE__FORCE__BLOCK__AFTER__FAILED__LOGINS (default=20)
OPENPROJECT_BRUTE__FORCE__BLOCK__MINUTES (default=30)
OPENPROJECT_CACHE__EXPIRES__IN__SECONDS (default=nil)
OPENPROJECT_CACHE__FORMATTED__TEXT (default=true)
OPENPROJECT_CACHE__MEMCACHE__SERVER (default=nil)
OPENPROJECT_CACHE__NAMESPACE (default=nil)
OPENPROJECT_COMMIT__FIX__DONE__RATIO (default=100)
OPENPROJECT_COMMIT__FIX__KEYWORDS (default="fixes,closes")
OPENPROJECT_COMMIT__FIX__STATUS__ID (default=nil)
OPENPROJECT_COMMIT__LOGS__ENCODING (default="UTF-8")
OPENPROJECT_COMMIT__LOGTIME__ACTIVITY__ID (default=nil)
OPENPROJECT_COMMIT__LOGTIME__ENABLED (default=false)
OPENPROJECT_COMMIT__REF__KEYWORDS (default="refs,references,IssueID")
OPENPROJECT_CONSENT__DECLINE__MAIL (default=nil)
OPENPROJECT_CONSENT__INFO (default={"en"=>"## Consent\n\nYou need to agree to the [privacy and security policy](https://www.openproject.org/data-privacy-and-security/) of this OpenProject instance."})
OPENPROJECT_CONSENT__REQUIRED (default=false)
OPENPROJECT_CONSENT__TIME (default=nil)
OPENPROJECT_COST__REPORTING__CACHE__FILTER__CLASSES (default=true)
OPENPROJECT_CROSS__PROJECT__WORK__PACKAGE__RELATIONS (default=true)
OPENPROJECT_CROWDIN__IN__CONTEXT__TRANSLATIONS (default=true)
OPENPROJECT_DATABASE__CIPHER__KEY (default=nil)
OPENPROJECT_DATE__FORMAT (default=nil)
OPENPROJECT_DEFAULT__AUTO__HIDE__POPUPS (default=true)
OPENPROJECT_DEFAULT__COMMENT__SORT__ORDER (default="asc")
OPENPROJECT_DEFAULT__LANGUAGE (default="en")
OPENPROJECT_DEFAULT__PROJECTS__MODULES (default=["calendar", "board_view", "work_package_tracking", "news", "costs", "wiki"])
OPENPROJECT_DEFAULT__PROJECTS__PUBLIC (default=false)
OPENPROJECT_DEMO__PROJECTS__AVAILABLE (default=false)
OPENPROJECT_DEMO__VIEW__OF__TYPE__TEAM__PLANNER__SEEDED (default=false)
OPENPROJECT_DEMO__VIEW__OF__TYPE__WORK__PACKAGES__TABLE__SEEDED (default=false)
OPENPROJECT_DIFF__MAX__LINES__DISPLAYED (default=1500)
OPENPROJECT_DIRECT__UPLOADS (default=true)
OPENPROJECT_DISABLE__BROWSER__CACHE (default=true)
OPENPROJECT_DISABLE__PASSWORD__CHOICE (default=false)
OPENPROJECT_DISABLE__PASSWORD__LOGIN (default=false)
OPENPROJECT_DISABLED__MODULES (default=[])
OPENPROJECT_DISPLAY__SUBPROJECTS__WORK__PACKAGES (default=true)
OPENPROJECT_DROP__OLD__SESSIONS__ON__LOGIN (default=false)
OPENPROJECT_DROP__OLD__SESSIONS__ON__LOGOUT (default=true)
OPENPROJECT_EDITION (default="standard")
OPENPROJECT_EE__MANAGER__VISIBLE (default=true)
OPENPROJECT_EMAIL__DELIVERY__CONFIGURATION (default="inapp")
OPENPROJECT_EMAIL__DELIVERY__METHOD (default=nil)
OPENPROJECT_EMAIL__LOGIN (default=false)
OPENPROJECT_EMAILS__FOOTER (default={"en"=>""})
OPENPROJECT_EMAILS__HEADER (default={"en"=>""})
OPENPROJECT_ENABLE__INTERNAL__ASSETS__SERVER (default=false)
OPENPROJECT_ENABLED__PROJECTS__COLUMNS (default=["project_status", "public", "created_at", "latest_activity_at", "required_disk_space"])
OPENPROJECT_ENABLED__SCM (default=["subversion", "git"])
OPENPROJECT_ENTERPRISE__CHARGEBEE__SITE (default="openproject-enterprise")
OPENPROJECT_ENTERPRISE__PLAN (default="enterprise-on-premises---euro---1-year")
OPENPROJECT_ENTERPRISE__TRIAL__CREATION__HOST (default="https://augur.openproject.com")
OPENPROJECT_FEEDS__ENABLED (default=true)
OPENPROJECT_FEEDS__LIMIT (default=15)
OPENPROJECT_FILE__MAX__SIZE__DISPLAYED (default=512)
OPENPROJECT_FIRST__WEEK__OF__YEAR (default=nil)
OPENPROJECT_FOG (default={})
OPENPROJECT_FOG__DOWNLOAD__URL__EXPIRES__IN (default=21600)
OPENPROJECT_FORCE__FORMATTING__HELP__LINK (default=nil)
OPENPROJECT_FORCE__HELP__LINK (default=nil)
OPENPROJECT_FORCED__SINGLE__PAGE__SIZE (default=250)
OPENPROJECT_GRAVATAR__FALLBACK__IMAGE (default="404")
OPENPROJECT_HEALTH__CHECKS__AUTHENTICATION__PASSWORD (default=nil)
OPENPROJECT_HEALTH__CHECKS__BACKLOG__THRESHOLD (default=20)
OPENPROJECT_HEALTH__CHECKS__JOBS__NEVER__RAN__MINUTES__AGO (default=5)
OPENPROJECT_HEALTH__CHECKS__JOBS__QUEUE__COUNT__THRESHOLD (default=50)
OPENPROJECT_HIDDEN__MENU__ITEMS (default={})
OPENPROJECT_HOST__NAME (default="localhost:3000")
OPENPROJECT_HSTS (default=true)
OPENPROJECT_HTTPS (default=true)
OPENPROJECT_IMPRESSUM__LINK (default=nil)
OPENPROJECT_INSTALLATION__TYPE (default="manual")
OPENPROJECT_INSTALLATION__UUID (default=nil)
OPENPROJECT_INTERNAL__PASSWORD__CONFIRMATION (default=true)
OPENPROJECT_INVITATION__EXPIRATION__DAYS (default=7)
OPENPROJECT_JOURNAL__AGGREGATION__TIME__MINUTES (default=5)
OPENPROJECT_LDAP__AUTH__SOURCE__TLS__OPTIONS (default=nil)
OPENPROJECT_LDAP__FORCE__NO__PAGE (default=nil)
OPENPROJECT_LDAP__GROUPS__DISABLE__SYNC__JOB (default=false)
OPENPROJECT_LDAP__TLS__OPTIONS (default={})
OPENPROJECT_LDAP__USERS__DISABLE__SYNC__JOB (default=false)
OPENPROJECT_LDAP__USERS__SYNC__STATUS (default=false)
OPENPROJECT_LOG__LEVEL (default="info")
OPENPROJECT_LOG__REQUESTING__USER (default=false)
OPENPROJECT_LOGIN__REQUIRED (default=false)
OPENPROJECT_LOGRAGE__FORMATTER (default=nil)
OPENPROJECT_LOST__PASSWORD (default=true)
OPENPROJECT_MAIL__FROM (default="openproject@example.net")
OPENPROJECT_MAIL__HANDLER__API__KEY (default=nil)
OPENPROJECT_MAIL__HANDLER__BODY__DELIMITER__REGEX (default="")
OPENPROJECT_MAIL__HANDLER__BODY__DELIMITERS (default="")
OPENPROJECT_MAIL__HANDLER__IGNORE__FILENAMES (default="signature.asc")
OPENPROJECT_MAIL__SUFFIX__SEPARATORS (default="+")
OPENPROJECT_MAIN__CONTENT__LANGUAGE (default="english")
OPENPROJECT_MIGRATION__CHECK__ON__EXCEPTIONS (default=true)
OPENPROJECT_NEW__PROJECT__USER__ROLE__ID (default=nil)
OPENPROJECT_NOTIFICATION__EMAIL__DELAY__MINUTES (default=15)
OPENPROJECT_NOTIFICATION__EMAIL__DIGEST__TIME (default="08:00")
OPENPROJECT_OAUTH__ALLOW__REMAPPING__OF__EXISTING__USERS (default=false)
OPENPROJECT_OMNIAUTH__DIRECT__LOGIN__PROVIDER (default=nil)
OPENPROJECT_ONBOARDING__ENABLED (default=true)
OPENPROJECT_ONBOARDING__VIDEO__URL (default="https://player.vimeo.com/video/163426858?autoplay=1")
OPENPROJECT_OPENID__CONNECT (default={})
OPENPROJECT_OVERRIDE__BCRYPT__COST__FACTOR (default=nil)
OPENPROJECT_PASSWORD__ACTIVE__RULES (default=["lowercase", "uppercase", "numeric", "special"])
OPENPROJECT_PASSWORD__COUNT__FORMER__BANNED (default=0)
OPENPROJECT_PASSWORD__DAYS__VALID (default=0)
OPENPROJECT_PASSWORD__MIN__ADHERED__RULES (default=0)
OPENPROJECT_PASSWORD__MIN__LENGTH (default=10)
OPENPROJECT_PER__PAGE__OPTIONS (default="20, 100")
OPENPROJECT_PLAIN__TEXT__MAIL (default=false)
OPENPROJECT_PLUGIN__COSTS (default={"costs_currency"=>"EUR", "costs_currency_format"=>"%n %u"})
OPENPROJECT_PLUGIN__OPENPROJECT__AUTH__SAML (default={"providers"=>nil})
OPENPROJECT_PLUGIN__OPENPROJECT__AVATARS (default={"enable_gravatars"=>true, "enable_local_avatars"=>true})
OPENPROJECT_PLUGIN__OPENPROJECT__BACKLOGS (default={"story_types"=>nil, "task_type"=>nil, "card_spec"=>nil})
OPENPROJECT_PLUGIN__OPENPROJECT__BIM (default={})
OPENPROJECT_PLUGIN__OPENPROJECT__BOARDS (default=nil)
OPENPROJECT_PLUGIN__OPENPROJECT__CALENDAR (default=nil)
OPENPROJECT_PLUGIN__OPENPROJECT__LDAP__GROUPS (default={})
OPENPROJECT_PLUGIN__OPENPROJECT__OPENID__CONNECT (default=nil)
OPENPROJECT_PLUGIN__OPENPROJECT__RECAPTCHA (default={"recaptcha_type"=>"disabled"})
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)
OPENPROJECT_RAILS__ASSET__HOST (default=nil)
OPENPROJECT_RAILS__CACHE__STORE (default=:file_store)
OPENPROJECT_RAILS__RELATIVE__URL__ROOT (default="")
OPENPROJECT_RECAPTCHA__VIA__HCAPTCHA (default=false)
OPENPROJECT_REGISTRATION__FOOTER (default={"en"=>""})
OPENPROJECT_REPORT__INCOMING__EMAIL__ERRORS (default=true)
OPENPROJECT_REPOSITORIES__AUTOMATIC__MANAGED__VENDOR (default=nil)
OPENPROJECT_REPOSITORIES__ENCODINGS (default=nil)
OPENPROJECT_REPOSITORY__AUTHENTICATION__CACHING__ENABLED (default=true)
OPENPROJECT_REPOSITORY__CHECKOUT__DATA (default={"git"=>{"enabled"=>0}, "subversion"=>{"enabled"=>0}})
OPENPROJECT_REPOSITORY__LOG__DISPLAY__LIMIT (default=100)
OPENPROJECT_REPOSITORY__STORAGE__CACHE__MINUTES (default=720)
OPENPROJECT_REPOSITORY__TRUNCATE__AT (default=500)
OPENPROJECT_REST__API__ENABLED (default=true)
OPENPROJECT_SAML (default=nil)
OPENPROJECT_SCM (default={})
OPENPROJECT_SCM__GIT__COMMAND (default=nil)
OPENPROJECT_SCM__LOCAL__CHECKOUT__PATH (default="repositories")
OPENPROJECT_SCM__SUBVERSION__COMMAND (default=nil)
OPENPROJECT_SECURITY__BADGE__DISPLAYED (default=true)
OPENPROJECT_SECURITY__BADGE__URL (default="https://releases.openproject.com/v1/check.svg")
OPENPROJECT_SELF__REGISTRATION (default=2)
OPENPROJECT_SENDMAIL__ARGUMENTS (default="-i")
OPENPROJECT_SENDMAIL__LOCATION (default="/usr/sbin/sendmail")
OPENPROJECT_SESSION__COOKIE__NAME (default="_open_project_session")
OPENPROJECT_SESSION__STORE (default=:active_record_store)
OPENPROJECT_SESSION__TTL (default=120)
OPENPROJECT_SESSION__TTL__ENABLED (default=false)
OPENPROJECT_SHOW__COMMUNITY__LINKS (default=true)
OPENPROJECT_SHOW__PENDING__MIGRATIONS__WARNING (default=true)
OPENPROJECT_SHOW__SETTING__MISMATCH__WARNING (default=true)
OPENPROJECT_SHOW__STORAGE__INFORMATION (default=true)
OPENPROJECT_SHOW__WARNING__BARS (default=true)
OPENPROJECT_SMTP__ADDRESS (default="")
OPENPROJECT_SMTP__AUTHENTICATION (default="plain")
OPENPROJECT_SMTP__DOMAIN (default="your.domain.com")
OPENPROJECT_SMTP__ENABLE__STARTTLS__AUTO (default=false)
OPENPROJECT_SMTP__OPENSSL__VERIFY__MODE (default="peer")
OPENPROJECT_SMTP__PASSWORD (default="")
OPENPROJECT_SMTP__PORT (default=587)
OPENPROJECT_SMTP__SSL (default=false)
OPENPROJECT_SMTP__USER__NAME (default="")
OPENPROJECT_SOFTWARE__NAME (default="OpenProject")
OPENPROJECT_SOFTWARE__URL (default="https://www.openproject.org/")
OPENPROJECT_SQL__SLOW__QUERY__THRESHOLD (default=2000)
OPENPROJECT_START__OF__WEEK (default=nil)
OPENPROJECT_STATSD (default={"host"=>nil, "port"=>8125})
OPENPROJECT_SYS__API__ENABLED (default=false)
OPENPROJECT_SYS__API__KEY (default=nil)
OPENPROJECT_TIME__FORMAT (default=nil)
OPENPROJECT_USER__DEFAULT__TIMEZONE (default=nil)
OPENPROJECT_USER__FORMAT (default=:firstname_lastname)
OPENPROJECT_USERS__DELETABLE__BY__ADMINS (default=false)
OPENPROJECT_USERS__DELETABLE__BY__SELF (default=false)
OPENPROJECT_WEB (default={"workers"=>2, "timeout"=>120, "wait_timeout"=>10, "min_threads"=>4, "max_threads"=>16})
OPENPROJECT_WELCOME__ON__HOMESCREEN (default=false)
OPENPROJECT_WELCOME__TEXT (default=nil)
OPENPROJECT_WELCOME__TITLE (default=nil)
OPENPROJECT_WORK__PACKAGE__DONE__RATIO (default="field")
OPENPROJECT_WORK__PACKAGE__LIST__DEFAULT__COLUMNS (default=["id", "subject", "type", "status", "assigned_to", "priority"])
OPENPROJECT_WORK__PACKAGE__LIST__DEFAULT__HIGHLIGHTED__ATTRIBUTES (default=[])
OPENPROJECT_WORK__PACKAGE__LIST__DEFAULT__HIGHLIGHTING__MODE (default="none")
OPENPROJECT_WORK__PACKAGE__STARTDATE__IS__ADDDATE (default=false)
OPENPROJECT_WORK__PACKAGES__DURATION__FIELD__ACTIVE (default=false)
OPENPROJECT_WORK__PACKAGES__PROJECTS__EXPORT__LIMIT (default=500)
OPENPROJECT_YOUTUBE__CHANNEL (default="https://www.youtube.com/c/OpenProjectCommunity")

Environment-specific configuration variables

Docker

PostgreSQL statement_timeout

In docker installations, there is a default statement_timeout of 90s set for the docker image. To override this value in case you’re getting statement timeout errors such as “ERROR: canceling statement due to statement timeout”, use the environment variable POSTGRES_STATEMENT_TIMEOUT