Setting up Pixelfed on the Raspberry Pi

This guide will show you how to set up and self-host Pixelfed on your Raspberry Pi.

Pixelfed is a free and open-source image-sharing social network service that you can self-host on your Raspberry Pi. With its image sharing functionality it is very much a self-hosted alternative to Instagram.

It works similar to Mastodon in that it operates using the ActivityPub protocol. This allows multiple Pixelfed servers to talk with each other and create a much larger social network.

Please note that you must have a domain name that you can use for your Pixelfed installation. Additionally, you will need to be able to open ports 80 and 443 on your router to allow access to Pixelfed. This is required for Pixelfed to work properly and for the SSL certificates to be generated for your domain name.

Additionally, you must be running a 64-bit version of Raspberry Pi OS. This tutorial will not function on a 32-bit operating system.

Equipment

Below is a list of equipment we used when setting up Pixelfed on our Raspberry Pi.

Optional

Raspberry Pi Case ( Amazon | SunFounder )
USB Keyboard ( Amazon | SunFounder )
USB Mouse ( Amazon | SunFounder )
Monitor ( Amazon | SunFounder )

We last tested this tutorial on a Raspberry Pi 5 running the latest version of Raspberry Pi OS Bookworm 64-bit.

Self-hosting Pixelfed on your Raspberry Pi

In the following sections, we will walk you through how to self-host Pixelfed on your Raspberry Pi.

This process isn’t the longest, but it requires you to configure several things and be knowledgeable enough to open up ports. Also, as mentioned at the start of this guide, you must have a domain name pointed to your Pi’s public IP address.

A publicly accessible domain name is a key part of how Pixelfed and the Fediverse works.

Preparing your Raspberry Pi

1. Before installing and setting up Pixelfed on our Raspberry Pi, we will want to update it to ensure everything is up-to-date.

You can update the package list cache and upgrade any out-of-date packages using the following two commands.

sudo apt update
sudo apt upgrade

2. Once our Pi is updated, we will want to download and install the “git” package by running the command below.

This tool will allow us to clone the Pixelfed source code easily.

sudo apt install git

3. To make running Pixelfed an easier process, we will rely on a Docker container. This saves us the hassle of setting up and configuring multiple different services.

If you don’t have Docker installed on your Raspberry Pi, be sure to follow our guide.

https://pimylifeup.com/raspberry-pi-docker/

4. After installing Docker, we can create a folder to store Pixelfed and all its data. We will keep this software in the “/opt/pixelfed” directory.

To create this folder, use the mkdir command within your terminal.

sudo mkdir -p /opt/pixelfed/

5. Now that the directory has been created, use the cd command to change into it. The rest of this tutorial will expect you to be located in this folder.

cd /opt/pixelfed

Cloning Pixelfed to the Raspberry Pi

6. Our next step is to get our Raspberry Pi to clone the Pixelfed repository. Thanks to us installing Git earlier on in this tutorial, cloning the repository is as simple as running the command below.

Ensure that you keep the dot (.) at the end of the command. This dot is crucial as it tells Git to clone the Pixelfed code base to the current directory.

sudo git clone https://github.com/pixelfed/pixelfed .

7. Depending on your internet connection, the cloning process might take a few minutes.

Once it finishes, you will want to make a copy of the “.env.docker” file using the following command. We will edit the copied version of this file to configure Pixelfed.

sudo cp .env.docker .env

Configuring your Raspberry Pi Pixelfed Installation

8. We can now begin to configure Pixefed. We will only focus on the settings we must adjust to get Pixelfed running on the Raspberry Pi. You can find more information on configuring Pixelfed from their official documentation.

You can begin to modify the “.env” environment file by using the following command in the terminal.

sudo nano .env

Adjusting Settings

9. You will need to make several changes to this file. Each of these is required for a working installation of Pixelfed.

If you want to make finding these options easier, you can Nano’s search functionality by pressing CTRL + W.

Set the Pixelfed App Name

a. The first option you want to change is “APP_NAME“. This option lets you set a name for your Pixelfed installation. This can be anything you choose as long as it is within double quotes (" ").

APP_NAME=

For example, if we wanted to name our instance “PiMyLifeUp Pixelfed” we would use the following option.

APP_NAME="PiMyLifeUp Pixelfed"

Selecting your Domain Name

b. The next setting is “APP_DOMAIN“. This option must be set to the domain name you intend to use access your Pixelfed installation.

Ensure that this domain name is also pointed to your public IP address so that it can be resolved.

APP_DOMAIN="example.com"

For example, if we used the domain name “pixelfed.pimylifeup.com” we would change the option to look like the following.

APP_DOMAIN="pixelfed.pimylifeup.com"

Disabling Email Verification

c. Now, if you don’t intend to configure Pixelfed to use an SMTP server, you will want to disable email verification.

SMTP is outside the scope of this guide, so we will disable it. Find the option below within the “.env” file.

#ENFORCE_EMAIL_VERIFICATION="true"

Once you have found the above line, you must replace the hashtag from the front of the line and replace “true” with “false“.

ENFORCE_EMAIL_VERIFICATION="false"

Setting your Timezone

d. The next option you will want to configure is the time zone for the service. Find the following option within the file.

APP_TIMEZONE="UTC"

Replace “UTC” with a valid time zone identifier. You can find a list of TZ identifiers on Wikipedia. For this example, we will set ours to “Australia/Hobart“.

APP_TIMEZONE="Australia/Hobart"

Entering a Database Password

e. Now scroll through the file until you find the “DB_PASSWORD” setting. This setting is the password that Pixelfed will use to connect to its database server.

DB_PASSWORD=

After finding the option above, you will want to specify a long and secure password within double quotes.

DB_PASSWORD="REPLACEMEWITHASECUREPASSWORD"

Setting your Contact Email

f. The final option we must set for Pixelfed to work on our Raspberry Pi is the contact email. If we don’t change this, the service will fail during start-up.

INSTANCE_CONTACT_EMAIL="__CHANGE_ME__"

Replace “__CHANGE_ME__” with an email that you can easily be contacted on.

INSTANCE_CONTACT_EMAIL="pixelfed@pimylifeup.com

Saving your Configuration Changes

10. After editing the “.env” configuration file, you can save and quit by pressing CTRL + X, Y, and then ENTER.

Starting up Pixelfed on your Raspberry Pi

11. We are now finally at the point where we can start up Pixelfed on our Raspberry Pi.

To get Docker to build and start-up Pixelfed, you will want to run the following command within the terminal.

Be prepared to wait a while for the initial setup process to complete. Docker needs to download and set up several containers and then run all Pixelfeds start-up commands that prepare stuff such as the database.

docker compose up -d

Generating Pixelfed Passport Keys

12. Before logging in and using the Pixelfed web interface, we must get it to generate its “passport” keys.

Pixelfed uses these keys as part of its authentication system. We must begin interacting with the “web” container to generate these keys by running the command below.

docker compose exec web bash -it

13. Once you have entered the web container, use the command below to get the software to generate the required keys.

php artisan passport:keys

14. When your system has finished generating the required keys. You can quit out of the container by running the following command.

exit

Accessing the Pixelfed Web Interface

15. If everything has gone correctly, you should now be able to access the web interface for Pixelfed by going to your domain name in your favorite web interface.

https://<DOMAINNAME>

16. You should now be greeted by the following screen welcoming you to your Pixelfed installation.

What you will want to do now is create your own account by clicking the “Sign up” button in the top-right corner.

17. On this screen, fill out the information for your user (1.). Since we have email verification disabled, the email doesn’t necessarily have to be valid.

After filling out all the required information, click the “Register” button (2.).

18. You have successfully set up Pixelfed on your Raspberry Pi. Take some time to explore the web interface and familiarize yourself with how to post your images on the platform.

Changing your New User to be an Admin

19. Now that you have created your first Pixelfed user you will want to return to your Raspberry Pi to turn that user into an admin.

Once you are back on your Pi, change to the directory where we set up Pixelfed.

cd /opt/pixelfed

20. Our next step requires us to interact with the “web” Docker container directly.

We can launch bash within this container by running the following command.

docker compose exec web bash -it

21. Now that the Pixelfed web container is open on your Raspberry Pi, use the following command to elevate your user to admin.

Ensure that you replace “<USERNAME>” with the username you used when creating your user.

php artisan user:admin <USERNAME>

22. Before your user is given admin privileges, you will be asked whether you want to give the found user admin rights.

If you are happy to proceed, type in “yes” and then press the ENTER key.

Found username: pimylifeup

 Add admin privileges to this user? (yes/no) [no]: yes

If everything works correctly, you should see the following message.

Successfully changed permissions!

23. We are now done with our Web container and can exit using the “exit” command.

exit

24. Using your user, you should now have full access to the Admin dashboard. We recommend exploring and adjusting the settings available to you within this interface.

You can access this dashboard by going to the following URL. Ensure that you replace “<YOURDOMINAME>” with your domain name.

https://<YOURDOMAIN>/i/admin/dashboard

Turning Off User Sign Ups

25. By default, your installation of Pixelfed on your Raspberry Pi is set to allow any user to register.

To change this behavior, we must edit the ".env” file again by running the command below.

sudo nano .env

26. Once you have the ".env” file open in nano, look for the following option.

#OPEN_REGISTRATION="true"

After finding the “OPEN_REGISTRATION” option you will need to remove the hashtag from in front of it. Additionally, you must also change “true” to “false“.

OPEN_REGISTRATION="false"

27. After making this change, save and quit by pressing CTRL + X, Y, and then ENTER.

28. Since we changed our configuration, Pixelfed needs to update its config cache.

You can do that by using the following command in the terminal.

docker compose exec web php artisan config:cache

If the cache was updated successfully, you should see the following message.

   INFO  Configuration cached successfully.

29. Even though we turned off user registration through the “.env” file, we must also do so through the Pixelfed admin panel.

You can open this panel by going to the following URL. Remember you must replace “<YOURDOMAIN>” with the domain name you use for Pixelfed.

https://<YOURDOMAIN>/i/admin/settings

30. Once you are on the settings page, you should see an option labeled “Registration Status” (1.). You will want to change this option to “Filtered” or “Closed“.

After deciding what to do, click the “Save” button (2.).

Conclusion

Hopefully, by this stage, you will have successfully set up Pixelfed on your Raspberry Pi.

The Raspberry Pi is a great place to host your own Pixelfed installation. It is relatively cheap to keep running 24/7 and has enough processing power to deal with light traffic.

Please feel free to leave a comment below if you have had any issues with getting this software up and running on your Pi.

If you liked this project, we highly recommend exploring our many other Raspberry Pi projects.