Listmonk on AWS User Guide

Overview

This image runs Listmonk, the open source self-hosted newsletter and mailing-list manager - manage subscribers and lists, design and send campaigns and transactional email through your own SMTP at high throughput, and track opens and clicks.

The Listmonk server runs behind nginx as a reverse proxy. PostgreSQL is the datastore for subscribers, lists, campaigns and analytics; both bind to the loopback interface only. The server listens on 127.0.0.1:9000 and is reached through nginx on port 80 (and 443 once you add TLS).

A super-administrator account and the PostgreSQL password are generated on the first boot of every deployed instance. The login is written to /root/listmonk-credentials.txt with mode 0600. The image ships no email-sending credentials - you configure your own SMTP after signing in.

Prerequisites

Before you deploy this image you need:

• An Amazon Web Services account where you can launch EC2 instances
• IAM permissions to launch instances, create security groups, and subscribe to AWS Marketplace products
• An EC2 key pair in the target Region for SSH access to the instance
• A VPC and subnet in the target Region, with a security group allowing inbound port 22 from your management network and inbound ports 80 and 443 from the networks your administrators use
• The AWS CLI (version 2) installed locally if you plan to deploy from the command line
• SMTP credentials for sending email (Amazon SES, or any provider)

Step 1: Launch the Instance from the AWS Marketplace

Sign in to the AWS Management Console, open the EC2 service, and select Launch instance. Under Application and OS Images choose AWS Marketplace AMIs and search for Listmonk. Select the cloudimg listing and choose Select, then Continue on the subscription summary.

Pick an instance type of m5.large or larger. Choose your EC2 key pair under Key pair (login). Under Network settings select your VPC and subnet, and either create or select a security group that allows inbound port 22 from your management network and inbound ports 80 and 443 from the networks your administrators use. Leave the root volume at the default size or larger.

Select Launch instance. First boot initialisation takes approximately one minute after the instance state becomes Running and the status checks pass.

Step 2: Launch the Instance from the AWS CLI

The following block launches an instance from the cloudimg Listmonk Marketplace AMI into an existing subnet and security group. Replace <ami-id> with the AMI ID shown on the Marketplace listing, <key-name> with your EC2 key pair name, <subnet-id> with your subnet ID, and <security-group-id> with a security group that opens ports 22, 80, and 443 as described above.

aws ec2 run-instances \
  --image-id <ami-id> \
  --instance-type m5.large \
  --key-name <key-name> \
  --subnet-id <subnet-id> \
  --security-group-ids <security-group-id> \
  --block-device-mappings '[{"DeviceName":"/dev/sda1","Ebs":{"VolumeSize":30,"VolumeType":"gp3"}}]' \
  --tag-specifications 'ResourceType=instance,Tags=[{Key=Name,Value=listmonk-01}]'

The command prints a JSON document on success. Note the instance ID, then retrieve its public address once it is running with aws ec2 describe-instances --instance-ids <instance-id> --query "Reservations[].Instances[].PublicIpAddress" --output text.

Step 3: Connect and Retrieve the Administrator Login

Connect over SSH with the key pair you selected and the public IP address from step 2. The SSH login user depends on the operating system of the AMI variant you launched:

The first boot service runs before the SSH daemon becomes ready, so the credentials file is always in place when you log in for the first time.

ssh <login-user>@<public-ip>
sudo cat /root/listmonk-credentials.txt

You will see a plain text file containing the Listmonk URL, the administrator username (admin) and the password. From the same SSH session you can confirm the deployment is healthy - the health endpoint is open:

curl -fsS http://127.0.0.1/health

{"data":true}

A {"data":true} response confirms the full stack - nginx, the Listmonk server and PostgreSQL - is serving.

Step 4: First Sign-in

Open a web browser and navigate to http://<public-ip>/admin. Listmonk presents its sign-in page. Enter the username admin and the password from /root/listmonk-credentials.txt, then select Login.

The Listmonk admin sign-in, served on first boot with a per-instance super-administrator login.

After signing in you reach the dashboard, with lists, subscribers, campaigns and analytics at a glance.

The Listmonk dashboard - lists, subscribers, campaigns and analytics.

Step 5: Configure SMTP

The image ships no email-sending credentials, so before sending you must connect an SMTP server. Open Settings, then the SMTP tab, and enter your provider's host, port, authentication and credentials. For Amazon SES, use your SES SMTP endpoint (for example email-smtp.eu-west-1.amazonaws.com, port 587) and SES SMTP credentials. Send a test, then save.

Step 6: Create Lists and Import Subscribers

Open Lists and create a list (single or double opt-in). Then open Subscribers to add subscribers individually, or import them in bulk from a CSV. You can segment subscribers with SQL-like queries and attributes.

Step 7: Build and Send a Campaign

Open Campaigns, then Create new. Give the campaign a name and subject, choose the list(s) to send to, pick a format (rich text, HTML, Markdown or plain text), and compose the content. Send a test message to yourself, then schedule or send the campaign. Track opens, clicks and bounces from the campaign's analytics.

Creating an email campaign in Listmonk - subject, lists, format and a test send.

Step 8: Enable HTTPS with Let's Encrypt

For any production deployment serve Listmonk over HTTPS so the admin session and subscriber data cannot be intercepted. The image ships with nginx, which certbot can configure automatically.

The following assumes you have a DNS record pointing your fully qualified domain name at the instance's public IP address.

sudo apt-get update && sudo apt-get install -y certbot python3-certbot-nginx
sudo certbot --nginx -d listmonk.your-domain.example \
  --non-interactive --agree-tos -m you@your-domain.example \
  --redirect

After certbot finishes, set the root URL under Settings, then General to your HTTPS address so links and unsubscribe URLs in emails are correct.

Step 9: Backups and Maintenance

Listmonk keeps all of its state - subscribers, lists, campaigns, templates and analytics - in PostgreSQL, plus any uploaded media under /opt/listmonk. Back both up:

sudo -u postgres pg_dump listmonk > <backup-dir>/listmonk-db-$(date +%F).sql
sudo tar -czf <backup-dir>/listmonk-uploads-$(date +%F).tgz -C /opt/listmonk uploads

Ship both artifacts to an Amazon S3 bucket or another object store. Because the database is on its own EBS volume, you can also take coordinated EBS snapshots. For kernel and package updates, Ubuntu's unattended-upgrades is enabled by default. To upgrade Listmonk, replace /opt/listmonk/listmonk with a newer release and run sudo systemctl stop listmonk && sudo -u listmonk /opt/listmonk/listmonk --config /opt/listmonk/config.toml --upgrade --yes && sudo systemctl start listmonk. Always back up first. See https://listmonk.app/docs/.

Step 10: Scaling and Deliverability

• Move PostgreSQL to Amazon RDS for PostgreSQL and update the [db] section of /opt/listmonk/config.toml
• Use Amazon SES for high-volume, reputable sending, and configure SPF, DKIM and DMARC on your sending domain for deliverability
• Put the web tier behind an Application Load Balancer and serve uploaded media through Amazon CloudFront

Each of these is documented in the official Listmonk documentation at https://listmonk.app/docs/.

Support

cloudimg provides 24/7/365 expert technical support for this image. Guaranteed response within 24 hours, one hour average for critical issues. Contact support@cloudimg.co.uk.

For general Listmonk questions consult the documentation at https://listmonk.app/docs/. Listmonk is a trademark of its respective owner; use here is nominative and does not imply affiliation or endorsement.