Installing Postleaf

Postleaf is a Node.js application that needs to run on a web server. You can install it locally for development purposes, but if you want to keep your website online 24/7 you'll need to purchase a proper web server.

To install Postleaf, you should be reasonably comfortable using a Linux or Unix terminal. Prior knowledge of Node.js, Git, and Nginx is also recommended.

If you're not comfortable installing Postleaf yourself, I will be happy to set it up for you on DigitalOcean for a one-time fee of $99 USD. This is a great way to support the project financially while also avoiding installing it yourself.


DIY

Postleaf requires a VPS with at least 512MB. It may run well with less memory, but the official recommendation is 512MB. The amount of disk space required will vary depending on your usage. Most modern VPSes will have more than enough space.

Dependencies

The following dependencies are required:

  • Node.js version 7 (lower versions have not been tested and are not supported)
  • npm
  • SQLite 3
  • GraphicsMagick
  • Git (recommended)

SMTP

Sending emails programmatically is hard. Because of that, you will need access to an SMTP server. Otherwise, you won't be able to create users, perform password resets, etc. It is a requirement for a proper Postleaf install, so please don't ignore this.

If you don't already have a transactional email service, the folks over at Discourse have put together a great list of email providers — many of which offer free plans.

Installation

Make sure you've already installed the necessary dependencies. Once you have, it's time to install Postleaf.

Create a directory (let's call it /var/www/postleaf) and clone the main repo and the default theme's repo.

mkdir -p /var/www/postleaf
cd /var/www/postleaf
git clone https://github.com/Postleaf/postleaf.git
git clone https://github.com/Postleaf/empower-theme.git postleaf/themes/empower-theme

The next step is to create an .env file. The easiest way to do this is by copying .env.example. Now open it and update the following values:

  • NODE_ENV – set this to production
  • APP_URL – set this to the domain you want to run Postleaf on
  • AUTH_SECRET – set this to a long, random string (tip: use a generator)
  • SMTP_HOST – your SMTP provider's hostname
  • SMTP_USERNAME – your SMTP username
  • SMTP_PASSWORD – your SMTP password
  • SMTP_PORT – your SMTP port
  • SMTP_SECURE – set to true to use TLS
  • SMTP_FROM_NAME – the name emails will be sent from by default
  • SMTP_FROM_EMAIL – the email address emails will be sent from by default

Now, from the same directory, run this command to install the necessary modules to run Postleaf.

npm install

This usually takes a few minutes to complete. Once complete, you're ready to run Postleaf.

Running

You can test your installation by running Postleaf with the following command.

node app.js

If all goes well, you should see a message stating Postleaf is running. If you see an error, you'll need to troubleshoot your installation. Feel free to ask for help on the forum if you get stuck.

It's generally a good idea to use a process manager such as pm2 to keep the app running. App crashes happen. Server restarts happen. A process manager will keep things running when they do.

You'll also want to put a reverse proxy in front of Postleaf to serve the app and handle SSL certificates. I recommend Nginx, but you can also use Apache or Caddy if you prefer.


Alas, configuring servers, process managers, and proxies is a very opinionated subject and is way beyond the scope of this page.

If you happen to be using DigitalOcean, I've written a thorough tutorial that will help you perform a proper install with Ubuntu, Nginx, and pm2. It covers everything from creating the droplet all the way down to setting up a free SSL certificate.

As always, if you need help head over to the community forum.