In this article, you will learn how to install the Pleroma federated social media app. Even if you are only planning on hosting this site for a single user, your account can interface with other instances in the “Fediverse.” Likewise, other users can follow and post your content onto their sites.
- Install Dependencies
- Restart Services
- Create a Pleroma User Account
- Download The Pleroma Application
- Running The Pleroma Installation
- Configure Your Domain For Nginx
- Configuring the Nginx Web Server
- Creating the SystemD Service
- Create An Admin User
- Enjoy Your New Community
Install Dependencies
First, you will need to install the software packages that allow Pleroma to run properly. You can install all of these apps with the following command:
apt install -y curl unzip libncurses5 postgresql postgresql-contrib nginx certbot libmagic-dev
Some of these may already be installed on your server. Fear not, if you run this command the apt package manager will simply skip over any installed packages.
Restart Services
And for good measure, go ahead and restart the PostgreSQL server:
systemctl restart postgresql
And, of course, to solidify the web server settings, restart Nginx:
systemctl restart nginx
Load up your domain, and you should see your Pleroma instance.
Create a Pleroma User Account
For the day-to-day maintenance of your Pleroma site, you will not want to use your root user. So it is recommended that you create a new user in your server for certain tasks. With the command below, you will be creating a Linux user named “pleroma” to handle administrative tasks on the command line. Note: this is not going to be the user account you will use to log into the site and create posts.
You can run this command to create the “pleroma” Linux user:
useradd -m -s /bin/bash -d /opt/pleroma pleroma
In order to switch to this user, you will need to use the su command:
su -l pleroma
Throughout this tutorial you will be switching between the pleroma user and the root user. If you have switched to the pleroma user you can easily get back to root by typing exit into your terminal.
As the root user, you must run the command below to set up a series of directories that will be used by the Pleroma application, and set ownership of those directories to the pleroma user. You can copy and paste this entire block into your terminal:
mkdir -p /var/lib/pleroma/uploads && chown -R pleroma /var/lib/pleroma && mkdir -p /var/lib/pleroma/static && chown -R pleroma /var/lib/pleroma && mkdir -p /etc/pleroma && chown -R pleroma /etc/pleroma
Download The Pleroma Application
Now, you will switch to the pleroma user to download the application using the curl command. First, the switch:
su -l pleroma
And then the command to download the program and place the installation files in the tmp directory:
curl 'https://git.pleroma.social/api/v4/projects/2/jobs/artifacts/stable/download?job=amd64' -o /tmp/pleroma.zip && unzip /tmp/pleroma.zip -d /tmp/
Now, you will move some files around, generate the configuration for Pleroma, and set up your database:
mv /tmp/release/* /opt/pleroma && rmdir /tmp/release && rm /tmp/pleroma.zip && ./bin/pleroma_ctl instance gen --output /etc/pleroma/config.exs --output-psql /tmp/setup_db.psql
Now, you will be asked a series of questions about your installation. You can skip any of these questions by pressing <ENTER> for a default value (in brackets).
- What domain will you use for your instance?
- This is up to you. Make sure to use a domain that is pointing to your server with either an A or CNAME record, as you require.
- What is the name of your instance?
- This is the site title for your installation. Don’t worry, this can be changed later.
- What is your admin email address?
- What email address would you like to set up as your admin email? You will not receive any messages here until you have configured your site for email delivery (which is optional).
- What email address do you want to use for sending email notifications?
- Similarly, if you have configured your site for email delivery, those notifications will go out to users from an email address of your choosing.
- Do you want search engines to index your site?
- This is a simple yes or no question. If the answer is no, search engines will be asked to bypass your site, but there is no guarantee that a search engine will abide by that condition.
- Do you want to store the configuration in the database (allows controlling it from admin-fe)?
- Another yes or no question, asking if you want to be able to make changes to your site from the administrative interface. These changes will be saved in your database. This means that your site configuration will be programmable from the web interface, and you can restore your configuration from a database backup. For many users, this is probably the best option. Otherwise, configurations will be need to be made at the level of the system configuration file.
- What is the hostname of your database?
- Go ahead and press enter to select localhost, unless you have a custom database configuration.
- What is the name of your database?
- Again, unless you have a custom database configuration, you can select the default value here by pressing <ENTER>.
- What is the user used to connect to your database?
- Unless you want to use a specific database user, you can also select the default value here.
- What is the password used to connect to your database?
- For this question as well, unless you have a specific password you would like the database user to use, you can press <ENTER> to accept the default value.
- Would you like to use RUM indices?
- Likewise, the default value is acceptable here.
- What port will the app listen to (leave it if you are using the default setup with nginx)?
- The default value here is also acceptable.
- What ip will the app listen to (leave it if you are using the default setup with nginx)?
- The default value is also acceptable here.
- What directory should media uploads go in (when using the local uploader)?
- Left with the default value, Pleroma will use the directory you have already created for this purpose:
/var/lib/pleroma/uploads/. - What directory should custom public files be read from (custom emojis, frontend bundle overrides, robots.txt, etc.)?
- Left untouched, this will default to the directory already created,
/var/lib/pleroma/static. - Do you want to strip location (GPS) data from uploaded images? This requires exiftool, it was detected as not installed, please install it if you answer yes.
- Unless you have installed the required software for this feature, you can answer no.
- Do you want to anonymize the filenames of uploads?
- A yes/no question that depends on your desired result. Neither option will interfere with normal operation of the site.
- Do you want to deduplicate uploaded files?
- This question also depends on your own preference and accepts a yes or no answer.
Once you have answered all of the questions, your installation is configured, and you can move on to the next steps.
Returning to the root user with exit, execute this command to complete the database setup as the postgres user:
su postgres -s $SHELL -lc "psql -f /tmp/setup_db.psql"
Running The Pleroma Installation
Now it’s time to do a test drive of your Pleroma installation. For the next series of commands you must switch to the pleroma user:
su -l pleroma && ./bin/pleroma_ctl migrate && ./bin/pleroma daemon
To test the installation, you can run the following command:
curl http://localhost:4000/api/v1/instance
If you get a long output, everything should be running well, and you can stop the daemon:
./bin/pleroma stop
Configure Your Domain For Nginx
On your InMotion Hosting cloud server, you will note that Apache is already running. So in order to use Nginx, you will need to stop the Apache web server:
systemctl stop apache2
Note: in order to use Pleroma properly your domain name must be pointing to your server with an A record or CNAME record.
Configuring the Nginx Web Server
Now, as the root user again, you will copy the configuration file for Nginx right from the Pleroma installation files:
cp /opt/pleroma/installation/pleroma.nginx /etc/nginx/sites-available/pleroma.conf
Then, create a symlink from the sites-available directory to the sites-enabled directory file:
ln -s /etc/nginx/sites-available/pleroma.conf /etc/nginx/sites-enabled/pleroma.conf
Make sure to edit the sample configuration file to replace any instances of “example.tld” with your domain. In this example, the command below uses the nano text editor, but you can use any text editor you prefer:
nano /etc/nginx/sites-available/pleroma.conf
And finally, reload the Nginx web server:
systemctl reload nginx
Creating the SystemD Service
Like your web server, you will want to keep Pleroma running as an active service that you can start and stop, but, most importantly, a service that will start itself if you reboot the server.
Create the service with the command below:
cp /opt/pleroma/installation/pleroma.service /etc/systemd/system/pleroma.service
Start the service with this command:
systemctl start pleroma
Enable the service with the command below (this will make sure that the service will start itself in the event of a server disruption):
systemctl enable pleroma
Create An Admin User
You’re almost there. It’s time to switch back over to your Pleroma system user so that you can create an admin account to administer the site:
su -l pleroma
As the pleroma user, run this command to create an admin user for the site, replacing the username and [email protected] fields with your actual information:
./bin/pleroma_ctl user new username [email protected] --admin
This command will create a hyperlink you can open in your browser to set your admin password. Once your account is established, you can always update your password in the admin area of the site.
Enjoy Your New Pleroma Community
Well done! You have now successfully created your own social media network, running on your own private server. As the administrator of the site, you can take any actions necessary to run your site as you see fit. Feel free to post any questions or comment you may have below.
Special thanks to the maintainers at landchad.net, from which this installation recipe was adapted.
