Pleroma for Dummies

With the recent surge in popularity of Twitter alternatives, I found myself giving Mastodon a shot -- I'm hardly at risk of being censored on Twitter, but I fancied a place that didn't fuck with my timeline.

In doing so, I discovered that Mastodon is simply one facet of a greater Fediverse -- and while it seems to be one of the more polished facets, there's an awful lot of mastotooting going on (Mastotooting; verb: to post ("toot") about how great the Mastodon social network is, from inside the Mastodon network itself) and, according to some technically-minded souls, not the most efficient facet. (And if you want to get into community politics, some criticize the lead developer's approach, that he just wants to be @jack 2.0.)

And so, I was introduced exposed to Pleroma. Like Mastodon, it integrates with the Fediverse, but unlike Mastodon, it consumes a lot less resources and is generally more suited to running on a smaller private server for one person who likes having domain name swag in their handle.

Unfortunately for my dreams of running a Pleroma instance for myself, I'm a fucking dumbass when it comes to Linux. I work with it so infrequently, every time I have to do something, it's like learning how to walk all over again.

But all was not lost -- there existed several guides which, for someone with a vague grasp as myself, would in theory be a bulletproof guide to helping me set things up.

But again, to my dismay, the guides are not perfect. They are either (I would consider) inconsistent, slightly outdated, or simply omit what might be considered common knowledge / common sense to an experienced user, and so someone less Linux-literate might fail. And so I regularly found myself stumped.

But! I got there eventually, and now I can share what I've learned from the process, and hopefully, make Pleroma easier to install.

Before we start:

This guide assumes you're generally familiar with computers (You are a competent typist, know how to quickly copy/paste, can navigate files / folders quickly), but not so much so with Linux, and so you're coming at this blind, and need baby steps.


This guide also assumes that you've got/had a Mastodon account somewhere, or have otherwise experienced the Fediverse at large. If not, you might want to sign up on a Mastodon server first.

Why? The thing that attracts a lot of people is that Mastodon / Pleroma doesn't suggest things to you, insert stuff into your timeline, or try to guess what you might like to see with Algorithms.

The caveat is that you're not suggested anything. If you don't already have an existing list of people to follow in the Fediverse, you are relying on the federation being pulled in by other users on the server (the "federated timeline") to give you content to consume.

...But you're creating a server that will just be hosting you to start with, so that federated timeline will be awfully empty, and getting a decent stream of content will be difficult. (Even if you're on the fediverse to shitpost, not to be shitposted at, nobody will see your posts if nobody's following you -- and the best way to be followed is through follow-backs.)

Creating an account on an existing, decently-populated Mastodon (or Pleroma) server will inevitably give you a decent stream of content in the local and federated timelines, users to follow, and a much greater chance of enjoying your new Pleroma instance.

That said, you can't import your Mastodon account to Pleroma at this time of writing, so don't go too overboard.

Links / articles I found useful:

https://www.digitalocean.com/community/tutorials/how-to-install-nginx-on-debian-8
https://www.digitalocean.com/community/tutorials/how-to-secure-nginx-with-let-s-encrypt-on-debian-8
https://i2p.rocks/blog/the-magical-world-of-pleroma-setting-up-your-instance.html
https://git.pleroma.social/pleroma/pleroma/wikis/Installing%20on%20Debian%20based%20distributions

For an example of a functioning Pleroma site, see http://pleroma.soykaf.com/




Mouse over (!) for my comments in-line.

You will need:

- A Debian 9.5 server / VM -- The cheapest of Digital Ocean's droplets works just fine. (!)
- A domain name -- anything will do, but:
    - Make sure your nameservers will let you set up custom DNS records (i.e. subdomains) (!)
    - There's more TLDs in this world than just .COM and .NET, and some of them make interesting (sub)domain names. (e.g. http://lets.split-the.party/) (!)


And that is basically all the prep work we need. Note that I've deliberately ignored most of the "you will need" stuff mentioned in above links -- you don't specifically need to go out and get them, we'll be acquiring them as part of the steps.

Spin up a droplet, and let's get started:

It's a 36-step process, as it turns out, but only because we're taking it one literal step at a time.

1. Set up your domain -- Decide what (sub)domain you want to see Pleroma at, and point it at your droplet's IP address. Remember that the (sub)domain you pick will be part of your handle, e.g. hasashi.ninja could make:
   
   @hanzo@hasashi.ninja
   
   We're doing this first, because DNS propagation is a pain in the ass to wait for. (!)
    
2. SSH into your server IP -- if you're not familiar, use PuTTY to connect to your droplet's IP address directly. The username will be "root" and the password sent to you by Digital Ocean by email separately when the droplet's set up. (!) (!)
    
3. Per the Wiki, update the system:
   
   apt update && apt dist-upgrade
   
   If asked, keep the already-installed versions.
    
4. Install stuff:
   
   apt-get install build-essential git wget postgresql nginx certbot sudo
   
   This installs stuff we need. Because blindly downloading things without any idea what they do is not great:
   
   - git gets the Pleroma files off of Gitlab.
   - wget is used to download stuff.
   - postgresql is for databases.
   - nginx is for the actual web interface, assuming you want one.
   - certbot to generate (free) SSL certificates. (!)
   - sudo so that a non-root user will actually be able to do root things.
    
5. Download the Erlang repository:
   
   wget -P /tmp/ https://packages.erlang-solutions.com/erlang-solutions_1.0_all.deb && sudo dpkg -i /tmp/erlang-solutions_1.0_all.deb
    
6. Install Elixir and Erlang:
   
   apt update && apt install elixir erlang-dev erlang-parsetools erlang-xmerl erlang-tools
    
7. Add a "pleroma" user. (!)
   
   adduser pleroma
    
8. Give the user sudo rights:
   
   usermod -aG sudo pleroma
    
9. Switch to them, and switch to home directory:
   
   su pleroma
   cd ~
    
10. Clone the latest Pleroma data:
    
    git clone https://git.pleroma.social/pleroma/pleroma
     
11. Change to that folder:
    
    cd pleroma/
     
12. Install dependencies - if asked, say yes to hex:
    
    mix deps.get
     
13. Generate a config -- again, say yes to rebar3:
    
    mix generate_config
    
    - This will take a minute or so due to compiling stuff.
    - You'll be asked some questions about your instance:
        - Domain name for the instance (!)
        - Name of the instance (!)
        - Admin email - pick an address that works and you don't mind being publicly visible. (!)
     
14. Edit that config file to make sure it's to your liking:
    
    nano config/generated_config.exs
    
    (Assuming you're still inside the pleroma folder -- as Root, the absolute path: nano /home/pleroma/pleroma/config/generated_config.exs )
    
    This is where you can enable / disable media_proxy. No pressure, I don't think it has a particular immediate effect, and you can change this later.
     
15. Rename the config file so that Pleroma can use it:
    
    mv config/{generated_config.exs,prod.secret.exs}
    
    (Yes, you could then use nano /home/pleroma/pleroma/config/prod.secret.exs to find and edit it later.)
     
16. Set up the database:
    
    sudo su postgres -c 'psql -f config/setup_db.psql'
    
    Give it a moment to finish.
     
17. Migrate the database / recompile Pleroma:
    
    MIX_ENV=prod mix ecto.migrate
    
    Note the MIX_ENV=prod at the start -- very important. (!)
    
    This also needs to be done if you update Pleroma in future, so don't forget.
     
18. Start Pleroma!
    
    MIX_ENV=prod mix phx.server
     
19. Test to make sure it's working, by going to the following in a web browser:
    
    http://[yourdomain]:4000/api/v1/instance
    
    You might need to allow a little time for DNS propagation if the page can't be reached yet. ("err_name_not_resolved" in Chrome) Wait 1-2 hours in that case, then try again.
    
    If it's working, you should see some stuff that looks like the information you filled in during setup, and in PuTTY, some logs will pop up as the page loads.
     
20. Kill Pleroma with CTRL+C, and then (A)bort. We've still got things to do, and a web interface to set up.
     
21. Log out, back to root:
    
    exit
    
    
     
22. We need to set up the SSL -- looking at the Digital Ocean Debian 8 guide from roughly "How to use the webroot plugin" may be educational so you have a vague idea of where we're going. (We've already installed certbot in Step 4, so nothing above that is needed.)
     
23. Prove that the default nginx config is OK:
    
    nginx -t
     
24. Make the folder that LetsEncrypt needs to access to prove you control the domain:
    
    mkdir -p /var/www/html/letsencrypt/.well-known
     
25. Request the certificate:
    
    certbot certonly -a webroot --webroot-path=/var/www/html -d [yourdomainhere] --email [youremailhere]
    
    Make sure that the email is, again, one that you can access and check, just in case.
    
    After a moment, it should hopefully succeed. Accept / OK through stuff, making copies for future reference if you want.
26. Copy the Pleroma nginx config to the right folder:
    
    cp /home/pleroma/pleroma/installation/pleroma.nginx /etc/nginx/sites-enabled/pleroma.nginx
     
27. Edit the config to suit your domain:
    
    nano /etc/nginx/sites-enabled/pleroma.nginx
    
    Make sure to replace any instance of yourdomain.tld with your Pleroma domain. (Should be about 5 places to replace it -- top, three times in the SSL cert / key section, and once again further down)
     
28. Edit the default nginx config:
    
    nano /etc/nginx/sites-available/default
     
29. Set the "root" value to the path where you put pleroma, + /priv/static -- e.g:
    
    /home/pleroma/pleroma/priv/static
     
30. Under section:
    
    location / {
    
    change try_files to:
    
    $uri $uri/ /index.html;
    
    See this DO forum page for an example of this / more info on why we do it. (tl;dr: The page tended to 404 before going to the index page.)
     
31. Prove that your nginx config is (still) OK:
    
    nginx -t
    
    If it's not OK, something's busted.
     
32. Restart nginx:
     
    systemctl restart nginx.service
    
    
     
33. We're not done yet! You want a systemd service. Copy the example service file:
    
    cp /home/pleroma/pleroma/installation/pleroma.service /usr/lib/systemd/system/pleroma.service
     
34. Edit the service file, make sure all paths fits your installation (they should, by default) and add the following line under the [Service] section:
    
    Environment="MIX_ENV=prod"
     
35. Enable / start Pleroma with the systemd:
    
    systemctl enable --now pleroma.service
    
    You can now start / stop Pleroma much like you would nginx. (e.g. systemctl restart pleroma.service)
     
36. Visit your domain name in a web browser, you should now see your Pleroma install!

What next?

• Try creating a user.
   
• You might be tempted to import your exported list of accounts you were following on a Mastodon instance. While this can be done, I found it extremely problematic, and while it said I was following them, I wasn't seeing any of their posts. I eventually had to unfollow and manually re-follow users, 1 or 2 at a time.
   
• Try creating a figurehead user to serve as the "admin". If you're ever going to have other users on your platform, it helps to have an account through which you can easily delete their abusive content -- but it's also good to not make your every-day account that admin user, in case:
  
  - It is hacked / compromised
  - You mis-click
  - You don't want people pissing and moaning at you when you just want to relax and enjoy the server you run.
  
  Once the user exists, log into your server via PuTTY again, and:
  
  cd /home/pleroma/pleroma/
  
  MIX_ENV=prod mix set_moderator [user] true
   
• Customize your Terms of Service:
  
  nano /home/pleroma/pleroma/priv/static/static/terms-of-service.html
  
  You're the boss, so make 'em whatever you want.
   
• Try adding a custom emoji:
  
  - Upload it to /home/pleroma/pleroma/priv/static/emoji/custom (.PNG, 50kb or less) (You can use FTP -- just connect to your (sub)domain or IP, using your Root username and password)
   - Add it: nano /home/pleroma/pleroma/config/custom_emoji.txt
  - Recompile: cd /home/pleroma/pleroma/ && MIX_ENV=prod mix clean && MIX_ENV=prod mix compile
  - Restart Pleroma: systemctl restart pleroma.service

Hopefully that covers everything. If it doesn't, @yesnaught on Twitter for corrections.