Important

You are browsing documentation for version 6.1 of OroCommerce, supported until 2029. Read the documentation for the latest LTS version to get up-to-date information.

See our Release Process documentation for more information on the currently supported and upcoming releases.

Managing Application Configuration with .env-app Files and Real Environment Variables in Oro

This guide explains how to migrate an Oro application from a config/parameters.yml file to environment variables or a .env-app file.

You can find more DSN examples in the .env-app file at the application root folder or in the corresponding documentation sections.

Managing Application Configuration with .env-app Files

In an Oro application, you can manage environment variable configuration through .env-app files. These files define default values for the environment variables the application needs.

You can use four types of .env-app files:

.env-app — Default values for the environment variables the app needs.
.env-app.local — Uncommitted local overrides. Intended for local development; do not commit to version control.
.env-app.$ORO_ENV — Committed environment-specific defaults. For example, .env-app.prod holds the defaults for a production environment.
.env-app.$ORO_ENV.local — Uncommitted environment-specific overrides. Intended for local development; do not commit to version control.

Real environment variables take precedence over the .env-app files.

Do not define production secrets in any committed files. Instead, use environment variables for infrastructure configuration. To compile .env-app files for production, run composer dump-env prod.

This guide uses the file name .env-app rather than the commonly used .env file. DevOps teams and other services often use .env to manage environment variables, so a dedicated .env-app file prevents confusion, avoids adding the wrong file to version control, and keeps the Oro application’s configuration separate and easy to manage.

Migration from `config/parameters.yml` to Environment Variables or `.env-app`

Database Connection

Instead of using the following configuration in config/parameters.yml:

parameters:
    database_driver:         pdo_pgsql
    database_host:           '%env(ORO_DB_HOST)%'
    database_port:           '%env(ORO_DB_PORT)%'
    database_name:           '%env(ORO_DB_NAME)%'
    database_user:           '%env(ORO_DB_USER)%'
    database_password:       '%env(ORO_DB_PASSWORD)%'
    database_server_version: '%env(ORO_DB_VERSION)%'
    database_driver_options: []

You can now use a single environment variable with the DSN:

ORO_DB_DSN=postgres://oro_db_user:oro_db_pass@127.0.0.1:5432/oro_db?sslmode=disable&charset=utf8&serverVersion=13.7

The sslmode=disable parameter turns TLS off. To connect to the database over TLS, see Secure (TLS) Connections.

Web Socket Connections

Instead of using the following configuration in config/parameters.yml:

parameters:
    websocket_bind_address:                "0.0.0.0"  # The host IP the socket server will bind to
    websocket_bind_port:                   8080       # The port the socket server will listen on
    websocket_frontend_host:               "*"        # Websocket host the browser will connect to
    websocket_frontend_port:               8080       # Websocket port the browser will connect to
    websocket_frontend_path:               ""         # Websocket url path the browser will connect to (for example "/websocket" or "/ws")
    websocket_backend_host:                "*"        # Websocket host the application server will connect to
    websocket_backend_port:                8080       # Websocket port the application server will connect to
    websocket_backend_path:                ""         # Websocket url path the application server will connect to (for example "/websocket" or "/ws")
    websocket_backend_transport:           tcp        # Socket transport (for example "tcp", "ssl" or "tls")
    websocket_backend_ssl_context_options: {}         # Socket context options, usually needed when using secure transport

You can now use three environment variables with DSNs:

ORO_WEBSOCKET_SERVER_DSN=//0.0.0.0:8080
ORO_WEBSOCKET_FRONTEND_DSN=//*:8080/ws
ORO_WEBSOCKET_BACKEND_DSN=tcp://127.0.0.1:8080

Note that * means to listen to all hosts.

Search Engine Connections

Instead of using the following configuration in config/parameters.yml:

parameters:
    # search engine configuration
    search_engine_name:                 orm
    search_engine_host:                 '%env(ORO_SEARCH_HOST)%'
    search_engine_port:                 '%env(ORO_SEARCH_PORT)%'
    search_engine_index_prefix:         '%env(ORO_SEARCH_INDEX_PREFIX)%'
    search_engine_username:             '%env(ORO_SEARCH_USER)%'
    search_engine_password:             '%env(ORO_SEARCH_PASSWORD)%'
    search_engine_ssl_verification:     '%env(ORO_SEARCH_ENGINE_SSL_VERIFICATION)%'
    search_engine_ssl_cert:             '%env(ORO_SEARCH_ENGINE_SSL_CERT)%'
    search_engine_ssl_cert_password:    '%env(ORO_SEARCH_ENGINE_SSL_CERT_PASSWORD)%'
    search_engine_ssl_key:              '%env(ORO_SEARCH_ENGINE_SSL_KEY)%'
    search_engine_ssl_key_password:     '%env(ORO_SEARCH_ENGINE_SSL_KEY_PASSWORD)%'

    # website search engine configuration
    website_search_engine_index_prefix: '%env(ORO_SEARCH_WEBSITE_INDEX_PREFIX)%'

You can now use two environment variables with DSNs:

ORO_SEARCH_ENGINE_DSN=orm:?prefix=oro_search
ORO_WEBSITE_SEARCH_ENGINE_DSN=orm:?prefix=oro_website_search

For elasticsearch search engine, use the following format:

ORO_SEARCH_ENGINE_DSN=elastic-search://valid_user:valid_password@127.0.0.1:9200?prefix=oro_search

Note that in the above examples, valid_user:valid_password@ — DSNs part can be skipped if authentication is not enabled.

For a connection over HTTPS, use the https scheme, for example, ORO_SEARCH_ENGINE_DSN=https://valid_user:valid_password@es.example.com:9200?prefix=oro_search. See Secure (TLS) Connections.

Sessions Storage Configuration

Instead of using the session_handler parameter, you can now use the ORO_SESSION_DSN environment variable. The default value is native:, but you can provide a redis DSN to use redis as the session handler.

Redis Connections

To configure Redis connections, including types, instead of:

parameters:
    session_handler:         'oro.session_handler'
    redis_dsn_session:       'redis://127.0.0.1:6379/0'
    redis_dsn_cache:         'redis://127.0.0.1:6380/0'
    redis_dsn_doctrine:      'redis://127.0.0.1:6380/1'
    redis_dsn_session_type:  'standalone' #optional, current configuration is applied if it is not set
    redis_dsn_cache_type:    'standalone' #optional, current configuration is applied if it is not set
    redis_dsn_doctrine_type: 'standalone' #optional, current configuration is applied if it is not set

Use:

ORO_SESSION_DSN=redis://127.0.0.1:6379/0
ORO_REDIS_CACHE_DSN=redis://127.0.0.1:6379/1
ORO_REDIS_DOCTRINE_DSN=redis://127.0.0.1:6379/2
ORO_REDIS_LAYOUT_DSN=redis://127.0.0.1:6379/3

When configuring a Redis Sentinel or Cluster connection, use the correct DSN format.

For Sentinel connections, use the following format:

redis://127.0.0.1:26379?dbindex=1&redis_sentinel=lru_cache_mon

For Cluster connections, use the following format:

redis://password@127.0.0.1:6379?host[127.0.0.1:6380]&dbindex=1&cluster=predis

Note that in the above examples, the password and dbindex values are optional and should be replaced with the appropriate values for your configuration. Additionally, in cluster example you can add multiple hosts.

For a connection over TLS, use the rediss scheme. See Secure (TLS) Connections.

To allow setting Redis connection configurations from environment variables, run the following command:

composer set-parameters redis

RabbitMQ Connection

Instead of using the following configuration in config/parameters.yml:

parameters:
    message_queue_transport:        'amqp'
    message_queue_transport_config: { host: 'localhost', port: '5672', user: 'guest', password: 'guest', vhost: '/master' }

You can now use the ORO_MQ_DSN environment variable:

ORO_MQ_DSN=amqp://guest:guest@localhost:5672/%2Fmaster

When configuring a virtual host (vhost), ensure that the vhost is URL encoded. If no vhost is provided, the default value of / will be used. As an example, if the vhost is /master, the corresponding url encoded vhost value is %2Fmaster, and if the vhost is master, the url encoded value is master.

For a connection over TLS, use the amqps scheme, for example, ORO_MQ_DSN=amqps://guest:guest@rabbitmq.example.com:5671/%2Fmaster. See Secure (TLS) Connections.

Secure (TLS) Connections

The application can connect to PostgreSQL, Redis, RabbitMQ, Elasticsearch, SMTP servers, and Gotenberg over TLS.

For Redis, RabbitMQ, Elasticsearch, and Gotenberg, the scheme of the DSN or URL turns TLS on. The other parts of the DSN or URL do not change. For SMTP, the scheme and the port select the TLS mode. See SMTP. PostgreSQL uses its own connection parameters. See PostgreSQL.

SMTP has two TLS modes:

Implicit TLS — The connection is encrypted from the start.
STARTTLS — The connection starts without encryption. Then the application sends the STARTTLS command, and the connection continues with TLS.

Service	Environment variables	Plain scheme	TLS scheme	Default port
Redis	`ORO_SESSION_DSN`, `ORO_REDIS_CACHE_DSN`, `ORO_REDIS_DOCTRINE_DSN`, `ORO_REDIS_LAYOUT_DSN`	`redis://`	`rediss://`	6379
RabbitMQ	`ORO_MQ_DSN`	`amqp://`	`amqps://`	5672 for `amqp://`, 5671 for `amqps://`
Elasticsearch	`ORO_SEARCH_ENGINE_DSN`, `ORO_WEBSITE_SEARCH_ENGINE_DSN`	`elastic-search://`, `http://`	`https://`	80 for `http://`, 443 for `https://`
SMTP	`ORO_MAILER_DSN`	`smtp://` (STARTTLS or implicit TLS, see SMTP)	`smtps://`	465 for `smtps://` and for `smtp://` without a port, 25 for `smtp://localhost` without a port
Gotenberg	`ORO_PDF_GENERATOR_GOTENBERG_API_URL`	`http://`	`https://`	80 for `http://`, 443 for `https://`

Elasticsearch listens on port 9200 by default. If your Elasticsearch server uses this port, specify the port in the DSN.

For the TLS modes of the smtp:// DSN, see SMTP.

Certificate Verification

The application verifies the certificate of the server and the host name of the server. You can turn off these checks only with an option.

A certificate from a public certificate authority (CA) needs no option. Managed cloud services usually have such certificates. The application uses the trust store of the operating system. Redis, RabbitMQ, and SMTP use the CA bundle of OpenSSL. Elasticsearch and Gotenberg use the CA bundle of curl if the PHP curl extension is installed. Otherwise, they use the CA bundle of OpenSSL. Make sure that the image of the application contains the CA certificates of the operating system, for example, the ca-certificates package.
A certificate from a private or self-signed certificate authority needs the ssl[cafile] option. Set this option to the path of the CA certificate in PEM format.

For PostgreSQL, see PostgreSQL.

TLS Options

Add the options to the query string of the DSN or URL. The names of the options are the names of the PHP SSL context options.

Option	Description	Services
`ssl[cafile]`	The path to the CA certificate or the CA bundle that verifies the server certificate.	Redis, RabbitMQ, Elasticsearch, SMTP, Gotenberg
`ssl[capath]`	The path to a directory with CA certificates.	Redis, RabbitMQ, SMTP, Gotenberg
`ssl[verify_peer]`	`0` turns off the verification of the server certificate. Use this value only for testing. For Redis, SMTP, and Gotenberg, the application still verifies the host name. To turn off this verification too, set `ssl[verify_peer_name]` to `0`. For RabbitMQ, `0` also turns off the verification of the host name. To keep this verification, set `ssl[verify_peer_name]` to `1`. For Elasticsearch, `0` always turns off the verification of the host name.	Redis, RabbitMQ, Elasticsearch, SMTP, Gotenberg
`ssl[verify_peer_name]`	`0` turns off the verification of the host name. Use this value only for testing.	Redis, RabbitMQ, Elasticsearch, SMTP, Gotenberg
`ssl[peer_name]`	The host name that the server certificate must contain, if it is not the host of the DSN.	Redis, RabbitMQ, SMTP
`ssl[local_cert]`	The path to the client certificate, if the server requires one (mutual TLS).	Redis, RabbitMQ, Elasticsearch, SMTP, Gotenberg
`ssl[local_pk]`	The path to the private key of the client certificate.	Redis, RabbitMQ, Elasticsearch, SMTP, Gotenberg
`ssl[passphrase]`	The passphrase of the client certificate or of its private key.	Redis, RabbitMQ, Elasticsearch, SMTP, Gotenberg

The services accept the following options:

Redis, RabbitMQ, and SMTP — The options in the table and the other PHP SSL context options.
Elasticsearch — Only the options in the table. Another option causes an error.
Gotenberg — The options in the table except ssl[peer_name], and the ssl[ciphers], ssl[peer_fingerprint], and ssl[capture_peer_cert_chain] options. Another option causes an error.

The boolean options, such as ssl[verify_peer], ssl[verify_peer_name], and ssl[allow_self_signed], accept 1, 0, true, false, yes, no, on, and off. Another value causes an error, also with the plain redis:// scheme. The ssl[security_level], ssl[verify_depth], and ssl[crypto_method] options accept only a number. The largest value of ssl[security_level] is 5.

To set the lowest TLS version, use the ssl[min_proto_version] option, for example, ssl[min_proto_version]=32 for TLS 1.2. The ssl[min_proto_version] and ssl[max_proto_version] options accept only these values: 8 (TLS 1.0), 16 (TLS 1.1), 32 (TLS 1.2), and 64 (TLS 1.3). The ssl[crypto_method] option has no effect for Redis and RabbitMQ, because their client libraries set their own value.

Warning

Do not turn off the verification in production. Without it, the application cannot detect a server that pretends to be Redis, RabbitMQ, Elasticsearch, an SMTP server, or Gotenberg.

The TLS options need the TLS scheme:

For RabbitMQ, the TLS options with a plain scheme cause an error.
For Elasticsearch, the TLS options with a plain scheme and a host in the DSN cause an error. For a DSN without a host, the configured hosts must use the https scheme. See Custom SSL Configuration.
For Redis, the plain redis:// scheme ignores the TLS options that have a correct value. Always use rediss:// for TLS.
For SMTP, the TLS options apply to the TLS mode that the smtp:// DSN uses, implicit TLS or STARTTLS. See SMTP.
For Gotenberg, the TLS options with the http:// scheme cause an error.
ssl=1 does not turn on TLS. For Redis, PHP shows a warning, and the application ignores the parameter. In debug mode, this warning causes an error. For RabbitMQ, Elasticsearch, SMTP, and Gotenberg, ssl=1 causes an error. Use the rediss://, amqps://, https://, or smtps:// scheme.

Encode the reserved characters in the username, in the password, and in the values of the options, such as ssl[passphrase]. For example, encode @ as %40 and : as %3A. An @ that is not encoded can make the application read a part of a secret as the host. In a shell, put the DSN in quotes, because it contains the &, [, and ] characters.

PHP adds the arguments of functions to the stack trace of an error. These arguments can contain the passwords of the DSNs. In production, set zend.exception_ignore_args = On in php.ini. This is the value in php.ini-production.

Some applications build the DSNs from the short ORO_REDIS_URL and ORO_SEARCH_URL variables. These variables contain the connection URL without the options of the DSN. To turn on TLS, change the scheme in these variables, for example, ORO_REDIS_URL=rediss://redis.example.com:6379. To add TLS options, set the full DSN variables from the table above.

PostgreSQL

The database connection uses the TLS parameters of the PostgreSQL client library (libpq). Add them to the query string of ORO_DB_DSN. Doctrine DBAL passes the following parameters to the database driver:

sslmode — The TLS mode. Use verify-full in production. The mode has one of the following values:
- verify-full — Encrypts the connection and verifies the server certificate and the host name.
- verify-ca — Encrypts the connection and verifies the server certificate, but not the host name.
- require — Encrypts the connection without any verification.
- prefer — Tries TLS without any verification. If TLS fails, connects without TLS. This is the default value of the client library.
- disable — Turns TLS off.
sslrootcert — The path to the CA certificate that verifies the server certificate. For a certificate from a public certificate authority, set sslrootcert=system to use the trust store of the operating system. With sslrootcert=system, the default mode is verify-full, and a weaker mode causes an error.
sslcert and sslkey — The paths to the client certificate and its private key, if the server requires a client certificate.
sslcrl — The path to the certificate revocation list.

The following DSN connects to the database over TLS and verifies the server certificate with a private CA:

ORO_DB_DSN='postgres://oro_db_user:password@db.example.internal:5432/oro_db?sslmode=verify-full&sslrootcert=/etc/pki/oro/ca.pem&serverVersion=18'

All connections of the application to the database use these parameters. This includes the separate Doctrine connections, such as the message queue and session connections, and the database isolation of Behat tests.

Important

The sslrootcert=system value needs PostgreSQL client library version 16 or higher. This is the library that the PHP pdo_pgsql extension uses. Without sslrootcert, the client library reads the ~/.postgresql/root.crt file of the user that runs PHP, not the trust store of the operating system.

The application reads the database connection from ORO_DB_DSN. If ORO_DB_DSN is not set, the application uses ORO_DB_URL. The .env-app file of the application sets sslmode=disable in ORO_DB_URL. To turn on TLS, set ORO_DB_DSN with the TLS parameters, or change sslmode in ORO_DB_URL. A parameter in the DSN takes precedence over the PGSSLMODE environment variable of the client library. Thus, PGSSLMODE has no effect while the DSN contains sslmode=disable. If you remove sslmode from the DSN, the client library uses the prefer mode, which does not verify the server.

Doctrine DBAL does not pass the other TLS parameters of the client library, such as sslpassword, sslnegotiation, and ssl_min_protocol_version. To set them, use the PostgreSQL Environment Variables, for example, PGSSLMINPROTOCOLVERSION. sslpassword has no environment variable. To use a client key that is protected with a password, set sslpassword in a connection service file of the client library and select the service with the PGSERVICE environment variable. For more information about the parameters, see PostgreSQL SSL Support.

SMTP

The application sends email messages over SMTP with the SMTP settings of the system configuration, under System > Configuration > System Configuration > General Setup > Email Configuration. If these settings are not configured, the application uses ORO_MAILER_DSN. The scheme and the port of the DSN select the TLS mode:

smtps:// — Implicit TLS, on port 465 by default.
smtp:// with port 465, or without a port — Implicit TLS on port 465, the same as smtps://.
smtp:// with another port, for example, 587 — STARTTLS if the server offers it.
smtp://localhost without a port — Port 25 with STARTTLS if the server offers it.

STARTTLS is optional. If the server does not offer STARTTLS, the application sends the credentials and the email message without TLS. In this case, the TLS options have no effect. Thus, use implicit TLS or an SMTP server that always offers STARTTLS. If the server offers STARTTLS, but the TLS connection fails, for example, because the application cannot verify the server certificate, sending fails.

The following DSN uses STARTTLS and verifies the server certificate with a private CA:

ORO_MAILER_DSN='smtp://user:password@smtp.example.internal:587?ssl[cafile]=/etc/pki/oro/ca.pem'

The SMTP DSN also accepts the verify_peer and peer_fingerprint options of the Symfony mailer. If the DSN sets the same option in both forms, for example, verify_peer and ssl[verify_peer], the ssl[...] option takes precedence. Use the ssl[...] options, the same as for the other services.

The Encryption option of the SMTP settings has the following values in the system configuration and in the organization configuration:

SSL — Implicit TLS.
TLS — Mandatory STARTTLS. If the server does not offer STARTTLS, sending fails.
None — STARTTLS if the server offers it. Otherwise, the application sends email messages without TLS.

The SMTP settings of a mailbox have the same SSL and TLS values. An empty value has the same effect as None.

With port 465, the application uses implicit TLS for any Encryption value.

The SMTP settings of the system configuration have no TLS options. The application verifies the server certificate with the trust store of the operating system and of OpenSSL. For a private certificate authority, add the CA certificate to the trust store of the operating system, or set the openssl.cafile option in php.ini.

The Check Connection (Saved Settings) and Check Connection (New Settings) buttons of the SMTP settings, and the health check of the mail transport, use the same TLS settings as sending.

Gotenberg

The TLS options of ORO_PDF_GENERATOR_GOTENBERG_API_URL apply only to the requests to Gotenberg. These are the requests that generate PDF files and the request of the requirements check. The application removes the options from the URL before it sends a request.

The following URL connects to Gotenberg over HTTPS and verifies its certificate with a private CA:

ORO_PDF_GENERATOR_GOTENBERG_API_URL='https://gotenberg.example.internal:3000?ssl[cafile]=/etc/pki/oro/ca.pem'

The TLS options need the default HTTP client of the Gotenberg PDF engine, the psr18.http_client service. If you replace this service with another client, the generation of PDF files with the TLS options fails with an error. The requirements check uses another HTTP client and is not affected. For more information about Gotenberg, see OroPdfGeneratorBundle.

Example: Managed Services with Public Certificates (AWS)

This example uses Amazon ElastiCache for Redis with encryption in transit, Amazon MQ for RabbitMQ, Elastic Cloud for Elasticsearch, and Amazon Simple Email Service (SES) for SMTP. The certificates of these services come from public certificate authorities. Thus, the DSNs have no TLS options.

# ElastiCache for Redis (primary endpoint, AUTH token)
ORO_SESSION_DSN='rediss://:auth-token@master.oro-cache.abc123.use1.cache.amazonaws.com:6379/0'
ORO_REDIS_CACHE_DSN='rediss://:auth-token@master.oro-cache.abc123.use1.cache.amazonaws.com:6379/1'
ORO_REDIS_DOCTRINE_DSN='rediss://:auth-token@master.oro-cache.abc123.use1.cache.amazonaws.com:6379/2'
ORO_REDIS_LAYOUT_DSN='rediss://:auth-token@master.oro-cache.abc123.use1.cache.amazonaws.com:6379/3'

# Amazon MQ for RabbitMQ
ORO_MQ_DSN='amqps://oro:mq-password@b-1a2b3c4d-5e6f-7a8b-9c0d.mq.us-east-1.amazonaws.com:5671/%2F'

# Elastic Cloud
ORO_SEARCH_ENGINE_DSN='https://elastic:es-password@oro.es.us-east-1.aws.elastic-cloud.com:443?prefix=oro_search'
ORO_WEBSITE_SEARCH_ENGINE_DSN='https://elastic:es-password@oro.es.us-east-1.aws.elastic-cloud.com:443?prefix=oro_website_search'

# Amazon SES (SMTP credentials of SES, STARTTLS)
ORO_MAILER_DSN='smtp://ses-smtp-user:ses-smtp-password@email-smtp.us-east-1.amazonaws.com:587'

Note

The cluster option of the Redis DSN configures one primary node and replica nodes. It does not configure the Redis Cluster protocol. The cluster mode of ElastiCache supports only the database 0, but the DSNs above use four databases. Thus, use an ElastiCache replication group with the cluster mode disabled. Connect to its primary endpoint.

Note

Amazon OpenSearch Service is not Elasticsearch. The application supports Elasticsearch, for example, Elastic Cloud or an Elasticsearch cluster that you manage.

Note

The certificates of Amazon RDS for PostgreSQL come from the certificate authority of Amazon RDS, not from a public certificate authority. Download the certificate bundle of Amazon RDS and set it in sslrootcert, for example, sslmode=verify-full&sslrootcert=/etc/pki/oro/rds-global-bundle.pem.

Example: Services with a Private Certificate Authority

For services with certificates from a private certificate authority, add the ssl[cafile] option to each DSN. For PostgreSQL, add the sslmode and sslrootcert parameters:

ORO_DB_DSN='postgres://oro_db_user:password@db.example.internal:5432/oro_db?sslmode=verify-full&sslrootcert=/etc/pki/oro/ca.pem&serverVersion=18'
ORO_SESSION_DSN='rediss://:password@redis.example.internal:6379/0?ssl[cafile]=/etc/pki/oro/ca.pem'
ORO_REDIS_CACHE_DSN='rediss://:password@redis.example.internal:6379/1?ssl[cafile]=/etc/pki/oro/ca.pem'
ORO_REDIS_DOCTRINE_DSN='rediss://:password@redis.example.internal:6379/2?ssl[cafile]=/etc/pki/oro/ca.pem'
ORO_REDIS_LAYOUT_DSN='rediss://:password@redis.example.internal:6379/3?ssl[cafile]=/etc/pki/oro/ca.pem'
ORO_MQ_DSN='amqps://oro:password@rabbitmq.example.internal:5671/%2F?ssl[cafile]=/etc/pki/oro/ca.pem'
ORO_SEARCH_ENGINE_DSN='https://elastic:password@es.example.internal:9200?prefix=oro_search&ssl[cafile]=/etc/pki/oro/ca.pem'
ORO_WEBSITE_SEARCH_ENGINE_DSN='https://elastic:password@es.example.internal:9200?prefix=oro_website_search&ssl[cafile]=/etc/pki/oro/ca.pem'
ORO_MAILER_DSN='smtps://user:password@smtp.example.internal:465?ssl[cafile]=/etc/pki/oro/ca.pem'
ORO_PDF_GENERATOR_GOTENBERG_API_URL='https://gotenberg.example.internal:3000?ssl[cafile]=/etc/pki/oro/ca.pem'

Example: Redis Sentinel

The TLS settings apply to the sentinels. They also apply to the primary node and to the replica nodes that the sentinels return.

ORO_REDIS_CACHE_DSN='rediss://sentinel.example.internal:26379?redis_sentinel=oro_cache&dbindex=1&ssl[cafile]=/etc/pki/oro/ca.pem'

A sentinel usually returns the IP addresses of the nodes. The application then verifies the certificate of a node against its IP address. Use one of these solutions:

Add the IP addresses of the nodes to their certificates.
Configure the sentinels to return host names (sentinel announce-hostnames yes and sentinel resolve-hostnames yes).
Add the ssl[peer_name] option with the name in the certificates of the nodes.

Example: Client Certificate (Mutual TLS)

ORO_MQ_DSN='amqps://oro:password@rabbitmq.example.internal:5671/%2F?ssl[cafile]=/etc/pki/oro/ca.pem&ssl[local_cert]=/etc/pki/oro/client.pem&ssl[local_pk]=/etc/pki/oro/client.key'

Message Queue Consumer Timeouts

Note

The configurable consumer receive_timeout option is available as of OroCommerce version 6.1.10.

You can tune the message queue consumer timeout with the following environment variable:

ORO_MQ_CONSUMER_RECEIVE_TIMEOUT=1.0

ORO_MQ_CONSUMER_RECEIVE_TIMEOUT sets the maximum time in seconds a consumer waits to receive a message from a single bound queue per receive cycle before moving on to the next queue. The default value is 1.0 second.

The variable overrides the corresponding oro_message_queue.consumer.receive_timeout configuration option.

Message Queue Consumption Mode

Note

Consumption modes are available as of OroCommerce version 6.1.10.

You can use the following environment variable to select the consumption mode, which determines the order in which a consumer visits multiple queues.

ORO_MQ_CONSUMPTION_MODE=default

ORO_MQ_CONSUMPTION_MODE sets the consumption mode used when a consumer is bound to more than one queue. It is an alternative to the --mode CLI option of the consume commands. The default value is default (round-robin). For the list of available modes, see Consumption Modes.

MongoDB Connection

To configure MongoDB as a file storage, instead of:

parameters:
    gaufrette_adapter.public:  'gridfs:mongodb://user:password@host1:27017,host2:27017/media'
    gaufrette_adapter.private: 'gridfs:mongodb://user:password@host1:27017,host2:27017/media'

Use:

ORO_MONGODB_DSN_PUBLIC=mongodb://127.0.0.1:27017/media
ORO_MONGODB_DSN_PRIVATE=mongodb://127.0.0.1:27017/private

Each value is a complete MongoDB connection string. The database name follows the host list, and the URI options follow the database name. The connection string supports the URI options, for example replicaSet, authSource, and tls, and the mongodb+srv scheme.

The connection string contains the credentials of the MongoDB user, so provide it through the secret mechanism of the deployment and rotate it as any other credential.

The connection string must meet the following requirements:

The scheme is mongodb or mongodb+srv, in lower case.
The database name follows the host list and precedes the URI options.
The database name does not contain a control character, a space, or any of the ", $, ., /, and \ characters.
The reserved characters in the username and the password are percent-encoded.

The following example configures a connection over TLS:

ORO_MONGODB_DSN_PUBLIC='mongodb://user:password@host1:27017/media?tls=true&tlsCAFile=/etc/pki/ca.crt'
ORO_MONGODB_DSN_PRIVATE='mongodb://user:password@host1:27017/private?tls=true&tlsCAFile=/etc/pki/ca.crt'

The following example configures a connection to a seed list:

ORO_MONGODB_DSN_PUBLIC=mongodb+srv://user:password@cluster0.example.com/media
ORO_MONGODB_DSN_PRIVATE=mongodb+srv://user:password@cluster0.example.com/private

The ORO_MONGODB_SERVER variable is a short form of the two variables above. The application adds /media and /private to its value. Use this variable only when the connection string ends with the host list, that is, when it contains no trailing slash and no URI options. In all other cases, set ORO_MONGODB_DSN_PUBLIC and ORO_MONGODB_DSN_PRIVATE directly.

For the same connection string in the parameters.yml file, see File System Adapters Configuration with parameters.yml.

To allow setting MongoDB connection configurations from environment variables, run the following command:

composer set-parameters mongo

Enterprise License, PNGQuant and JPEGOptim Libraries Paths

These parameters:

parameters:
    enterprise_licence:             ~
    enterprise_licence_start:       ~
    liip_imagine.jpegoptim.binary:  null
    liip_imagine.pngquant.binary:   null

Are now set using the corresponding environment variables:

ORO_ENTERPRISE_LICENCE=
ORO_ENTERPRISE_LICENCE_START=
ORO_JPEGOPTIM_BINARY=
ORO_PNGQUANT_BINARY=

Web Backend Prefix

By default, Oro applications use the /admin path as the backend prefix.

To override this default value, you can define a custom prefix in the config/config.yml file.

For example:

web_backend_prefix: '/my_admin_prefix'

Deployment Type

The deployment_type parameter has been removed. Use custom Symfony application environments instead. Set the Symfony application environment with the ORO_ENV environment variable:

ORO_ENV=prod

Other Configuration

The following parameters are read from environment variables as before:

secret
mailer_dsn
tracking_data_folder

These parameters should be configured in the environment variables, such as ORO_SECRET, ORO_MAILER_DSN and ORO_TRACKING_DATA_FOLDER.

Managing Application Configuration with .env-app Files and Real Environment Variables in Oro

Managing Application Configuration with .env-app Files

Migration from config/parameters.yml to Environment Variables or .env-app

Database Connection

Web Socket Connections

Search Engine Connections

Sessions Storage Configuration

Redis Connections

RabbitMQ Connection

Secure (TLS) Connections

Certificate Verification

TLS Options

PostgreSQL

SMTP

Gotenberg

Example: Managed Services with Public Certificates (AWS)

Example: Services with a Private Certificate Authority

Example: Redis Sentinel

Example: Client Certificate (Mutual TLS)

Message Queue Consumer Timeouts

Message Queue Consumption Mode

MongoDB Connection

Enterprise License, PNGQuant and JPEGOptim Libraries Paths

Web Backend Prefix

Deployment Type

Other Configuration

Migration from `config/parameters.yml` to Environment Variables or `.env-app`