by 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.
Recommended
- Raspberry Pi Amazon
- Micro SD Card Amazon
- Power Supply Amazon
- Domain Name Namecheap
- Ethernet Cable Amazon or Wi-Fi Amazon
Optional
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 upgradeCopy2. 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 gitCopy3. 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/Copy5. 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/pixelfedCopyCloning 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 .Copy7. 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 .envCopyConfiguring 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 .envCopyAdjusting 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=CopyFor example, if we wanted to name our instance “PiMyLifeUp Pixelfed” we would use the following option.
APP_NAME="PiMyLifeUp Pixelfed"CopySelecting 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"CopyFor 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"CopyDisabling 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"CopyOnce 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"CopySetting 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"CopyReplace “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=CopyAfter finding the option above, you will want to specify a long and secure password within double quotes.
DB_PASSWORD="REPLACEMEWITHASECUREPASSWORD"CopySetting 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__"CopyReplace “__CHANGE_ME__” with an email that you can easily be contacted on.
INSTANCE_CONTACT_EMAIL="pixelfed@pimylifeup.comCopySaving 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 -dCopyGenerating 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 -itCopy13. Once you have entered the web container, use the command below to get the software to generate the required keys.
php artisan passport:keysCopy14. When your system has finished generating the required keys. You can quit out of the container by running the following command.
exitCopyAccessing 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/pixelfedCopy20. 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 -itCopy21. 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>Copy22. 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]: yesIf 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.
exitCopy24. 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/dashboardTurning 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 .envCopy26. Once you have the ".env” file open in nano, look for the following option.
#OPEN_REGISTRATION="true"CopyAfter 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"Copy27. 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:cacheCopyIf 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/settings30. 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.
Hello. I’m following along up until point 15. Do I need to have a reverse proxy installed, like nginx, for the domain to point to the Pixelfed docker container?
I use Cloudflare tunnels, have set up the routing there, have an SSL certificate installed, etc. Normally (eg. for Mastodon) I would then use nginx to point the domain to the correct root, but there is no mention of needing that in this guide. Does Docker handle the routing?
Thanks in advance.
(Big fan of your guides!)
Hi Rob,
The Docker Compose stack that we are using for Pixelfed (the official one) actually already has a Proxy included It will handle the whole process of fetching an SSL certificate etc for you but it does force you to have to be able to open ports 80 and 443.
However, if you are using Cloudflare tunnel there is a good chance this functionality might become more of a pain (One heads up with Cloudflare tunnels is that there is a limit on the upload size that can prove to be a bit of a hinderance).
You can disable the Proxy parts of the Docker stack by modifying the “
.env” file and finding the following line.You would this change that to something like “disabled” to stop the container from starting up the proxy.
You would then set up your Cloudflare tunnel to route Pixelfed running on port 8080 to your desired domain name.
Hope that helps, I can try and explain things a bit better if you need.
Kind regards,
Emmet
Update: I tried following the above instructions with nginx already installed and it failed at point 11 (failed to bind host port, address already in use) so it seems fair to assume that the domain routing is handled by Docker and a separate reverse proxy is not needed. Hence you didn’t put this in your guide. This means I’m back to being stuck at point 15. Is having the APP_DOMAIN in the .env file all that is required for serving the web front end? Thanks!
Hi Rob,
Hmm I didn’t think about this when I responded to you last night. But there is a good chance the default port that Pixelfed uses is already in use since port 8080 is quite common.
What you willl want to do next is open the “.env” file for editing again but this time look for the following line.