Setting up a Mailcoach app on AWS with Laravel Forge

2020-02-23 (Sunday) | 700 words (~3 minutes reading)

Notes to myself.

I’ve been looking forward to the release of Mailcoach, which is a self-hosted mailing list manager app. I have a few mailing lists, most of which are tiny, but one of which has over 3000 subscribers. This puts it over the threshold of expensive subscription options in MailChimp. MailChimp wants over 70 USD / month to run this single list, whereas a Mailcoach license is a one-off payment of 99 USD. Plus it seems like it would be interesting to self-host the mailing list manager and learn a few things along the way.

I want to manage my Mailcoach app on AWS via Laravel Forge, which is the set-up I use for all my Laravel apps. It was a little bit tricker than I expected to get Mailcoach set up with Forge, though, due to Mailcoach requiring a manual step during composer install. Here are the steps that worked for me.

Deploying Mailcoach with Forge

Create an empty Github repo, e.g. foobar-mailcoach.

Create a new Mailcoach application using the composer installer:

composer create-project spatie/Mailcoach

This will require entering your Mailcoach email address and license key. Hit y when asked if you want to save these in an auth.json file, as that’s essential for the rest of the setup.

Once Composer has created the auth.json file for you, find it by first finding your Composer home:

composer config --list --global | grep home

It’s likely to be something like /home/vagrant/.composer/, if you’re in a vagrant box. Check the auth file contents are there with the Mailcoach details:

cat /home/vagrant/.composer/auth.json

It should look like this:

{
    "bitbucket-oauth": {},
    "github-oauth": {},
    "gitlab-oauth": {},
    "gitlab-token": {},
    "http-basic": {
        "satis.mailcoach.app": {
            "username": "<your@email.com>",
            "password": "<your-mailcoach-license-key>"
        }}
}

Copy that and put it in the equivalent place on your Forge server for the forge user there. Be careful not to overwrite any existing Composer auth details you might have there if this is not a new Forge server.

You can edit the Composer auth file on the Forge server with:

vim /home/forge/.config/composer/auth.json

Now Forge will be able to install your Mailcoach application on the server without needing the manual step, as it already has the auth details available for the forge user.

Note that you’ll want to update the default Forge deployment script to include this:

yarn install
yarn run prod

Also, if you’re hosting the application on an HTTPS URL (which you should be), you need to change the master.blade.php layout file to use secure asset URLs. Just change all calls to asset() to secure_asset().

Then you can hit your new Mailcoach application at the domain you pointed to it.

Setting up Mailcoach scheduler in Forge

Mailcoach makes use of Laravel’s scheduler, so you’ll need to set that up in Forge. Go to the site settings in Forge, then the Scheduler section. You’ll need to set up a scheduler run that looks like this:

php /home/mailcoach/default/artisan schedule:run

Set to run every minute.

Make sure it runs as the appropriate user if you’ve got site isolation enabled for this site.

Setting up Horizon for Mailcoach in Forge

Mailcoach makes use of Laravel Horizon, so you’ll need to set that up in Forge as well. You can follow the instructions for that here:

https://medium.com/@taylorotwell/deploying-horizon-to-laravel-forge-fc9e01b74d84

In short, go to the server settings in Forge, then Daemons. Add a Daemon with this command:

php artisan horizon

And make sure it runs as the appropriate user and in the right directory for the Mailcoach site you have.

Then go to the Site settings, and add this command at the end of the deployment script:

php artisan horizon:terminate

(That restarts the Horizon workers on each deployment.)

After that, follow the Mailcoach docs to finish the rest of the set up.


Tech mentioned