> Source: https://meetrix.io/blogs/listmonk-developer-guide/ > Markdown copy of that page. Cite the URL above, not this file. PaaS Products # Listmonk - Developer Guide [By Dinesh Chathuranga](https://meetrix.io/blogs/authors/dinesh-chathuranga/) • October 24, 2023 • 15 min read Welcome to our comprehensive developer guide for deploying Listmonk on AWS! Listmonk is a powerful, open-source email marketing platform, and with our pre-configured AMI, you can get it running in your own AWS environment in minutes. Deploying on Google Cloud instead? See our [Listmonk on GCP Marketplace](https://meetrix.io/blogs/listmonk-newsletter-manager-gcp/) overview. This guide will walk you through every step, from launching the AMI to configuring your domain and securing your instance. Let's get started! ### Related Article [ How to Install Listmonk on AWS by Single Click | Commercial Support for Listmonk Effortlessly deploy Listmonk, a top email marketing platform, on your self-hosted server at low cost with our pre-configured AMI, ideal for businesses in the UK, USA, Europe, Ireland, Singapore, and Thailand seeking efficient marketing solutions. Meetrix.IO • Kelum Sampath ![How to Install Listmonk on AWS by Single Click | Commercial Support for Listmonk](https://meetrix.io/blog-images/paas-dev-guides/listmonk/listmonk-image.png)](https://meetrix.io/blogs/how-to-install-listmonk/) ## Video Guide Prerequisites Before you begin, make sure you have the following: - Basic knowledge of AWS services, including EC2 and CloudFormation. - An active AWS account with the necessary permissions. - Sufficient vCPU quota to launch new instances. If you need to increase it, follow [this guide](https://meetrix.io/blogs/increase-aws-vcpu-quota/). ## Launching the Listmonk AMI from AWS Marketplace ### Step 1: Subscribe to the AMI 1. Navigate to the [Listmonk](https://aws.amazon.com/marketplace/pp/prodview-aut76oivkrr4g) listing in the AWS Marketplace. 2. Click the **Continue to Subscribe** button. 3. Accept the terms and conditions by clicking **Accept Terms**. 4. After a brief processing period, click **Continue to Configuration**. ### Step 2: Configure and Launch 1. On the "Configure this software" page, select your desired AWS region. 2. Click **Continue to Launch**. 3. From the "Choose Action" dropdown, select **Launch CloudFormation**. 4. Click **Launch**. This will redirect you to the CloudFormation console to create a new stack. ## Deploying with CloudFormation ### Step 1: Create Stack 1. You'll be taken to the "Create stack" page. Ensure the "Template is ready" option is selected. 2. Click **Next**. ### Step 2: Specify Stack Details Provide the necessary parameters for your Listmonk deployment. These settings define how your instance will be configured. | Parameter | Description | | --- | --- | | Stack name | A unique name for your CloudFormation stack (e.g., `my-listmonk-deployment`). | | Admin Email | The email address for generating SSL certificates with Let's Encrypt. | | DeploymentName | A name for your deployment (e.g., `listmonk`). | | DomainName | Your public domain name (e.g., `listmonk.yourdomain.com`). SSL will be set up automatically if the domain is hosted on Route 53. Please make sure your domain name is hosted on Route 53. If it's unsuccessful, you have to set up SSL manually. | | EmailFrom | The "From" email address for outgoing emails (e.g., `noreply@yourdomain.com`). | | InstanceType | The EC2 instance type. We recommend `t3.medium` or larger for optimal performance. | | KeyName | The name of your EC2 key pair for SSH access. | | S3Bucket | An S3 bucket name for storing PostgreSQL database backups. | | SMTPHost, SMTPPassword, SMTPPort, SMTPUser | Your SMTP server details for sending emails. | | SSHLocation | The IP address range for SSH access. Defaults to `0.0.0.0/0` (open to all). For better security, restrict this to your IP. | | SubnetCidrBlock | The CIDR block for the subnet. Defaults to `10.0.0.0/24`. | | VpcCidrBlock | The CIDR block for the VPC. Defaults to `10.0.0.0/16`. | After filling in the details, click **Next**. ### Step 3: Configure Stack Options 1. Under "Stack failure options," choose **Roll back all stack resources**. This ensures that failed deployments are automatically cleaned up. 2. Click **Next**. ### Step 4: Review and Submit 1. Review all the details you've entered. ![Reviewing CloudFormation stack parameters for Listmonk](https://meetrix.io/blog-images/paas-dev-guides/listmonk/listmonk-01.png)3. Acknowledge that CloudFormation might create IAM resources by ticking the checkbox. ![Acknowledging IAM resource creation in CloudFormation](https://meetrix.io/blog-images/paas-dev-guides/listmonk/listmonk-02.png)5. Click **Submit** to start the deployment. You will be redirected to the CloudFormation stacks page, where you can monitor the deployment progress. The stack creation process typically takes 5-10 minutes. Wait for the status to change to **CREATE\_COMPLETE**. ![Listmonk CloudFormation stack successfully created](https://meetrix.io/blog-images/paas-dev-guides/listmonk/listmonk-03.png) ## Configuring Your DNS ### Step 1: Get the Public IP Address Once the stack is created, go to the **Outputs** tab and copy the value of **PublicIp**. ![Copying the Public IP from CloudFormation outputs](https://meetrix.io/blog-images/paas-dev-guides/listmonk/listmonk-04.png) ### Step 2: Create a DNS Record 1. Go to your DNS provider (e.g., AWS Route 53, GoDaddy, Cloudflare). 2. Create an **A record** for your domain (e.g., `listmonk.yourdomain.com`). ![Creating an A record in AWS Route 53](https://meetrix.io/blog-images/paas-dev-guides/listmonk/listmonk-05.png)4. Point the record to the **PublicIp** you copied in the previous step. 5. Save the record. ## Accessing Your Listmonk Instance You can now access your Listmonk application using the **DashboardUrlIp** from the CloudFormation "Outputs" tab. ![Accessing the Listmonk dashboard URL](https://meetrix.io/blog-images/paas-dev-guides/listmonk/listmonk-06.png) 502 Bad Gateway Error? If you see a "502 Bad Gateway" error, don't worry! The application is likely still starting up. Please wait about 5 minutes and then refresh the page. ![502 Bad Gateway Error](https://meetrix.io/blog-images/paas-dev-guides/listmonk/listmonk-07.png) 1. Click "Login" button and enter details. ![Listmonk Login](https://meetrix.io/blog-images/paas-dev-guides/listmonk/listmonk-08.png)3. Then click continue button. You will navigate to the Listmonk dashboard. ![Listmonk Dashboard](https://meetrix.io/blog-images/paas-dev-guides/listmonk/listmonk-09.png)5. Before you start, please go to the "General" tab in the settings and modify the "Root URL" to correspond with your domain. Additionally, adjust the "Default \`from\` email" according to your preference, then click on "Save". ![Listmonk Settings](https://meetrix.io/blog-images/paas-dev-guides/listmonk/listmonk-10.png) ## Setup Gmail SMTP server ### Step 1: Obtain password 1. Navigate to your google account [https://myaccount.google.com/](https://myaccount.google.com/). 2. In the Security section, enable 2-step verification. ![2-step verification](https://meetrix.io/blog-images/paas-dev-guides/listmonk/listmonk-11.png)4. Use the search bar to find the "App passwords" option and navigate to the "App passwords" section. ![App passwords](https://meetrix.io/blog-images/paas-dev-guides/listmonk/listmonk-12.png)6. Provide an app name and click on "create" to generate. ![App password creation](https://meetrix.io/blog-images/paas-dev-guides/listmonk/listmonk-13.png)8. Once generated, copy the password and ensure to keep it safe as it will not be visible again. ### Step 2: Test SMTP 1. Navigate to the SMTP tab in the Listmonk "Settings". 2. Provide the following details: - Host: `smtp.gmail.com` - Port: `465` - Auth protocol: `LOGIN` - Username: Your Gmail address - Password: Previously generated password - To e-mail: An email address to which you want to send the test email ![SMTP Test](https://meetrix.io/blog-images/paas-dev-guides/listmonk/listmonk-14.png) 3. Click on "Send Email". If everything is in order, you will receive a test email. ![SMTP Test](https://meetrix.io/blog-images/paas-dev-guides/listmonk/listmonk-15.png)5. Save the settings, and you're all set to proceed. ## Manual SSL Certificate Generation If your domain is not hosted on Route 53, the automatic SSL setup might fail. In that case, you'll need to generate the certificate manually. ### Step 1: SSH into the Server 1. From the CloudFormation "Outputs" tab, copy the **PublicIp**. ![Copying Public IP for SSH access](https://meetrix.io/blog-images/paas-dev-guides/listmonk/listmonk-16.png)3. Open your terminal and use the following command to connect to the server. Replace `your-key.pem` with your key pair file. ```bash ssh -i "your-key.pem" ubuntu@ ``` ![SSH Connection Command](https://meetrix.io/blog-images/paas-dev-guides/listmonk/listmonk-17.png) ### Step 2: Run the Certificate Script Once logged in, run the following script. It will prompt you to enter your domain name and email address. ```bash sudo /root/certificate_generate_standalone.sh ``` ## Managing Your Listmonk Instance ### Shutting Down and Restarting 1. In the CloudFormation stack's **Resources** tab, click the link for the **Instance** to go to the EC2 console. ![Navigating to the EC2 instance from CloudFormation](https://meetrix.io/blog-images/paas-dev-guides/listmonk/listmonk-18.png)3. Select the instance and use the **Instance state** dropdown to **Stop instance** or **Start instance**. ![Stopping the Listmonk EC2 instance](https://meetrix.io/blog-images/paas-dev-guides/listmonk/listmonk-19.png) ### Removing the Deployment To completely remove the Listmonk application and all associated resources, simply delete the CloudFormation stack from the AWS console. ## API Documentation Listmonk provides a powerful REST API that allows you to control the entire platform programmatically. You can find the complete documentation here: [Official Listmonk API Documentation](https://listmonk.app/docs/apis/sdks/) ## Upgrading Your Instance We regularly update our AMI with the latest version of Listmonk. To upgrade, you can launch a new instance with the newer version and migrate your data. Remember to back up your server data before removing the old instance. ## Troubleshooting Common Issues 1. **vCPU Quota Error:** If you see an error about vCPU limits, please follow [this guide](https://meetrix.io/blogs/increase-aws-vcpu-quota/) to request an increase. ![AWS vCPU quota limit error](https://meetrix.io/blog-images/paas-dev-guides/listmonk/listmonk-20.png)3. **Insufficient Capacity:** If you get an "insufficient instance capacity" error, try launching the stack in a different AWS region or at a later time. ![AWS insufficient instance capacity error](https://meetrix.io/blog-images/paas-dev-guides/listmonk/listmonk-21.png)5. **Dashboard Error on First Load:** If the dashboard doesn't load immediately, wait 5-10 minutes for the services to initialize and then try again. ![Listmonk dashboard error on initial load](https://meetrix.io/blog-images/paas-dev-guides/listmonk/listmonk-22.png) ## Conclusion To sum up, Listmonk proves to be a versatile solution for managing mailing lists and newsletters, featuring a self-hosted model with minimal dependencies - it operates as a standalone binary with only a Postgres database required. This setup ensures users have full control over their email marketing processes, enabling seamless integration and scalability without reliance on external services. Whether for small businesses or large enterprises, Listmonk offers robust features and straightforward deployment, making it an excellent choice for enhancing and managing email campaigns effectively. Opt for Listmonk to streamline your email marketing efforts with ease and control. ## Technical Support If you run into any issues, our support team is here to help. Reach out to us at [aws@meetrix.io](mailto:aws@meetrix.io). ## Frequently Asked Questions What is Listmonk? Listmonk is an open-source, self-hosted email marketing platform that allows you to manage mailing lists, send campaigns, and track results with full control over your data. What are the prerequisites for installing Listmonk on AWS with this guide? You need basic knowledge of AWS services (EC2, CloudFormation), an active AWS account with appropriate permissions, and a sufficient vCPU limit. How do I get technical support? You can reach out to Meetrix Support at support@meetrix.io for assistance with Listmonk issues. How do I handle upgrades? When a new version is available in the AWS Marketplace, you can remove the previous version and launch the product again using the newer version. Remember to backup the necessary server data before removing. ## Ready to Launch Your Own Email Marketing Platform? Get started in minutes with our pre-configured AMI and take control of your email campaigns. [Deploy Listmonk from AWS Marketplace](https://aws.amazon.com/marketplace/pp/prodview-aut76oivkrr4g) Meetrix Store Listmonk Newsletters with no per-subscriber fees [Deploy it](https://meetrix.io/store/listmonk/) Meetrix Store New Deploy what this guide covers, pre-configured. - [Listmonk Newsletters with no per-subscriber fees](https://meetrix.io/store/listmonk/) - [Mailcow Business email on your own domain](https://meetrix.io/store/mailcow/) - [Ghost Blogs and paid memberships, no revenue cut](https://meetrix.io/store/ghost/) - [Jitsi Meet Self-hosted video calls for 50 to 500 users](https://meetrix.io/store/jitsi-meet/) - [RustDesk Remote desktop AMI, a TeamViewer alternative](https://meetrix.io/store/rustdesk/) - [Coturn TURN/STUN for WebRTC, no per-minute relay fees](https://meetrix.io/store/coturn/) [Browse all products](https://meetrix.io/store/)