remp/mailer-skeleton

REMP Mailer Skeleton

3.4.0 2024-01-23 14:01 UTC

Requires

• remp/mailer-module: ^3.5

MIT

README

This is a pre-configured skeleton of REMP Mailer application with simple installation.

Mailer serves as a tool for configuration of mailers, creation of email layouts and templates, and configuring and sending mail jobs to selected segments of users.

Installation

Docker

The simplest possible way is to run this application in docker containers. Docker Compose is used for orchestrating. Except of these two application, there is no need to install anything on host machine.

Recommended (tested) versions are:

• Docker - 24.0.4
• Docker Compose - 2.19.1

Steps to install application within docker

1. Get the application

   A) Using Composer:

   composer create-project --no-install remp/mailer-skeleton path/to/install

   cd path/to/install

   B) Using GitHub:

   git clone https://github.com/remp2020/mailer-skeleton.git

   cd mailer-skeleton

2. Prepare environment & configuration files

   cp .env.example .env

   cp app/config/config.local.neon.example app/config/config.local.neon

   cp docker-compose.override.example.yml docker-compose.override.yml

   No changes are required if you want to run application as it is.

   Note: nginx web application runs on the port 80. Make sure this port is not used, otherwise you will encounter error like this when initializing Docker:

   ERROR: for nginx  Cannot start service nginx: Ports are not available: listen tcp 0.0.0.0:80: bind: address already in use
   

   In such case, change port mapping in docker-composer.override.yml. For example, the following setting maps internal port 80 to external port 8080, so the application will be available at http://mailer.press:8080.

   services:
   # ...
     nginx:
       ports:
         - "8080:80"

3. Setup host

   Default host used by application is http://mailer.press. This domain should by pointing to localhost (127.0.0.1), so add it to local /etc/hosts file. In addition, we recommend adding mailhog.mailer.press domain for testing. Use the following commands:

   echo '127.0.0.1 mailer.press' | sudo tee -a /etc/hosts

   echo '127.0.0.1 mailhog.mailer.press' | sudo tee -a /etc/hosts

4. Start Docker containers

   docker compose up

   You should see logs of starting containers. This may include errors, because application was not yet initialized. Enter the application docker container:

   # run from anywhere in the project
   docker compose exec mailer bash

   When inside the container, add required permissions:

   chmod -R a+rw temp log

   After that, choose and run one of the two installation options:

   • Fully ready application with demo data:

     make install-demo

   • No demo data:

     make install

5. Log-in to Mailer

   Access application via web browser. Default configuration:

   • URL: http://mailer.press/
   • User:
     • Email: [e-mail]
     • Password: passphrase_change_me

   IMPORTANT: Please run make install every time you update Mailer-skeleton using composer update.

Manual installation

Dependencies

• PHP 8.1
• MySQL 8
• Redis 6.2

Installation

Clone this repository, go inside the folder and run the following to create configuration files from the sample ones:

cp .env.example .env

cp app/config/config.local.neon.example app/config/config.local.neon

Edit .env file and set up all required values such as database and Redis connections.

Now run the installation:

make install

As an alternative, run the following to include seeding of demo values in the installation:

make install-demo

Mailer demo overview

Default integrations

After the installation of Mailer skeleton, Mailer uses default (local) integrations that need to be replaced with real implementations before going live. The local integrations serve as references and defaults to allow sending testing emails without doing any extra work.

Authentication

SimpleAuthenticator is responsible for authentication to the tool.

List of credentials is configured in config.local.neon file. Default credentials are:

• Email: [e-mail]
• Password: passphrase_change_me

Do not run Mailer publicly with SimpleAuthenticator using the default credentials.

Mailers integration

Outgoing emails are sent by SmtpMailer. To configure a different mailer (e.g. MailGun), consult the Mailers section in the documentation. Configuration of the SMTP mailer is loaded from config.local.neon, see the section local_configs (which overrides any configuration options stored in the database):

local_configs:
    default_mailer: remp_smtp
    remp_smtp_host: mailhog
    remp_smtp_port: 1025

Key remp_smtp_host points to mailhog. This is an internal docker address of the mailhog docker container. The container runs MailHog, which is a web based SMTP testing tool. Therefore, all emails sent from the Demo Mailer instance are captured by MailHog, and are easily viewable in the MailHog web interface at http://mailhog.mailer.press.

User-base integration

Mailer depends on external authority to get information about users. As a default source of users, Dummy implementation of user provider is used. Provider lists 2 demo users ([e-mail], [e-mail]). See the documentation on how to implement different user provider.

Segment integration

To send a newsletter, Mailer needs to get a segment of users who should receive it. To complement default user-base integration, there's also Dummy implementation of segment provider, always returning the same segment with both demo users.

Debug mode

After the installation, Mailer is running in debug mode and all debug information is shown. Avoid running this mode in production. To disable this mode, change the value of ENV key in .env configuration file:

# previously was `local` (debug ON)
ENV=production

Basic scenario - send email to user segment

To test the Mailer functionality, we recommend going through the following basic scenario:

1. Log-in to Mailer at URL http://mailer.press
2. Go to Jobs
3. Click Add new job
4. Select values in Include segments, Newsletter list, and Email A alternative inputs. Keep other inputs empty.
   • Demo values of Emails, Layouts and Newsletter lists are seeded by default in demo installation.
5. Click Save and start button
6. Wait approximately a minute, so Mailer processes the job. Check the job status at Jobs page.
7. After the job is processed (status "DONE"), go to MailHog at http://mailhog.mailer.press/ and check that emails were successfully received.

Customization

Mailer-skeleton is ready for customization. Please see the mailer-module documentation for more information.

As a sample, mailer-skeleton provides app/Commands/SampleCommand.php, extending the Command class. It is registered as a new command in the config.local.neon file. Run it by connecting to the container:

docker compose exec mailer bash

and executing the command:

php bin/command.php mail:sample-command

Troubleshooting

Some known errors that have occurred and how to fix them.

Docker SMTP error "Cannot assign requested address"

In some cases (such as running containers for the first time), a docker container might end up reporting this error message. Simply restarting the problematic container should help.