مراية لـ
https://github.com/postalserver/postal.git
تم المزامنة 2025-12-01 05:43:04 +00:00
feat: new configuration system (and schema) (#2819)
هذا الالتزام موجود في:
Adam Cooke
31
doc/config/configuration.md
Normal file
31
doc/config/configuration.md
Normal file
@@ -0,0 +1,31 @@
|
||||
# Configuring Postal
|
||||
|
||||
Postal can be configured in two ways: using a YAML-based configuration file or through environment variables.
|
||||
|
||||
If you choose to use environment variables, you don't need to provide a config file. A full list of environment variables is available in the `environment-variables.md` file in this directory.
|
||||
|
||||
To use a configuration file, the `POSTAL_CONFIG_FILE_PATH` environment variable will dictate where Postal will look for the config file. An example YAML file containing all available configuration is provided in the `yaml.yml` file in this directory. Remember to include the `version: 2` key/value in your configuration file.
|
||||
|
||||
## Development
|
||||
|
||||
When developing with Postal, you can configure the application by placing a configuration file in `config/postal/postal.yml`. Alternatively, you can use environment variables by placing configuration in `.env` in the root of the application.
|
||||
|
||||
### Running tests
|
||||
|
||||
By default, tests will use the `config/postal/postal.test.yml` configuration file and the `.env.test` environment file.
|
||||
|
||||
## Containers
|
||||
|
||||
Within a container, Postal will for a config file in `/config/postal.yml` unless overriden by the `POSTAL_CONFIG_FILE_PATH` environment variable.
|
||||
|
||||
## Ports & Bind Addresses
|
||||
|
||||
The web & SMTP server listen on ports and addresses. The defaults for these can be set through configuration however, if you're running multiple instances of these on a single host you will need to specify different ports for each one.
|
||||
|
||||
You can use the `PORT` and `BIND_ADDRESS` environment variables to provide instance-specific values for these processes.
|
||||
|
||||
Additionally, `HEALTH_SERVER_PORT` and `HEALTH_SERVER_BIND_ADDRESS` can be used to set the port/address to use for running the health server alongside other processes.
|
||||
|
||||
## Legacy configuration
|
||||
|
||||
Legacy configuration files from Postal v1 and v2 are still supported. If you wish to use a new configuration option that is not available in the legacy format, you will need to upgrade the file to version 2.
|
||||
90
doc/config/environment-variables.md
Normal file
90
doc/config/environment-variables.md
Normal file
@@ -0,0 +1,90 @@
|
||||
# Environment Variables
|
||||
|
||||
This document contains all the environment variables which are available for this application.
|
||||
|
||||
| Name | Type | Description | Default |
|
||||
| ---- | ---- | ----------- | ------- |
|
||||
| `POSTAL_WEB_HOSTNAME` | String | The hostname that the Postal web interface runs on | postal.example.com |
|
||||
| `POSTAL_WEB_PROTOCOL` | String | The HTTP protocol to use for the Postal web interface | https |
|
||||
| `POSTAL_SMTP_HOSTNAME` | String | The hostname that the Postal SMTP server runs on | postal.example.com |
|
||||
| `POSTAL_USE_IP_POOLS` | Boolean | Should IP pools be enabled for this installation? | false |
|
||||
| `POSTAL_DEFAULT_MAXIMUM_DELIVERY_ATTEMPTS` | Integer | The maximum number of delivery attempts | 18 |
|
||||
| `POSTAL_DEFAULT_MAXIMUM_HOLD_EXPIRY_DAYS` | Integer | The number of days to hold a message before they will be expired | 7 |
|
||||
| `POSTAL_DEFAULT_SUPPRESSION_LIST_AUTOMATIC_REMOVAL_DAYS` | Integer | The number of days an address will remain in a suppression list before being removed | 30 |
|
||||
| `POSTAL_DEFAULT_SPAM_THRESHOLD` | Integer | The default threshold at which a message should be treated as spam | 5 |
|
||||
| `POSTAL_DEFAULT_SPAM_FAILURE_THRESHOLD` | Integer | The default threshold at which a message should be treated as spam failure | 20 |
|
||||
| `POSTAL_USE_LOCAL_NS_FOR_DOMAIN_VERIFICATION` | Boolean | Domain verification and checking usually checks with a domain's nameserver. Enable this to check with the server's local nameservers. | false |
|
||||
| `POSTAL_USE_RESENT_SENDER_HEADER` | Boolean | Append a Resend-Sender header to all outgoing e-mails | true |
|
||||
| `POSTAL_SIGNING_KEY_PATH` | String | Path to the private key used for signing | config/postal/signing.key |
|
||||
| `POSTAL_SMTP_RELAYS` | Array of strings | An array of SMTP relays in the format of smtp://host:port | |
|
||||
| `WEB_SERVER_DEFAULT_PORT` | Integer | The default port the web server should listen on unless overriden by the PORT environment variable | 5000 |
|
||||
| `WEB_SERVER_DEFAULT_BIND_ADDRESS` | String | The default bind address the web server should listen on unless overriden by the BIND_ADDRESS environment variable | 127.0.0.1 |
|
||||
| `WEB_SERVER_MAX_THREADS` | Integer | The maximum number of threads which can be used by the web server | 5 |
|
||||
| `WORKER_DEFAULT_HEALTH_SERVER_PORT` | Integer | The default port for the worker health server to listen on | 9090 |
|
||||
| `WORKER_DEFAULT_HEALTH_SERVER_BIND_ADDRESS` | String | The default bind address for the worker health server to listen on | 127.0.0.1 |
|
||||
| `MAIN_DB_HOST` | String | Hostname for the main MariaDB server | localhost |
|
||||
| `MAIN_DB_PORT` | Integer | The MariaDB port to connect to | 3306 |
|
||||
| `MAIN_DB_USERNAME` | String | The MariaDB username | postal |
|
||||
| `MAIN_DB_PASSWORD` | String | The MariaDB password | |
|
||||
| `MAIN_DB_DATABASE` | String | The MariaDB database name | postal |
|
||||
| `MAIN_DB_POOL_SIZE` | Integer | The maximum size of the MariaDB connection pool | 5 |
|
||||
| `MAIN_DB_ENCODING` | String | The encoding to use when connecting to the MariaDB database | utf8mb4 |
|
||||
| `MESSAGE_DB_HOST` | String | Hostname for the MariaDB server which stores the mail server databases | localhost |
|
||||
| `MESSAGE_DB_PORT` | Integer | The MariaDB port to connect to | 3306 |
|
||||
| `MESSAGE_DB_USERNAME` | String | The MariaDB username | postal |
|
||||
| `MESSAGE_DB_PASSWORD` | String | The MariaDB password | |
|
||||
| `MESSAGE_DB_DATABASE_NAME_PREFIX` | String | The MariaDB prefix to add to database names | postal |
|
||||
| `LOGGING_RAILS_LOG_ENABLED` | Boolean | Enable the default Rails logger | false |
|
||||
| `LOGGING_SENTRY_DSN` | String | A DSN which should be used to report exceptions to Sentry | |
|
||||
| `LOGGING_ENABLED` | Boolean | Enable the Postal logger to log to STDOUT | true |
|
||||
| `LOGGING_HIGHLIGHTING_ENABLED` | Boolean | Enable highlighting of log lines | false |
|
||||
| `GELF_HOST` | String | GELF-capable host to send logs to | |
|
||||
| `GELF_PORT` | Integer | GELF port to send logs to | 12201 |
|
||||
| `GELF_FACILITY` | String | The facility name to add to all log entries sent to GELF | postal |
|
||||
| `SMTP_SERVER_DEFAULT_PORT` | Integer | The default port the SMTP server should listen on unless overriden by the PORT environment variable | 25 |
|
||||
| `SMTP_SERVER_DEFAULT_BIND_ADDRESS` | String | The default bind address the SMTP server should listen on unless overriden by the BIND_ADDRESS environment variable | 127.0.0.1 |
|
||||
| `SMTP_SERVER_DEFAULT_HEALTH_SERVER_PORT` | Integer | The default port for the SMTP server health server to listen on | 9091 |
|
||||
| `SMTP_SERVER_DEFAULT_HEALTH_SERVER_BIND_ADDRESS` | String | The default bind address for the SMTP server health server to listen on | 127.0.0.1 |
|
||||
| `SMTP_SERVER_TLS_ENABLED` | Boolean | Enable TLS for the SMTP server (requires certificate) | false |
|
||||
| `SMTP_SERVER_TLS_CERTIFICATE_PATH` | String | The path to the SMTP server's TLS certificate | config/postal/smtp.cert |
|
||||
| `SMTP_SERVER_TLS_PRIVATE_KEY_PATH` | String | The path to the SMTP server's TLS private key | config/postal/smtp.key |
|
||||
| `SMTP_SERVER_TLS_CIPHERS` | String | Override ciphers to use for SSL | |
|
||||
| `SMTP_SERVER_SSL_VERSION` | String | The SSL versions which are supported | SSLv23 |
|
||||
| `SMTP_SERVER_PROXY_PROTOCOL` | Boolean | Enable proxy protocol for use behind some load balancers | false |
|
||||
| `SMTP_SERVER_LOG_CONNECTIONS` | Boolean | Enable connection logging | false |
|
||||
| `SMTP_SERVER_MAX_MESSAGE_SIZE` | Integer | The maximum message size to accept from the SMTP server (in MB) | 14 |
|
||||
| `SMTP_SERVER_LOG_IP_ADDRESS_EXCLUSION_MATCHER` | String | A regular expression to use to exclude connections from logging | |
|
||||
| `DNS_MX_RECORDS` | Array of strings | The names of the default MX records | ["mx1.postal.example.com", "mx2.postal.example.com"] |
|
||||
| `DNS_SPF_INCLUDE` | String | The location of the SPF record | spf.postal.example.com |
|
||||
| `DNS_RETURN_PATH_DOMAIN` | String | The return path hostname | rp.postal.example.com |
|
||||
| `DNS_ROUTE_DOMAIN` | String | The domain to use for hosting route-specific addresses | routes.postal.example.com |
|
||||
| `DNS_TRACK_DOMAIN` | String | The CNAME which tracking domains should be pointed to | track.postal.example.com |
|
||||
| `DNS_HELO_HOSTNAME` | String | The hostname to use in HELO/EHLO when connecting to external SMTP servers | |
|
||||
| `DNS_DKIM_IDENTIFIER` | String | The identifier to use for DKIM keys in DNS records | postal |
|
||||
| `DNS_DOMAIN_VERIFY_PREFIX` | String | The prefix to add before TXT record verification string | postal-verification |
|
||||
| `DNS_CUSTOM_RETURN_PATH_PREFIX` | String | The domain to use on external domains which points to the Postal return path domain | psrp |
|
||||
| `SMTP_HOST` | String | The hostname to send application-level e-mails to | 127.0.0.1 |
|
||||
| `SMTP_PORT` | Integer | The port number to send application-level e-mails to | 25 |
|
||||
| `SMTP_USERNAME` | String | The username to use when authentication to the SMTP server | |
|
||||
| `SMTP_PASSWORD` | String | The password to use when authentication to the SMTP server | |
|
||||
| `SMTP_FROM_NAME` | String | The name to use as the from name outgoing emails from Postal | Postal |
|
||||
| `SMTP_FROM_ADDRESS` | String | The e-mail to use as the from address outgoing emails from Postal | postal@example.com |
|
||||
| `RAILS_ENVIRONMENT` | String | The Rails environment to run the application in | production |
|
||||
| `RAILS_SECRET_KEY` | String | The secret key used to sign and encrypt cookies and session data in the application | |
|
||||
| `RSPAMD_ENABLED` | Boolean | Enable rspamd for message inspection | false |
|
||||
| `RSPAMD_HOST` | String | The hostname of the rspamd server | 127.0.0.1 |
|
||||
| `RSPAMD_PORT` | Integer | The port of the rspamd server | 11334 |
|
||||
| `RSPAMD_SSL` | Boolean | Enable SSL for the rspamd connection | false |
|
||||
| `RSPAMD_PASSWORD` | String | The password for the rspamd server | |
|
||||
| `RSPAMD_FLAGS` | String | Any flags for the rspamd server | |
|
||||
| `SPAMD_ENABLED` | Boolean | Enable SpamAssassin for message inspection | false |
|
||||
| `SPAMD_HOST` | String | The hostname for the SpamAssassin server | 127.0.0.1 |
|
||||
| `SPAMD_PORT` | Integer | The port of the SpamAssassin server | 783 |
|
||||
| `CLAMAV_ENABLED` | Boolean | Enable ClamAV for message inspection | false |
|
||||
| `CLAMAV_HOST` | String | The host of the ClamAV server | 127.0.0.1 |
|
||||
| `CLAMAV_PORT` | Integer | The port of the ClamAV server | 2000 |
|
||||
| `SMTP_CLIENT_OPEN_TIMEOUT` | Integer | The open timeout for outgoing SMTP connections | 30 |
|
||||
| `SMTP_CLIENT_READ_TIMEOUT` | Integer | The read timeout for outgoing SMTP connections | 30 |
|
||||
| `MIGRATION_WAITER_ENABLED` | Boolean | Wait for all migrations to run before starting a process | false |
|
||||
| `MIGRATION_WAITER_ATTEMPTS` | Integer | The number of attempts to try waiting for migrations to complete before start | 120 |
|
||||
| `MIGRATION_WAITER_SLEEP_TIME` | Integer | The number of seconds to wait between each migration check | 2 |
|
||||
203
doc/config/yaml.yml
Normal file
203
doc/config/yaml.yml
Normal file
@@ -0,0 +1,203 @@
|
||||
version: 2
|
||||
|
||||
postal:
|
||||
# The hostname that the Postal web interface runs on
|
||||
web_hostname: postal.example.com
|
||||
# The HTTP protocol to use for the Postal web interface
|
||||
web_protocol: https
|
||||
# The hostname that the Postal SMTP server runs on
|
||||
smtp_hostname: postal.example.com
|
||||
# Should IP pools be enabled for this installation?
|
||||
use_ip_pools: false
|
||||
# The maximum number of delivery attempts
|
||||
default_maximum_delivery_attempts: 18
|
||||
# The number of days to hold a message before they will be expired
|
||||
default_maximum_hold_expiry_days: 7
|
||||
# The number of days an address will remain in a suppression list before being removed
|
||||
default_suppression_list_automatic_removal_days: 30
|
||||
# The default threshold at which a message should be treated as spam
|
||||
default_spam_threshold: 5
|
||||
# The default threshold at which a message should be treated as spam failure
|
||||
default_spam_failure_threshold: 20
|
||||
# Domain verification and checking usually checks with a domain's nameserver. Enable this to check with the server's local nameservers.
|
||||
use_local_ns_for_domain_verification: false
|
||||
# Append a Resend-Sender header to all outgoing e-mails
|
||||
use_resent_sender_header: true
|
||||
# Path to the private key used for signing
|
||||
signing_key_path: config/postal/signing.key
|
||||
# An array of SMTP relays in the format of smtp://host:port
|
||||
smtp_relays: []
|
||||
|
||||
web_server:
|
||||
# The default port the web server should listen on unless overriden by the PORT environment variable
|
||||
default_port: 5000
|
||||
# The default bind address the web server should listen on unless overriden by the BIND_ADDRESS environment variable
|
||||
default_bind_address: 127.0.0.1
|
||||
# The maximum number of threads which can be used by the web server
|
||||
max_threads: 5
|
||||
|
||||
worker:
|
||||
# The default port for the worker health server to listen on
|
||||
default_health_server_port: 9090
|
||||
# The default bind address for the worker health server to listen on
|
||||
default_health_server_bind_address: 127.0.0.1
|
||||
|
||||
main_db:
|
||||
# Hostname for the main MariaDB server
|
||||
host: localhost
|
||||
# The MariaDB port to connect to
|
||||
port: 3306
|
||||
# The MariaDB username
|
||||
username: postal
|
||||
# The MariaDB password
|
||||
password:
|
||||
# The MariaDB database name
|
||||
database: postal
|
||||
# The maximum size of the MariaDB connection pool
|
||||
pool_size: 5
|
||||
# The encoding to use when connecting to the MariaDB database
|
||||
encoding: utf8mb4
|
||||
|
||||
message_db:
|
||||
# Hostname for the MariaDB server which stores the mail server databases
|
||||
host: localhost
|
||||
# The MariaDB port to connect to
|
||||
port: 3306
|
||||
# The MariaDB username
|
||||
username: postal
|
||||
# The MariaDB password
|
||||
password:
|
||||
# The MariaDB prefix to add to database names
|
||||
database_name_prefix: postal
|
||||
|
||||
logging:
|
||||
# Enable the default Rails logger
|
||||
rails_log_enabled: false
|
||||
# A DSN which should be used to report exceptions to Sentry
|
||||
sentry_dsn:
|
||||
# Enable the Postal logger to log to STDOUT
|
||||
enabled: true
|
||||
# Enable highlighting of log lines
|
||||
highlighting_enabled: false
|
||||
|
||||
gelf:
|
||||
# GELF-capable host to send logs to
|
||||
host:
|
||||
# GELF port to send logs to
|
||||
port: 12201
|
||||
# The facility name to add to all log entries sent to GELF
|
||||
facility: postal
|
||||
|
||||
smtp_server:
|
||||
# The default port the SMTP server should listen on unless overriden by the PORT environment variable
|
||||
default_port: 25
|
||||
# The default bind address the SMTP server should listen on unless overriden by the BIND_ADDRESS environment variable
|
||||
default_bind_address: 127.0.0.1
|
||||
# The default port for the SMTP server health server to listen on
|
||||
default_health_server_port: 9091
|
||||
# The default bind address for the SMTP server health server to listen on
|
||||
default_health_server_bind_address: 127.0.0.1
|
||||
# Enable TLS for the SMTP server (requires certificate)
|
||||
tls_enabled: false
|
||||
# The path to the SMTP server's TLS certificate
|
||||
tls_certificate_path: config/postal/smtp.cert
|
||||
# The path to the SMTP server's TLS private key
|
||||
tls_private_key_path: config/postal/smtp.key
|
||||
# Override ciphers to use for SSL
|
||||
tls_ciphers:
|
||||
# The SSL versions which are supported
|
||||
ssl_version: SSLv23
|
||||
# Enable proxy protocol for use behind some load balancers
|
||||
proxy_protocol: false
|
||||
# Enable connection logging
|
||||
log_connections: false
|
||||
# The maximum message size to accept from the SMTP server (in MB)
|
||||
max_message_size: 14
|
||||
# A regular expression to use to exclude connections from logging
|
||||
log_ip_address_exclusion_matcher:
|
||||
|
||||
dns:
|
||||
# The names of the default MX records
|
||||
mx_records:
|
||||
- mx1.postal.example.com
|
||||
- mx2.postal.example.com
|
||||
# The location of the SPF record
|
||||
spf_include: spf.postal.example.com
|
||||
# The return path hostname
|
||||
return_path_domain: rp.postal.example.com
|
||||
# The domain to use for hosting route-specific addresses
|
||||
route_domain: routes.postal.example.com
|
||||
# The CNAME which tracking domains should be pointed to
|
||||
track_domain: track.postal.example.com
|
||||
# The hostname to use in HELO/EHLO when connecting to external SMTP servers
|
||||
helo_hostname:
|
||||
# The identifier to use for DKIM keys in DNS records
|
||||
dkim_identifier: postal
|
||||
# The prefix to add before TXT record verification string
|
||||
domain_verify_prefix: postal-verification
|
||||
# The domain to use on external domains which points to the Postal return path domain
|
||||
custom_return_path_prefix: psrp
|
||||
|
||||
smtp:
|
||||
# The hostname to send application-level e-mails to
|
||||
host: 127.0.0.1
|
||||
# The port number to send application-level e-mails to
|
||||
port: 25
|
||||
# The username to use when authentication to the SMTP server
|
||||
username:
|
||||
# The password to use when authentication to the SMTP server
|
||||
password:
|
||||
# The name to use as the from name outgoing emails from Postal
|
||||
from_name: Postal
|
||||
# The e-mail to use as the from address outgoing emails from Postal
|
||||
from_address: postal@example.com
|
||||
|
||||
rails:
|
||||
# The Rails environment to run the application in
|
||||
environment: production
|
||||
# The secret key used to sign and encrypt cookies and session data in the application
|
||||
secret_key:
|
||||
|
||||
rspamd:
|
||||
# Enable rspamd for message inspection
|
||||
enabled: false
|
||||
# The hostname of the rspamd server
|
||||
host: 127.0.0.1
|
||||
# The port of the rspamd server
|
||||
port: 11334
|
||||
# Enable SSL for the rspamd connection
|
||||
ssl: false
|
||||
# The password for the rspamd server
|
||||
password:
|
||||
# Any flags for the rspamd server
|
||||
flags:
|
||||
|
||||
spamd:
|
||||
# Enable SpamAssassin for message inspection
|
||||
enabled: false
|
||||
# The hostname for the SpamAssassin server
|
||||
host: 127.0.0.1
|
||||
# The port of the SpamAssassin server
|
||||
port: 783
|
||||
|
||||
clamav:
|
||||
# Enable ClamAV for message inspection
|
||||
enabled: false
|
||||
# The host of the ClamAV server
|
||||
host: 127.0.0.1
|
||||
# The port of the ClamAV server
|
||||
port: 2000
|
||||
|
||||
smtp_client:
|
||||
# The open timeout for outgoing SMTP connections
|
||||
open_timeout: 30
|
||||
# The read timeout for outgoing SMTP connections
|
||||
read_timeout: 30
|
||||
|
||||
migration_waiter:
|
||||
# Wait for all migrations to run before starting a process
|
||||
enabled: false
|
||||
# The number of attempts to try waiting for migrations to complete before start
|
||||
attempts: 120
|
||||
# The number of seconds to wait between each migration check
|
||||
sleep_time: 2
|
||||
المرجع في مشكلة جديدة
حظر مستخدم