Update installation and other-notes pages against the Postal 3.3.7 source - #93
Open
benrfairless wants to merge 7 commits into
Open
benrfairless wants to merge 7 commits into
benrfairless wants to merge 7 commits into
Conversation
New feature pages written from the 3.3.7 source: - Routing incoming e-mail: MX vs forwarding address, route name rules, the five route modes and their SMTP-time behaviour, additional endpoints, processing order, HTTP/SMTP/address endpoint options (including the STARTTLS/STARTLS mismatch), retries and bounces - Mail server settings: Live/Development, retention behaviour and defaults, send limits (rolling hour, 90% warning, hourly notices), every reason a message can be held and whether release bypasses it, suppression list rules, advanced/admin-only settings, suspension, deletion - Sending domains: org vs server domains, DNS and e-mail verification, the four DNS checks with exact expected records and statuses, DKIM signing and fallback, custom return path for DMARC alignment, use_for_any
Documents the install-repo helper script: run/setup/tool commands, flags, override files and hooks.
Generated from doc/config/yaml.yml at the 3.3.7 tag (111 options across 17 sections) with environment variable names derived using the GROUP_KEY convention, plus cross-references to the relevant feature pages.
- Webhooks: document the {event,timestamp,uuid,payload} envelope, request
signing headers and JWKS verification, retry schedule, 10-day history,
SendLimit* events
- HTTP payloads: correct status-code handling (5xx retries, 429/4xx hard
fail), per-endpoint timeout, missing payload keys, SSRF blocked ranges
and allowed_request_destinations
- API: expand into a full reference for all four legacy endpoints,
including parameter-error status, error codes and response shapes
- OIDC: correct user matching order (UID first, then e-mail), note that
linking removes the local password, document manual endpoints
- Spam & virus: add rspamd and ClamAV sections, correct threshold
semantics, document X-Postal-* headers and outbound inspection
- SMTP auth/TLS: username handling per mechanism, SMTP-IP matching,
response table, STARTTLS-only, certificate chains
- Click tracking, health metrics, IP pools, logging: fill in behaviour
from source (DNS OK requirement, metric list, priority weighting,
rule matching, log options)
- Configuration: document POSTAL_CONFIG_FILE_PATH, $config-file-root, env var naming rules and precedence, process-specific variables, SMTP relay URL format and ssl_mode values, trusted proxies; complete the v1 -> v2 legacy key mapping - Upgrading: describe what postal upgrade actually does, version pinning - Prerequisites: correct message database naming (postal-server-<id>) - Feature list: 10-day webhook history, threat checking, rspamd, OIDC, Prometheus, signed webhooks - Bounces: return path address format, X-Postal-MsgID detection, unmatched bounce handling, bounces Postal generates - Containers: in-image CLI commands, env-only configuration, amd64 only, proxy protocol, HTTP wait targets, migration waiter - Wildcards: exact-match precedence, additional endpoint restriction - Debugging: logs, health checks, activity tab, test-app-smtp
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Reviews the Welcome, Getting Started and Other Notes sections against the Postal source at tag
3.3.7(and thepostalserver/installhelper repo) and brings them in line with current behaviour.Changes
POSTAL_CONFIG_FILE_PATHand the$config-file-rootplaceholder, theGROUP_KEYenvironment-variable naming rule and that env vars take precedence over the file, the process-specific variables (PORT,BIND_ADDRESS,HEALTH_SERVER_*,SILENCE_POSTAL_CONFIG_MESSAGES), thesmtp_relaysURL format andssl_modevalues,trusted_proxies. Completes the v1 → v2 legacy key mapping (four mappings were missing:general.exception_url,message_db.prefix,logging.rails_log,smtp_server.log_connect).postal upgradeactually does (it runsgit pullitself), version pinning,postal version, rollback caveats.{prefix}-server-{id}, notpostal-*; adds an exampleGRANT.psrp.return path, how bounces are matched viaX-Postal-MsgID, what happens to unmatched bounces, and that incoming bounces do not populate the suppression list.postalCLI commands, env-var-only configuration, amd64-only image, proxy protocol, HTTPWAIT_FOR_TARGETS,migration_waiter.*; additional endpoints on wildcard routes must be HTTP; tag is preserved inrcpt_to.postal test-app-smtp, host authorization errors.Claims I could not verify from the codebase were left as-is (MariaDB "10.6 or higher", "MySQL not supported" – note upstream
CONTRIBUTING.mdactually says MySQL – and the client library list).Stacked on #90, #91 and #92 (cross-links).
pnpm generatepasses on this branch (177 routes prerendered, no 404s from the link crawler).