Installing Mastodon on the Raspberry Pi

In this tutorial, we will be showing you how to install Mastodon on the Raspberry Pi.

Raspberry Pi Mastodon

Mastodon is a free and open-source software that allows you to self-host your own social network on your Raspberry Pi.

This software is a microblogging platform that is very much like Twitter However, unlike Twitter, it is possible to use Mastodon to run a private social network.

Please note that Mastodon is a relatively heavy piece of software. You will have the best experience using a Raspberry Pi 4 with at least 2GB of memory.

Additionally, you must be using a 64-bit operating system due to the newer release of PostgreSQL we will be utilizing.


Below is the equipment we used to set up Mastodon on our Raspberry Pi.



This tutorial was tested on a Raspberry PI 400 running the latest version of Raspberry Pi OS Buster 64-bit.

Before You Begin

Before you begin with Mastodon on your Raspberry Pi, you will need a few things for the best experience with this self-hosted social network.

  • A domain name to point toward your Raspberry Pi’s IP address. Mastodon requires a domain name to operate correctly. If you try to connect through a host that hasn’t been configured, it will block the connection.

    If you have a dynamic IP address, we have a guide on how to set up dynamic DNS on your Pi.

    To use Mastodon locally you can also specify a domain name like “pimylifeup.local” and modify the hosts file on your system to point that domain to your Pi’s local IP.

  • A publicly routable IP address and not one behind a CG-NAT. You will also need the ability to port forward ports 80 and 443 to your Raspberry Pi’s local IP.
  • You should also use a transactional mail service such as Sendgrid, Mailgun, or Amazon SES. While this is not required, it will help ensure emails sent by Mastodon are more likely to be recieved.

Preparing your Raspberry Pi to Run Mastodon

Before running the Mastodon software on the Raspberry Pi, we must install all the software required to run it.

In the following sections, we will walk you through setting up everything required to run Mastodon.

Installing the Software Needed for Setup

1. Before installing the software needed to run Mastodon, we should perform an update.

Update the package list cache and any out-of-date packages using the following two commands.

2. Once the update completes, we can install any software we require to set up the various pieces of software Mastodon relies on for our Raspberry Pi.

Use the command below to install almost everything we need to run Mastodon. Even though we are installing a lot of software, there are a few more we will still need to set up.

Creating a User for Mastodon on your Raspberry Pi

3. With the base software installed, we can create a user that Mastodon will run under on our Raspberry Pi.

We can create this user by using the useradd command, as shown below. This user will have the name “mastodon“.

By using the “-m” option, this command will create a home directory while making the user.

Installing NodeJS

4. The Mastodon social network relies on the Node.JS runtime for its streaming functionality.

Before continuing any further, follow our guide on installing Node.JS onto the Raspberry Pi.

5. Once you have Node.JS installed on your device, you may safely continue with this tutorial.

Setting up PostgreSQL for Mastodon

6. PostgreSQL is the next piece of software we need to set up on our Raspberry Pi for Mastodon.

Mastodon will use PostgreSQL to store all of the data from your self-hosted social network.

We will need to add the official repository to install the latest version of PostgreSQL.

Start by saving the GPG key for the Postgre repository to your device by using the following command.

7. Now that we have added the GPG key for PostgreSQL, we can add the repository to our sources list by using the command below.

8. As we changed the available repositories, we need to update the package list cache again.

Update the package list cache by running the following command.

9. We can finally install PostgreSQL to our Raspberry Pi for Mastodon to utilize.

To install this database software, run the command below in the terminal.

Creating a PostgreSQL User for Mastodon on the Raspberry Pi

10. With PostgreSQL now installed on the Raspberry Pi, our next step is creating a new SQL “user” for Mastodon to use when connecting to the database.

To be able to create this user, we will need to use the following command to launch the PostgreSQL CLI.

11. Since PostgreSQL uses the “ident” plugin by default, we only need to ensure the user has the same name as the user created earlier.

Use the command below within the CLI to create a Postgre user named “mastodon“.

Using “CREATEDB” at the end of the line, we are telling Postgres that this new user can create databases. This permission is required for Mastodon to properly install intself.

12. With the user now created, you can quit out of the CLI by typing in the following.

Enabling Yarn

13. To build and run Mastodon on our Raspberry Pi, we will need to enable Yarn. Yarn is a package manager for Node.JS.

You can enable Yarn on your system by using the following two commands.

Installing Ruby for Mastodon on the Raspberry Pi

14. We can finally install Ruby on your Raspberry Pi. Mastodon uses Ruby to generate its web pages and the REST API.

To install Ruby, we need to change to the Mastodon user by running the following command.

15. To install and set up Ruby on our Raspberry Pi, we will use a tool called “rbenv“. This tool allows us to set up the Ruby environment for our Mastodon user easily.

Clone the code repository for the “rbenv” utility using the below command.

16. We also need to clone the “ruby-build” plugin for the “rbenv” tool.

You can clone this tool by running the command below within the terminal.

17. Now run the following command to adjust the “.bashrc” file. Commands within this file will be executed when the bash terminal starts.

The command we add will initialize the “rbenv” utility used to set up the Ruby environment.

18. To ensure the changes we made are available immediately, use the command below.

19. We can now begin installing Ruby 3.0.4 to our Raspberry Pi by using the command below in the terminal.

Installing Ruby like this ensures we have the exact version Mastodon expects on our Raspberry Pi.

Please note that the compilation process can take some time.

20. Once Ruby finishes installing, our next step is to declare it as the global version of Ruby to use.

To do this, you only need to use the following command.

21. Finally, we need to utilize the Ruby package manager to install “bundler“.

You can install this package by using “gem” as shown below.

Installing Mastodon on the Raspberry Pi

Now that we have prepared everything, we need to run Mastodon on our Raspberry Pi, we can finally move on to installing this social network software.

Over the following sections, you will learn how to compile and install Mastodon on your device.

Cloning the Mastodon Repository to your Raspberry Pi

1. Before we continue, you must ensure that you are still running as the Mastodon user.

If you don’t see you shell session starting with “mastodon@” you will need to run the following command.

2. Once you have switched to the “mastodon” user, you can change to the home directory using the cd command.

3. Now that we are in the home directory, we can clone the Mastodon code base to our Raspberry Pi.

To clone the repository, you must use the command below.

4. After cloning the Mastodon repository, we will want to use the cd command again to change to the “live” directory.

5. We can now use the “git checkout” command to change to the latest stable “tagged” release of Mastodon.

Installing Mastodon and its Dependancies

6. Our first step is setting the “deployment” option to “true” using the following command.

7. We then utilize the “bundle” tool to exclude packages that areused purely for development or test purposes.

8. Finally, we can use the bundle command again to install all of the Ruby dependencies for Mastodon to our Raspberry Pi.

Using the “-j” option, we can tell the package manager to use as many CPU cores as we have.

9. Once the Ruby packages have been installed, we can use yarn to install the Node.JS dependencies for Mastodon.

Install these dependencies by utilizing the following command.

Configuring Mastodon for your Raspberry Pi

10. We can finally begin the final process of configuring Mastodon itself on your Raspberry Pi.

To begin this process, run the following command within the command line.

General Settings

11. You will first be prompted to enter the domain name for your Mastodon instance. It is crucial to set this to the exact domain name you plan on using. If you connect through any other domain, the connection will be blocked.

For our example, we will be using ““.

12. Next, you will be asked if you want to run your Raspberry Pi’s Mastodon instance in single-user mode. Single-user mode means that there will only be a singular public profile.

Type in “Y” if you only want this Mastodon server for yourself.

Alternatively, press the “N” key and then the ENTER key to have multiple users.

13. You will be asked if you are running Mastodon as a docker container.

Since we aren’t using Docker to run Mastodon, press the “N” key and then the ENTER key.

PostgreSQL Settings

14. The following prompt will ask you to set the host for PostgreSQL.

The default value is “/var/run/postgresql” so you can safely press the ENTER key.

15. Next, you will be prompted to specify the post for PostgreSQL.

Again, the default value is fine so press the ENTER key.

16. The following option will ask you for the name of the Mastodon database.

To continue, you can safely accept the default value and press the ENTER key.

17. You will next have the chance to specify the PostgreSQL to utilize for Mastodon.

If you have been following this tutorial, you can safely use the default value and press the ENTER key.

18. The final setting we need to configure for PostgreSQL is its password.

Since we created our PostgreSQL user without one, it will default to using “ident” for authentication. As long as the user running Mastodon and the PostgreSQL user matches, we will be able to access the database.

Leave the field empty, and then press the ENTER key to proceed.

Redis Settings

19. Your next step is to set the host for your Redis server.

Since we installed this locally, we can use the default option by pressing the ENTER key.

20. We then need to set the port used when connecting to the Redis server.

As we haven’t changed the default port in this guide, press the ENTER key to use the default value.

21. The final option we need to set is the password.

With the way we have set up Redis locally, press the ENTER key without specifying a password.

Cloud Storage Settings

22. You will now get the chance to configure Mastodon to use cloud storage for uploaded files.

As this isn’t something we plan on covering in this guide, we will type in “N” and press ENTER.

If you want to use Cloud storage such as AWS, you will want to type “Y” and follow the prompts.

SMTP Options

23. Next, you will be prompted whether you want to send emails from your Raspberry Pi for Mastodon. This is not recommended, as email providers such as Outlook and Gmail will likely block your server.

Instead, you should use a transactional mail service such as Sendgrid, Mailgun, or Amazon SES.

If you want to keep your setup simple and aren’t worried about the deliverability of your emails, you can type “Y” and press the ENTER key.

Otherwise, to use a transactional email service, type “N” and press ENTER.

If you choose to send emails directly from your Raspberry Pi, skip to step 30.

24. You will now need to know the details of the SMTP service that you will be using.

The first detail you need to know is the IP or domain name for the SMTP server. For example, if you were using Mailgun, you would use ““.

25. We will next need to set the port to send the SMTP message over. This port differs from service to service.

For example, using the Mailgun service, you would use port “587“.

26. To be able to send any message over SMTP you will need a username and password.

First, you will be prompted to enter the password for your SMTP connection. Your mail transaction service provides these details.

27. After entering the username to use for the SMTP connection you will also need to enter the password.

28. We can also control the type of authentication that is used for SMTP.

The default value for this option is “plain“. Make sure you check your provider for the correct value.

29. Next you will need to specify the SMTP verify mode. If you are unsure what to pick here, you can choose the “none” option.

30. You can now choose the email address that your Raspberry Pi will use to send Mastodon’s emails through.

To use your own, you need to use the following format: “NAME “. For example, if we were setting this up for our website it would be written like “PiMyLifeUP “.

You can also use the default value by pressing the ENTER key.

31. Finally, you will be asked whether you want to test the configuration nail.

To test whether all of your settings worked, press “Y“, then press the ENTER key.

Finishing the Configuration

32. We can finally finish configuring Mastodon on your Raspberry Pi.

You will now be asked whether you want to save the configuration to the “.env.production” file.

To save the changes, type in “Y” and then press the ENTER key.

33. Mastodon will now want to set up the database and install all of its data.

Type in “y” and press ENTER to have Mastodon create its database.

34. The final thing you will be asked during configuration is whether you want your Raspberry PI to compile Mastodon’s CSS and JS assets.

As we need these to be compiled, type in “Y” and press the ENTER key.

Creating an Admin Account

35. Before the configuration script ends, you will be asked if you want to create a Mastodon admin account.

Now is the best time to create this account, so type in “y” and press ENTER to continue.

36. You will now be asked to specify a username for your admin account.

You can name this user whatever you would like. Type in the username, then press the ENTER key.

37. Next, you can specify an email address to be assigned to your admin account. This email address is what you will use to login to your admin account.

Ensure this is an email address that you can be reached through as its utilized.

38. After creating your account, it will automatically generate a password. Save this password, as you will use it to log in to your account.

Obtaining an SSL Certificate for your Mastodon Server

39. At this point, we are finally done with the Mastodon user.

Return to your normal user by running the following command.

40. To help keep your Raspberry Pi’s Mastodon connection secure, you should run it under HTTPS. For this to work, you will need to generate a certificate for your domain name.

Thanks to installing certbot earlier in this guide, we can request a certificate from Lets Encrypt by running the following command.

Ensure that you replace “" with the domain name that you are using.

During certificate generation, you will be prompted with a series of questions.

Configuring NGINX for Mastodon on your Raspberry Pi

41. Let us now copy the example Nginx config from the Mastodon directory to the “sites-available” directory.

Use the command below to perform this action.

42. We need to create a symbolic link between the mastodon config file in the “sites-available” directory and the “sites-enabled” directory.

You can create this symbolic link by using the following command.

43. Our next step is to edit your Raspberry Pi’s Mastodon Nginx config file so that it uses your domain name.

Begin editing the config file using the nano text editor by using the command shown below.

44. Within this file, you will need to find and change the following line. There will be two occurrences of this within the file that will need to be swapped out.

These lines should be near the top of each “server {” block.

Replace this with the domain name that you are using. For example, we used ““.

45. Our next step is to configure the Nginx file to point to the SSL certificate you got earlier

Find the following two lines within the file.

Once you have found both of these lines, you need to remove the hashtag in front of them. You also need to change “” to your domain name.

For example, using our domain name of ““, the lines would look like the following.

46. Once you have made the changes, you can save and quit by pressing CTRL + X, followed by Y, then the ENTER key.

47. As we have made changes to Nginx’s configuration, we will need to perform a reload by running the following command.

Setting up a Service File for Mastodon on the Raspberry Pi

48. The final task we need to do is set up a service that will manage running Mastodon on our Raspberry Pi.

Luckily, these service files come bundled with the Maston code base.

Copy the systemd services to the relevant directory using the cp command shown below.

59. With the service files copied, we can now enable and start them all by using the following command.

The “--now” option tells systemd to start up Mastodon

60. At this point, Mastodon is now up and running on your Raspberry Pi and will be fully accessible through your chosen domain name.

Connecting to your Raspberry Pi Mastodon Server

At this point, you will have finally gotten Mastodon installed on your Raspberry Pi and will be ready to access it.

1. To access Mastodon, you must go to the domain name you configured earlier.

For our example, we will go to the following address in our web browser.

2. You should be greeted by Mastodon’s login screen. Using the form in the top-right, you can log in using the administrator account you created during setup.

Login to Mastodon Admin Account on Raspberry Pi

3. You are now logged into your Mastodon account. You can start now start “tooting” on your profile.

Alternatively, since you are the admin, you can also head to the preferences screen and utilize the administration panel.

Open Preferences in right-hand sidebar

4. Once you are on the preferences screen, look at the left-hand sidebar to find the “Administration” option and click it.

Open administration panel

5. Within the administration screen, you can control many aspects of your self-hosted Mastodon installation.

Take your time to learn about all of the tools available within this screen, as it will help you manage your community.

Raspberry Pi Mastodon Admin Dashboard


At this point in the guide, you should hopefully have Mastodon installed and running on your Raspberry Pi.

Mastodon is a self-hosted social network that uses the microblogging style that Twitter popularised.

Please comment below if you have had issues getting Mastodon to run on your Pi.

If you liked this guide, check out our many other Raspberry Pi projects.

Leave a Reply

Your email address will not be published. Required fields are marked *

This site uses Akismet to reduce spam. Learn how your comment data is processed.

Server Status

Aradippou Chat Larnaca Nicosia

Chat Links

Official Links.


Alternative Mirror Links.

1. KiwiIRC 1.
2. KiwiIRC 2.

Other Web Clients.

1. IrcCloud.

Recent Posts

Related Posts:


Follow me on Mastodon

Super Club Radio

Mighty Deals


CyIRC Tweets