Class: Protege::Generators::PostfixGenerator

Inherits:
Rails::Generators::Base
  • Object
show all
Defined in:
lib/generators/protege/postfix/postfix_generator.rb

Overview

Vendors the self-hosted Postfix + OpenDKIM mail-server deploy files into the host application.

Self-hosting mail needs a Docker image that runs Postfix (MTA) and OpenDKIM (DKIM) for the agent domain. Those build files ship inside the gem; this generator copies them into the host's deploy/mail/ so the developer can build, publish, and run the image (e.g. as a Kamal accessory). It also drops adaptable host-wiring references (a Kamal accessory snippet, an example CI workflow, and a deploy guide), then prints the next steps.

Files are copied verbatim (never ERB-templated): +main.cf+/+KeyTable+/+SigningTable+ carry a __MAIL_DOMAIN__ placeholder and the scripts use shell ${VAR} interpolation — all substituted at container runtime by entrypoint.sh, not at generate time.

Examples:

bin/rails g protege:postfix

Instance Method Summary collapse

Instance Method Details

#copy_ci_workflow ⇒ void

This method returns an undefined value.

Copy the example CI workflow that builds and publishes the image.



36
37
38
39
 
# File 'lib/generators/protege/postfix/postfix_generator.rb', line 36

def copy_ci_workflow
  copy_file 'github/workflows/build-mail-image.example.yml',
            '.github/workflows/build-mail-image.example.yml'
end

#copy_mail_server_files ⇒ void

This method returns an undefined value.

Copy the container build files + in-repo references (README, MAIL.md, Kamal snippet) verbatim.



29
30
31
 
# File 'lib/generators/protege/postfix/postfix_generator.rb', line 29

def copy_mail_server_files
  directory 'deploy/mail', 'deploy/mail'
end

#print_next_steps ⇒ void

This method returns an undefined value.

Print the host-side wiring the generator can't do for you (deployment-specific).



44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
 
# File 'lib/generators/protege/postfix/postfix_generator.rb', line 44

def print_next_steps
  say "\n  Self-hosted mail files written to deploy/mail/.", :green
  say <<~STEPS

    Next steps (see deploy/mail/MAIL.md for the full guide):

      1. Build + publish the image:
           docker build --platform linux/amd64 -t YOUR_REGISTRY/protege-mail:latest deploy/mail
           docker push YOUR_REGISTRY/protege-mail:latest
         (or rename .github/workflows/build-mail-image.example.yml to build it in CI)

      2. Run it as your MTA — merge deploy/mail/kamal-accessory.example.yml into config/deploy.yml.
         The only secret is RAILS_INBOUND_EMAIL_PASSWORD; there is NO DKIM key secret — the app
         pushes each domain's key to the MTA when you add it (and via the console "Sync now" button).
         Keep the protege_mail_provision volume so the pushed keys survive restarts.

      3. Point the app at it (config/environments/production.rb + deploy.yml app env):
           config.action_mailbox.ingress = :relay
           config.action_mailer.smtp_settings = { address: ENV.fetch("MAIL_RELAY_HOST", "protege-mail"),
                                                   port: 25, authentication: nil, enable_starttls_auto: false }
         Set MAIL_RELAY_HOST: protege-mail in the app service's env — the app pushes provisioning
         there, and its presence puts the console in self-hosted mode.

      4. Set up PTR/reverse DNS, open inbound TCP 25, request an outbound-25 unblock if needed,
         then add each agent domain in the dashboard (Domains → New) and publish the SPF/DKIM/DMARC
         + MX records it shows.
  STEPS
end