Could you provide a step-by-step install guide?

[sals9]

For some reason, I got stuck on how to properly configure config.toml file. It will be so helpful if you can provide a step-by-step guide on how to install Listmonk. Also, there is no demo for a quick look!

Please help!

[knadh]

Hi @SalahSaqr the config.toml is simple enough with ample comments documenting each line. That itself should ideally serve as a tutorial. Could you be more specific as to which section you need help with?

[sals9]

I just wanted to create a quick demo on a Vultr instance so I can navigate the app and see all of the available options and features but I failed in installation.

Here are the exact steps I did:

1. apt install postgresql postgresql-contrib
2. wget https://github.com/knadh/listmonk/releases/download/v0.6.2-alpha/listmonk_0.6.2-alpha_linux_amd64.tar.gz
3. mkdir listmonk
4. tar -C /root/listmonk -xzf listmonk_0.6.2-alpha_linux_amd64.tar.gz
5. cd listmonk
6. ./listmonk --new-config
7. ./listmonk --install

... And I got this error:

main.go:90: reading config: config.toml
init.go:94: error connecting to DB: dial tcp: lookup demo-db on 127.0.0.53:53: server misbehaving

I'm totally noob, I know that, but I just was looking for a noob-friendly guide because when I saw that modern dashboard image of Listmonk, I fall in LOVE! Seriously!

[knadh]

You have to edit config.toml after it's generated. SMTP and DB settings etc.

The error shows that you haven't configured the [db] section. db.host in your case is most likely localhost with the Postgres DB (which you have to create), and its username and password.

But if you just want to check all of this out, you can just run the Docker version that comes up with a demo DB. The instructions are in the README.

[sals9]

As you suggest, I tried with the Docker method...

root@vultr:~# docker-compose up -d app db
ERROR:
Can't find a suitable configuration file in this directory or any
parent. Are you in the right directory?

    Supported filenames: docker-compose.yml, docker-compose.yaml

Could you please help?

[mr-karan]

Looks like you haven't downloaded the docker-compose.yml as mentioned here:

https://github.com/knadh/listmonk/blob/master/README.md#running-on-docker

Without a docker-compose file, you cannot run those commands.

[sals9]

Should I install it manually? How? And where should it be located?
Can you help me with more details?

[mr-karan]

You can get the docker-compose.yml from here. You can place it in any directory, all the docker-compose commands must be executed from where this file is present.

I believe the instructions are more than enough on the README. You may check Google for more 101 guides on running app with docker/compose etc.

[jackdanielux]

I like what I'm hearing about listmonk, have no clue how to set this up. Nada. I just know how to set up postgres Linux server on digital Ocean. Can some one guide me how to set this up? I know it may be a complete wastage of someone's time, but still wanted to check. In no mood to let MailChimp loot me.

P.S. The best thing would be to do what easy engine did to WP. 1 click install Wp On nginx.

[knadh]

Hey @jackdanielux. Good to know that you're hearing good things about listmonk! Curious to know where :)

Installation is simple. You setup Postgres, download the listmonk binary, and run it. Please refer to the "Binary" section here: https://listmonk.app/docs/installation/

[jackdanielux]

Thanks. I was looking for self hosted solutions which are scalable and easy to install. People pointed me to Sendy and while checking reviews of Sendy some fb grp members pointed me to Listmonk.

1 question - will this run on a server (Digital Ocean) ? Could not see where the pre requisites have been mentioned. Sorry for my basic questions ☺️

[knadh]

1 question - will this run on a server (Digital Ocean) ? Could not see where the pre requisites have been mentioned. Sorry for my basic questions relaxed

listmonk's pre-compiled binaries are available for Linux, Mac, Windows. If you've a Postgres to connect to, it'll run on all these systems with no additional setup or dependencies. Just run the binary ./listmonk

[jackdanielux]

Thanks I have got as far as ./listmonk -- install > y > continue (y/n)? y - then error as below:

2020/09/27 14:48:18 install.go:51: error loading SQL queries: Error preparing q
ery 'next-campaign-subscribers': pq: SELECT DISTINCT ON expressions must match
nitial ORDER BY expressions

could not find anything on this on documentation? Can someone pls help?

[knadh]

This shouldn't happen. Can you confirm the version of listmonk you're using and the Postgres version?

[jackdanielux]

I downloaded the listmonk binary and postgres 13 for windows yesterday. Assuming those are the latest versions?

[jackdanielux]

v 0.7 alpha of listmonk and postgres 13 (pgadmin 4)

[knadh]

Yes, that's the latest version listmonk. I have a feeling something subtle may have changed in Postgres 13 (which was released very recently). I'll have to download Postgres 13 and try it out myself. In the meanwhile, if you've time, you could try Postgres 10 or 11, on which I've tested listmonk.

[jackdanielux]

Thanks, got it working. Loved it 👍 Now deploying it on server - have few queries though as below, can you pls help?

• Need Domain to Host Listmonk (standalone / subdomain will do)?

• DKIM email Security - is it a separste step that we need to take care of

• What all things would need to be enabled on server to ensure email delivery (SSL etc.)

• Does the from email (in settings) need to be a working email ID, or can it be anything

• Does from email need to be from same domain on which Listmonk is installed

• How to directly push subscribers (on the fly) to a particular list on Listmonk

• Location of Templates

• Does this qualify as txnal or marketing email (since this in on SES and using a self hosted solution) // While I have seen emails from Zerodha (both txnal and marketing) coming from 2 different email IDs

• How to export subscribers from listmonk (into a csv) for backup

• Considering I have a wordpress blog, how can I auto email my subscribers whenever a new post is published?

• How can a new subscriber be straight added into the 2 opt in list rather than manually uploading data and running opt in campaign?

[knadh]

Need Domain to Host Listmonk (standalone / subdomain will do)?

Domain, sub-domain, an IP, any public address will work.

DKIM email Security - is it a separste step that we need to take care of

This is handled by the mail server. If you're using SES, it's taken care of.

What all things would need to be enabled on server to ensure email delivery (SSL etc.)

If you're using SES (or any other SMTP provider), again, it's taken care of. You might want to Google around to see the best practices.

Does the from email (in settings) need to be a working email ID, or can it be anything

Depends on the mail server's policies.

Does from email need to be from same domain on which Listmonk is installed

Depends on the mail server's policies.

How to directly push subscribers (on the fly) to a particular list on Listmonk

There's an HTML form that can be displayed to visitors (see the Subscribers -> Form) option and there are APIs.

Location of Templates

Templates are managed on the dashboard. Check the Campaign -> Templates menu.

Does this qualify as txnal or marketing email (since this in on SES and using a self hosted solution) // While I have seen emails from Zerodha (both txnal and marketing) coming from 2 different email IDs

listmonk is a generic mail client. This depends on what you're sending and SES policies.

How to export subscribers from listmonk (into a csv) for backup.

For now, you can just dump your Postgres database and take an SQL backup. An export option is planned for a future release.

Considering I have a wordpress blog, how can I auto email my subscribers whenever a new post is published?

You will have to script this using the APIs I linked above.

How can a new subscriber be straight added into the 2 opt in list rather than manually uploading data and running opt in campaign?

When a new subscriber is added to an opt-in list from the dashboard or via the API, they will automatically receive an opt-in notification.

[jackdanielux]

Thanks for the earlier detailed responses.

Currently on Linux 20.04 server with postgres 12 on digital ocean, have done all required installation and settings currently stuck at the below error while generating config file - can you pls help? have given the required permissions (read, write) to the user over the folder where listmonk binary is located.

-bash: ./listmonk: Permission denied

[knadh]

Is the listmonk binary's permission 755?

[jackdanielux]

My bad, I was running from an incorrect user. Thanks. Currently stuck at below error:

IP where it is installed : x.x.x.x
2020/09/29 19:13:36 init.go:170: error connecting to DB: dial tcp x.x.x.x:5432: connect: connection refused

Here's the config file:
address = "x.x.x.x:9000"

admin_username = "listmonkauthusername"
admin_password = "listmonkauthusernamepassword"

Database.

[db]
host = "x.x.x.x"
port = 5432
user = "listmonkpostgresdbuser"
password = "listmonkpostgresdbuserpassword"
database = "listmonkpostgresdbname"
ssl_mode = "disable"

[knadh]

dial tcp x.x.x.x:5432: connect: connection refused. Either the IP is incorrect or the port isn't open (firewall? Is Postgres listening on the local interface?). For a small setup, you can put listmonk and Postgres on the same server.

[jackdanielux]

Tried disabling firewall. Still same error. Even the IP is correct.

For a small setup, you can put listmonk and Postgres on the same server. - You mean on the same postgres server? They are on the same server, it is just that I have created a separate user (apart from postgres) to access a separate db for listmonk.

Is Postgres listening on the local interface? by this you mean is 5432 allowing connect? - Yes, I have disabled the firewall.

if you mean that is the ip:5432 accessible - then no, it says site can't be reached

[jackdanielux]

btw I am using postgres 12 - is it that this may be causing the problem?

And I have not edited the pg_hba.conf file - is that required?

[knadh]

If it’s on the same host, you can just use 127.0.0.1 as the DB host IP in the config.

[jackdanielux]

Changed it - still same error

init.go:170: error connecting to DB: dial tcp 127.0.0.1:5432: connect: connection refused

[knadh]

That means Postgres is either not running or is not listening on that port. You might want to try connecting to Postgres with psql to make sure it’s running.

[jackdanielux]

psql
psql: error: could not connect to server: could not connect to server: No such file or directory
Is the server running locally and accepting
connections on Unix domain socket "/var/run/postgresql/.s.PGSQL.5432"?

This was the error when I tried re-connecting the 2.

[hereiskunalverma]

got it thanks, great application by the way

[sarangarao]

@sals9 if possible could you please share with Developer set up in windows ..https://listmonk.app/docs/developer-setup/ as this is for linux env Make dist is not available in windows command . Please share with us the windows setup

[MaximilianKohler]

Please make a proper guide similar to this Sendy one https://levelup.gitconnected.com/setting-up-your-own-bulk-mail-server-using-sendy-and-aws-20d05ee01362.

Even after reading all the discussion here I don't know how to set up listmonk like that. It should be way less time-taxing to make a simple guide rather than answer all these questions from us noobs (and then we don't even end up with a solution in the end).

This is the best listmonk guide I found https://www.youtube.com/watch?v=fAOBqgR9Yfo but it only covers local install on localhost:9000, which has a ton of limitations, as mentioned here: #862 (comment)

This is the only other listmonk guide I've found https://yasoob.me/posts/setting-up-listmonk-opensource-newsletter-mailing/ and while it mentions EC2 one time, it really doesn't show how to set it up on EC2 similar to that Sendy guide.

Related: #587 (comment)

[mr-karan]

Did you go through the official docs at https://listmonk.app/docs/installation/ ?

Setting up Listmonk using a binary (if you're unfamiliar with Docker) is pretty easy and my preferred way of running it:

• Download binary
• Setup basic configuration to connect to DB
• Start a PostgreSQL instance.

A documentation usually covers a generic usecase which works for 99% of people. Covering all scenarios for all different kinds of environments(EC2/DigitalOcean) is not really possible. However, in context of Listmonk - you can run it on any Linux VM and the instructions would remain the same.

If you can elaborate what is missing in the docs then we can improve them further if needed.

[MaximilianKohler]

Did you go through the official docs at https://listmonk.app/docs/installation/

Yes.

Setting up Listmonk using a binary

I did mention that I completed that with the help of the linked youtube tutorial (your docs weren't/aren't enough), but it has many limitations (see link in previous comment).

A documentation usually covers a generic usecase which works for 99% of people

I don't think yours do.

I think a guide like this https://levelup.gitconnected.com/setting-up-your-own-bulk-mail-server-using-sendy-and-aws-20d05ee01362 might cover close to 70% use cases. But parts of it seemed outdated already, and possibly people who aren't hosting on EC2 might have more difficulty or need another guide.

My comments here covered the issues I'm having:

• Complete Setup Guide for Binary #862 (comment)
• Unclear on where to start and impact on existing server. #587 (comment)

[MaximilianKohler]

Isn't using listmonk with EC2 and SES one of the primary use cases since you get 62k/mo free emails and 1yr free EC2 micro? If you go to fiverr and search "sendy" you get a bunch of people able to set it up for you, but there are 0 results for listmonk, so we can't even hire someone if we wanted.

So:

• Sendy: multiple guides, many people to hire.
• Listmonk: 0 guides and 0 people to hire.

EDIT: More example guides:

• https://www.youtube.com/watch?v=tT5wU7ij3io
• https://www.mailwizz.com/videos/

This kind of stuff lets average people use the product, otherwise we have no idea what to do. Though that's missing info on setting up with AWS EC2, so it would have to be paired with the Sendy guide showing how to setup and use virtualmin on EC2.

[MaximilianKohler]

AWS Lightsail install:

#1208

Railway install

Right below this comment.

EC2 micro install

(and much more)

Moved to: https://gist.github.com/MaximilianKohler/e5158fcfe6de80a9069926a67afcae11 to make it easier for people to find.

---

Old complaints/history:

Note: do not use "sudo -i". It will install things into the wrong directory. If you don't want to type "sudo" all the time, "sudo bash" might work. But for these, copy-paste is fine.
EDIT: I actually removed sudo from many lines below, as it was unnecessary and possibly caused by erroneously putting sudo in front of mkdir listmonk to start with. If you have to put sudo in front of any lines below, you probably messed something up. These things are finicky, and commands have to be so precise or you can run into so many problems. Another reason a novice like me should not be having to write this guide.

Lesson: don't use sudo unnecessarily. Especially when creating directories and files. Since it sets the permissions of them to root.

SSL:

https://yasoob.me/posts/setting-up-listmonk-opensource-newsletter-mailing/

First copy the contents of the "nginx.conf" file and paste into text file. Replace (ctrl+h) all 4 instances of "example.com" with the subdomain hostname from the previous step -- IE: listmonk.mysite.com.

Go back to cmd:

mkdir -p data/nginx
cd data/nginx
nano ./nginx.conf

Paste in your edited nginx.conf. Save and exit.

Edit the "init-letsencrypt.sh" in a text file.

Go back to cmd:

cd
nano ./init-letsencrypt.sh

paste in the contents of the "init-letsencrypt.sh" text file. Save and exit.

nano ./docker-compose.yml
paste in the NGINX and certbot lines.

Save and exit. Then run:
sudo bash ./init-letsencrypt.sh
sudo docker start certbot

---

Initially I did the above instructions without the sudo docker-compose up nginx line after "Paste in your edited nginx.conf. Save and exit." and we got errors: https://user-images.githubusercontent.com/3606996/201724164-eb44bf32-49a6-411f-9f23-9ed3a2ab818b.jpg

Requesting a certificate for listmonk.mysite.com
Certbot failed to authenticate some domains
Detail: connection refused

This is a perfect example of a main complaint I have. yasoob clearly figured it out, but his directions were only geared towards super technical people. And I even had a super technical person help me, and they wasted hours on this when the solution was a simple missing command that you and/or yasoob could have easily spelled out for us.

I know you guys know these commands and steps very well, and could have written out the above steps very trivially within a few minutes. Yet we wasted so many hours & days on this.

Why put all this time into this project and make it so unnecessarily difficult for people to use it?

EDIT: turns out it was not that line that fixes the issue. That line in that spot results in:

ubuntu@listmonk:~$ sudo docker-compose up nginx
ERROR: No such service: nginx

It seems that the issue was due to unnecessary use of sudo.

[candidexmedia]

Hey folks! I made an informal step-by-step on how to get started with Listmonk using Railway on Twitter: https://twitter.com/candidexmedia/status/1623032874172616708

Alternative: https://nitter.net/candidexmedia/status/1623032874172616708#m

I've included screenshots and short videos

[knadh]

This is very nice, @candidexmedia!

Twitter, unfortunately, is an unreliable place to storage useful information. Hard to discover also. Why don't you add this to the listmonk docs as-is? We can create a new tutorials sections for tutorials like this.

[candidexmedia]

Hey @knadh :

Twitter, unfortunately, is an unreliable place to storage useful information. Hard to discover also.
That's true. I used Twitter to engage with conversations about MailChimp, which were on the rise following the updates to their free plan.

We can create a new tutorials sections for tutorials like this.

Sounds good, let me know once a tutorials/how-tos section exists. I think it should be separate from the current docs, as this guide is more conversational and less of a reference.

[knadh]

We could just add a new subdirectory/subsection called Tutorials.

[MaximilianKohler]

I think a "tutorials" link here https://listmonk.app/#download or here https://listmonk.app/docs/installation/ would be ideal. That's where I first looked for directions and dismissed Listmonk because I couldn't find any.

[candidexmedia]

@knadh : I'd recommend checking out how Publii has their docs set up, especially in terms of layout and structure:

They have docs for Developers, docs for Users, tutorials, and how-to guides.

Listmonk's doesn't need to be as fragmented, but I like how Publii's different doc types speak to each other, kind of like what @MaximilianKohler mentions.

As the number of tutorials and how-to guides grows, it would be good to ensure that the listing of articles is effectively showcased within the site, kind of like a blog. Does the current stack allow for this?

[MaximilianKohler]

Hey folks! I made an informal step-by-step on how to get started with Listmonk using Railway on Twitter: https://twitter.com/candidexmedia/status/1623032874172616708

I've included screenshots and short videos

I've been looking into Railway, and checked out your guide again. It would be great if you made your own thread with your guide and included your custom CSS code.

After reviewing your guide and the Railway docs, one thing I'm not sure about is maintaining/accessing the server. With AWS EC2 and Hetzner, I connect to them with Putty and FileZilla very similarly. But I haven't seen how that works with Railway.

BTW, I submitted a pull request to add a "tutorials" section to the bottom of the docs, like you suggested.

[candidexmedia]

Hey @MaximilianKohler : Thanks for checking the guide out.

It would be great if you made your own thread with your guide and included your custom CSS code.

I'm working on a more fulsome post on my blog with code snippets. What did you mean "own thread"?

After reviewing your guide and the Railway docs, one thing I'm not sure about is maintaining/accessing the server.

The database and deployment settings can accessed from your Railway.app dashboard. There's also a command-line tool (Railway CLI) with more advanced functionality, but I don't use it much, so I'm not sure if that's what you mean by "maintaining/accessing the server". What are you attempting to access?

BTW, I submitted a pull request to add a "tutorials" section to the bottom of the docs, like you suggested.

Sweet, thank you! 😃

[MaximilianKohler]

What did you mean "own thread"?

A post on your blog would be fine. I meant like this: #1208

so I'm not sure if that's what you mean by "maintaining/accessing the server". What are you attempting to access?

For example, with AWS EC2 https://gist.github.com/MaximilianKohler/e5158fcfe6de80a9069926a67afcae11 I have to run sudo apt update && sudo apt upgrade -y every once in a while to keep my server updated. I also run backup commands: https://gist.github.com/MaximilianKohler/e5158fcfe6de80a9069926a67afcae11#backup and connect to my server with Putty and FileZilla.

Basically, if your full Railway guide can cover all the aspects in my EC2 guide (including downgrading), that would be great. Also, if you could cover the differences (ease of use, costs, etc.) compared to a standard cloud host like EC2, digital ocean, etc., that would be useful.

[candidexmedia]

@MaximilianKohler Thanks for the suggestions and examples! I just recently learned about how downgrading is done for Listmonk with docker, so it's something I'll have to test with Railway.

Also, if you could cover the differences (ease of use, costs, etc.) compared to a standard cloud host like EC2, digital ocean, etc., that would be useful.

I'll admit: I have very little expertise when it comes to standard cloud hosting, so I don't think I could provide a proper comparison. I only use one-click services like Railway, Heroku, Pikapods, etc. because they are super easy to use, but that may not mean that they are the best choice for those who know what they're doing, you know?

I think there are certain things that are possible to do with cloud hosting which may not be as straightforward or possible with one-click deployment services, such as the custom static directory mentioned here or accessing the database (in Pikapods' case).

I think my guide will focus more on how to use the app: designing emails, customization, managing media, that kind of thing. That said, covering upgrading, redeployment, and other basic maintenance pieces is something I'll keep in mind. Thanks again!

[MaximilianKohler]

I just recently learned about how downgrading is done for Listmonk with docker

Is this correct? #1457 - I mostly guessed at the commands.

[candidexmedia]

I just recently learned about how downgrading is done for Listmonk with docker

Is this correct? #1457 - I mostly guessed at the commands.

Sorry, I thought I had answered this! I remembered trying the commands out back when you sent this by editing the dockerfile and having it work. That said, it's been a while. 😅 The discussion in the other thread about restoring the previous db version (and making backups) is an important one.

I really appreciate all the updates you've done to the docs and efforts to catalogue information @MaximilianKohler. I still wish there was a separate user guide for Listmonk outside of the dev docs -- somewhere where we, the community, can share tips about designing templates, picking the right SMTP (and all the DMARC/SKIM/SPF stuff related to it), bounce processing, etc. -- like Publii and Penpot have.

Anyway, Railway has changed quite a bit about how their templates and services work since I posted that Tweet thread. There have been major improvements, like being able to deploy a docker container that pulls from latest (instead of from a GitHub deploy + dockerfile), and persistent storage volumes (which makes saving images in the filesystem possible). I even found out that creating a custom static directory is possible in Railway.

I'll probably scan the docs to update some stuff relating to Railway. I do want to wait a bit before releasing a full guide, since I understand that a major refactor / release is coming up?

[MaximilianKohler]

I still wish there was a separate user guide for Listmonk outside of the dev docs -- somewhere where we, the community, can share tips about designing templates, picking the right SMTP (and all the DMARC/SKIM/SPF stuff related to it), bounce processing, etc.

You could do it in an issue here, or you can use the comments here https://gist.github.com/MaximilianKohler/e5158fcfe6de80a9069926a67afcae11.