- How to Deploy Kill the Newsletter! (and other Node.js Applications)
- A code review from an older version
The simplest way to use Kill the Newsletter! is with the hosted version at https://kill-the-newsletter.com.
Kill the Newsletter! is and will always be free; you don’t have to create an account; and I don’t collect your data or share it with anyone.
You may run Kill the Newsletter! on your own servers if you wish. This guarantees the utmost privacy, and it’s also a fun system adminstration project. Kill the Newsletter! strikes a good balance between being relatively easy to self-host and being non-trivial at the same time, because it is a web application as well as an email server.
The best way to start self-hosting is to test Kill the Newsletter! on your machine. You can’t really use Kill the Newsletter! if it’s running on your machine because Kill the Newsletter!’s email server must be accessible from the internet to receive email and most likely your internet service provider blocks this kind of connection to prevent spam. Still, this is a good first step to get your feet wet by downloading and running Kill the Newsletter! for the first time.
Download the latest release and give it a try. You may send test emails using curl by creating a file like the following:
email.txt
From: Publisher <[email protected]>
To: ru9rmeebswmcy7wx@localhost
Subject: Test email with HTML
Date: Sat, 13 Mar 2021 11:30:40
<p>Some HTML</p>
And then running the following command:
$ curl smtp://localhost:2525 --mail-from [email protected] --mail-rcpt ru9rmeebswmcy7wx@localhost --upload-file email.txt
Remember to change the ru9rmeebswmcy7wx in the example above to the appropriate email address for your Kill the Newsletter! test inbox.
To install Kill the Newsletter! on your own server you’ll need:
-
A domain (for example,
kill-the-newsletter.com). I buy domains at Namecheap. -
A DNS server. I use the DNS server that comes with the domain I bought at Namecheap (and they even provide free DNS service for domains bought elsewhere).
-
A server. I rent a $6/month DigitalOcean droplet created with the following configuration:
Distributions Ubuntu 20.04 (LTS) Plan Share CPU · Regular Intel · $5/mo Datacenter region I use New York 1, but you should use whatever is closest to you Additional options IPv6 & Monitoring Authentication SSH keys Hostname Your domain, for example, kill-the-newsletter.comBackups Enabled (that’s what makes the $5/month plan actually cost $6/month) I also like to assign the droplet a Floating IP because it allows me to destroy and create droplets without having to change the DNS and wait for the DNS propagation to happen.
This is the cheapest DigitalOcean offering, and yet it has managed Kill the Newsletter!’s traffic for years, even when it occasionally receives extra attention, for example, when it makes the front page of HackerNews.
This is where you associate domains to servers. For example, you associate kill-the-newsletter.com to the DigitalOcean droplet on which Kill the Newsletter! runs.
| Type | Host | Value |
|---|---|---|
A |
@ |
The (Floating) IP address of the server |
Alias |
www |
Your domain, for example, kill-the-newsletter.com |
MX |
@ |
Your domain, for example, kill-the-newsletter.com |
SSH into the server and download Kill the Newsletter!:
[your machine] $ ssh [email protected]
[the server] # mkdir kill-the-newsletter && cd kill-the-newsletter
[the server] # curl -O https://github.com/leafac/kill-the-newsletter/releases/download/<version>/kill-the-newsletter--linux--<version>.tgz
[the server] # tar -xzf kill-the-newsletter--linux--<version>.tgzYou may adapt deployment-example/configuration.js, which is the configuration running at https://kill-the-newsletter.com. In particular, you must change the following lines:
// ...
webApplication.set("url", "https://kill-the-newsletter.com");
webApplication.set("email", "smtp://kill-the-newsletter.com");
webApplication.set("administrator", "mailto:[email protected]");
// ...
domains: ["kill-the-newsletter.com", "www.kill-the-newsletter.com"],
// ...At this point you’re ready to run Kill the Newsletter! for real:
[the server] # ./kill-the-newsletter configuration.jsKill the Newsletter! starts a web server and an email server. They include everything you need to run securely in production, including support for HTTPS.
Isn’t running the service as root a bad idea?
This practice is frowned upon, but it may be okay in some cases (that’s how I’ve been running https://kill-the-newsletter.com for years). If the only thing of value on a machine is Kill the Newsletter!, then what would you be protecting by running the service as a unprivileged user? The most important things is the data, but that should be accessible from the unprivileged user anyway. I prefer to treat the machine as disposable and run the service as root—it’s as simple as it gets.
Install Kill the Newsletter! as a systemd Service
This ensures that Kill the Newsletter! is always running. If it hits an error and halts, systemd restarts it. If the machine reboots, systemd starts Kill the Newsletter! again.
First, stop the server you ran in the previous step.
Then, create a file at /etc/systemd/system/kill-the-newsletter.service with the contents from deployment-example/kill-the-newsletter.service.
Finally, run the following commands:
[the server] # systemctl daemon-reload
[the server] # systemctl enable kill-the-newsletter
[the server] # systemctl restart kill-the-newsletterYou may log out of the server and start enjoying your own Kill the Newsletter! installation.
All the data is stored under the data directory as a SQLite database. If you every have to migrate to a different server, just take the data directory with you.
To update, just download and extract a newer release, and then restart the service with the following command:
[the server] # systemctl restart kill-the-newsletterThe guide above covers the basics of running Kill the Newsletter! on a Linux server, which is the most common way of deploying web services, but there are executables for Windows and macOS as well. The process is similar up to the point of installing Kill the Newsletter! as a systemd service, because other operating systems use other process managers.
The configuration.js file is a JavaScript module that must return a function to be called by the kill-the-newsletter executable. Typically this configuration will start the servers (web and email) for Kill the Newsletter!, but it may do anything you wish. The kill-the-newsletter executable simply calls the configuration.js file and passes a require() function from the perspective of Kill the Newsletter! itself. You may require(".") to get a hold of the killTheNewsletter() function, which produces the webApplication and the emailApplication. You may also require() any of the Kill the Newsletter! production dependencies listed in package.json.
If you installed Kill the Newsletter! before 2021-03-18 then you need to start from scratch because the deployment process changed (it’s much simpler now!). You may migrate existing feeds with the migration tools found in the v1.0.1 release or the migration tag. Just make a backup of your feeds/ directory, download the migration executable, and run it from the directory containing feeds/. It’ll produce a data/ directory with the data in the new format.
Using the kill-the-newsletter npm Package
For people familiar with TypeScript/JavaScript, Kill the Newsletter! is also distributed as an npm package. You may run it with npx kill-the-newsletter, or npm install kill-the-newsletter into your project to import or require it and mount it as part of a bigger Express application.