Pixelfed is a free and open-source image sharing social network service. It is decentralized, therefore user data is not stored on a central server, unlike other platforms. The fediverse is a large network of platforms that all speak a common language. Imagine if you could reply to Instagram posts from Twitter, or interact with your favorite Medium blogs from Facebook – federated alternatives like Pixelfed, Mastodon and WriteFreely enable you to do these types of things. In this step by step guide I will show you how to install Pixelfed on your UGREEN NAS using Docker & Portainer.

💡Note: This guide works perfectly with the latest Pixelfed v0.12.6 release.

💡Note: Check out my guide on how to Install Pixelfed on Your Synology NAS.

• STEP 1

Please Support My work by Making a Donation.

• STEP 2

Install Portainer using my step by step guide. If you already have Portainer installed on your UGREEN NAS, skip this STEP. Attention: Make sure you have installed the latest Portainer version.

• STEP 3

⚠️Mandatory: Enable HTTPS on your UGREEN NAS.

• STEP 4

Create a new hostname on the noip website using your noip account. For example, I have created mariuspixel as Host and I use the free ddns.net domain. In the IP Address area, type in your own IPV4 IP address from your ISP, then click Create. Follow the instructions in the image below.

• STEP 5

Go to Files and open the docker folder. Inside the docker folder, create one new folder and name it pixelfed. Follow the instructions in the image below.
Note: Be careful to enter only lowercase, not uppercase letters.

• STEP 6

Now create three new folders inside the pixelfed folder that you have previously created at STEP 5 and name them db, redis, storage. Follow the instructions in the image below.
Note: Be careful to enter only lowercase, not uppercase letters.

• STEP 7

Log into Portainer using your username and password. On the left sidebar in Portainer, click on Home then Live connect. Follow the instructions in the image below.

On the left sidebar in Portainer, click on Stacks then + Add stack. Follow the instructions in the image below.

• STEP 8

In the Name field type in pixelfed. Follow the instructions in the image below.

Note: Copy Paste the code below in the Portainer Stacks Web editor.

services:
  pixelfed-redis:
    image: redis
    container_name: Pixelfed-REDIS
    hostname: pixelfed-redis
    security_opt:
      - no-new-privileges:true
    healthcheck:
      test: ["CMD-SHELL", "redis-cli ping || exit 1"]
    user: 999:10
    environment:
       TZ: Europe/Bucharest
    volumes:
      - /volume1/docker/pixelfed/redis:/data:rw
    restart: on-failure:5
    
  pixelfed-db:
    image: postgres:17
    container_name: Pixelfed-DB
    hostname: pixelfed-db
    security_opt:
      - no-new-privileges:true
    healthcheck:
      test: ["CMD", "pg_isready", "-q", "-d", "pixelfeddb", "-U", "pixelfeduser"]
      timeout: 45s
      interval: 10s
      retries: 10
    env_file:
      - stack.env
    environment:
       TZ: Europe/Bucharest
    volumes:
      - /volume1/docker/pixelfed/db:/var/lib/postgresql/data:rw
    restart: on-failure:5

  pixelfed-web:
    image: quay.io/zknt/pixelfed:latest
    container_name: Pixelfed-WEB
    hostname: pixelfed-web
    security_opt:
      - no-new-privileges:true
    healthcheck:
      test: stat /etc/passwd || exit 1
    env_file:
      - stack.env
    volumes:
      - /volume1/docker/pixelfed/storage:/var/www/storage:rw
      - app-bootstrap:/var/www/bootstrap
    ports:
      - 9750:80
    depends_on:
      pixelfed-db:
        condition: service_started
      pixelfed-redis:
        condition: service_healthy
    restart: on-failure:5

  pixelfed-worker:
    image: quay.io/zknt/pixelfed:latest
    container_name: Pixelfed-WORKER
    hostname: pixelfed-worker
    security_opt:
      - no-new-privileges:true
    healthcheck:
      test: php artisan horizon:status | grep running
      interval: 60s
      timeout: 5s
      retries: 1
    env_file:
      - stack.env
    volumes:
      - /volume1/docker/pixelfed/storage:/var/www/storage:rw
      - app-bootstrap:/var/www/bootstrap
    entrypoint: /worker-entrypoint.sh
    depends_on:
      pixelfed-db:
        condition: service_started
      pixelfed-redis:
        condition: service_healthy
      pixelfed-web:
        condition: service_healthy
    restart: on-failure:5
volumes:
  app-bootstrap:

Note: Before you paste the code above in the Web editor area below, change the value numbers for user with your own UID and GID values. (Follow my step by step guide on how to do this.) 999 is my personal UID value and 10 is my personal GID value. You have to type in your own values.
Note: Before you paste the code above in the Web editor area below, change the value for TZ. (Select your current Time Zone from this list.)

• STEP 9

Click the Upload button after Web editor. Download the stack.env file by clicking the blue link below and then upload it from your computer in the “Load variables from .env files“. Follow the instructions in the image below. 🔒Note: Support my work to unlock the password. You can use this password to download any file on mariushosting forever!

👉🏻Download stack.env file

• STEP 10

Note: On the Environment variables change the value for APP_KEY. (Generate your own free base64 APP KEY.)
Note: On the Environment variables change the value for APP_TIMEZONE and add your own TIMEZONE.  (Select your current Time Zone from this list.)
Note: On the Environment variables change the value for APP_URL. Type in your own NO IP DDNS that you have previously created at STEP 4 with https at the beginning.
Note: On the Environment variables change the value for APP_DOMAIN. Type in your own NO IP DDNS that you have previously created at STEP 4 without https at the beginning.
Note: On the Environment variables change the value for ADMIN_DOMAIN. Type in your own NO IP DDNS that you have previously created at STEP 4 without https at the beginning.
Note: On the Environment variables change the value for SESSION_DOMAIN. Type in your own NO IP DDNS that you have previously created at STEP 4 without https at the beginning.
⚠️Warning: Do NOT change any of the other values.

• STEP 11

After you make the changes, click the Web editor button. Follow the instructions in the image below.

• STEP 12

Scroll down on the page until you see a button named Deploy the stack. Click on it. Follow the instructions in the image below. The installation process can take up to a few minutes. It will depend on your Internet speed connection.

• STEP 13

If everything goes right, you will see the following message at the top right of your screen: “Success Stack successfully deployed“.

• STEP 14

Open your Nginx Proxy Manager container that you have previously installed at STEP 3. Click Add Proxy Host. A new pop up window will open. Add the following details:

Domain Names: Type in your own noip domain name that you have previously created at STEP 4.
Scheme: http
Forward Hostname/IP: Type in the local NAS IP of your UGREEN NAS.
Forward Port: Type in the Pixelfed local Port that is 9750
Check Block Common Exploits
Check Websockets Support
Click the SSL tab. Follow the instructions in the image below.

• STEP 15

After you click the SSL tab, add the following details:

SSL Certificate: Request a new SSL Certificate
Check: Force SSL
Check: HSTS Enabled
Check: HTTP/2 Support
Email Address for Let’s Encrypt: Type in your own Email Address.
Check: I Agree to the Let’s Encrypt Terms of Service.
Click Save. Follow the instructions in the image below.

• STEP 16

In the Proxy Hosts area, if everything goes right, you will see that your pixelfed hostname has been generated. Click on it. Follow the instructions in the image below.

• STEP 17

🟢Please Support My work by Making a Donation. Almost 99,9% of the people that install something using my guides forget to support my work, or just ignore STEP 1. I’ve been very honest about this aspect of my work since the beginning: I don’t run any ADS, I don’t require subscriptions, paid or otherwise, I don’t collect IPs, emails, and I don’t have any referral links from Amazon or other merchants. I also don’t have any POP-UPs or COOKIES. I have repeatedly been told over the years how much I have contributed to the community. It’s something I love doing and have been honest about my passion since the beginning. But I also Need The Community to Support me Back to be able to continue doing this work.

• STEP 18

Now open your browser and type in your HTTPS/SSL certificate like this https://pixelfed.ddns.net In my case it’s https://mariuspixel.ddns.net If everything goes right, you will see the Pixelfed Login page. Click Sign up. Follow the instructions in the image below.

• STEP 19

Type in your own Name, Username and Password. Confirm your Password then click Register. Follow the instructions in the image below.

• STEP 20

Your main Pixelfed page will look like this.

• STEP 21

Give Administrator rights to the username you have previously created at STEP 19. On the left sidebar in Portainer, click Containers. Identify your Pixelfed-WEB instance, then click on the little terminal icon. Follow the instructions in the image below.

• STEP 22

After you click on the little terminal icon at STEP 21, a new page will open. Click Connect. Follow the instructions in the image below.

• STEP 23

After you click Connect at STEP 22, a Console will open. Copy paste the code below and confirm by pressing Enter on your keyboard to start the admin rights process. Follow the instructions in the image below.

php artisan user:admin mariushosting

Note: Before you type in the code, remember to change the username with the one that you have previously chosen at STEP 19. Follow the instructions in the image below.

• STEP 24

After you press Enter on your Keyboard at STEP 23, you will get a message that says: “Add admin privileges to this user?” Type in yes and confirm by pressing Enter on your keyboard. Follow the instructions in the image below.

• STEP 25

After a few seconds you will get a message in the terminal that says: “Successfully changed permissions!“. Go straight to STEP 26.

• STEP 26

On the left sidebar in Portainer, click Containers. Identify your Pixelfed-WEB instance, select it then click Restart. Follow the instructions in the image below.

• STEP 27

🟢Please Support My work by Making a Donation. Almost 99,9% of the people that install something using my guides forget to support my work, or just ignore STEP 1. I’ve been very honest about this aspect of my work since the beginning: I don’t run any ADS, I don’t require subscriptions, paid or otherwise, I don’t collect IPs, emails, and I don’t have any referral links from Amazon or other merchants. I also don’t have any POP-UPs or COOKIES. I have repeatedly been told over the years how much I have contributed to the community. It’s something I love doing and have been honest about my passion since the beginning. But I also Need The Community to Support me Back to be able to continue doing this work.

• STEP 28

Now open your browser and type in your HTTPS/SSL certificate like this https://pixelfed.ddns.net In my case it’s https://mariuspixel.ddns.net If everything goes right, you will see the Pixelfed Login page. Click Login. Follow the instructions in the images below.

Type in your own Email and Password that you have previously created at STEP 19, then click Login. Follow the instructions in the image below.

• STEP 29

At the top right of the page, under user profile, click Admin Dashboard. Follow the instructions in the image below.

• STEP 30

Type in your own Password that you have previously created at STEP 19, then click Confirm Password. Follow the instructions in the image below.

• STEP 31

On the left sidebar, click Diagnostics. As you can see, the instance actor cache is set to false. Follow the next step to fix it.

• STEP 32

Open a new browser page, then type in your own NO IP DDNS followed by /i/actor

https://pixelfed.ddns.net/i/actor

• STEP 33

Refresh the Diagnostics page. As you can see, the instance actor cache is set to true.

• STEP 34

Your Admin Dashboard at a Glance! For extra admin Settings, follow STEP 35 further down. Follow the instructions in the image below.

• STEP 35

In the Pixelfed dashboard under your profile on the right click Appearance. Follow the instructions in the image below.

• STEP 36

Select Dark Mode theme to switch to dark mode. Follow the instructions in the image below.

• STEP 37

Your Dark Mode theme will look like this.

• STEP 38

If you want to add more extra Admin Settings, go to Portainer then click Stacks. Click on pixelfed. Follow the instructions in the image below.

• STEP 39

Click on the Editor tab then scroll down the page a little bit. Click Environment variables. Follow the instructions in the image below.

• STEP 40

Change the values for ENABLE_CONFIG_CACHE and CUSTOM_EMOJI from false to true then scroll down the page until you find the Update the stack button. Follow the instructions in the image below.

• STEP 41

Click Update the stack. Follow the instructions in the image below.

• STEP 42

After you click Update the stack at STEP 41, a new pop up window will open. Click Update. Follow the instructions in the image below.

• STEP 43

Restart all four containers in Portainer. Note: Read the full Pixelfed documentation.

Enjoy Pixelfed on your UGREEEN NAS!

🆘TROUBLESHOOTING

⚠️Fix: If you experience permissions issues and your container doesn’t start, just change the following line in the compose stack at STEP 8 

user: 999:10
with
user: 0:0
Then update the stack.

🆙Note/Update/Container: How to Update Your Docker Containers on UGREEN NAS Using Portainer.
🐳Note: How to Create Docker Shortcuts on Desktop.
🆕Note: How to Update Portainer to the latest version.

This post was updated on Thursday / September 18th, 2025 at 11:44 PM