I've seen some people ask for help setting up Pixelfed. I spent a few days trying to get it working. This is my first guide so please let me know if something needs to be changed or clarified. You will need a database (mysql or mariadb), redis, a reverse proxy (swag in this case), and the compose.manager plugin.

 

-------------------------------------------------------

Database Setup

-------------------------------------------------------

Pixelfed only supports mysql. I am using mariadb which seems to be working but it's not supported so your mileage may vary. If you feel more comfortable using mysql install it instead of mariadb and modify the .env changes we'll do later to match

 

• Search CA for "mariadb" install the container from linuxserver's repository

• in the setup create a mysql root password, mysql database, mysql user, and mysql password. You will need the database name, user, and mysql password for later.

 

-------------------------------------------------------

redis Setup

-------------------------------------------------------

• Search CA for "redis " install the container from jj9887's repository

• set an a port number that is not being used by another service and click apply to install

 

-------------------------------------------------------

pixelfed container setup

-------------------------------------------------------

• Search CA for "Docker Compose Manager " install the container from dcflachs's repository

•  Return to the docker tab. At the bottom click the new "ADD NEW STACK'' button

•  Create a name for your new docker compose stack I used "pixelfed". Click the advanced dropdown arrow and set a directory for the compose stack, this is where the "appdata" will be downloaded. I used "/mnt/user/appdata/pixelfed"

• Click the small gear icon next to the new stack and click "edit stack" then "compose file".

• paste the following docker compose file into the text box that appears and click "save changes"

 

services:
  web:
    image: "${DOCKER_APP_IMAGE}:${DOCKER_APP_TAG}"
    container_name: "${DOCKER_ALL_CONTAINER_NAME_PREFIX}-web"
    restart: unless-stopped
    profiles:
      - ${DOCKER_WEB_PROFILE:-}
    build:
      target: ${DOCKER_APP_RUNTIME}-runtime
      cache_from:
        - "type=registry,ref=${DOCKER_APP_IMAGE}-cache:${DOCKER_APP_TAG}"
      args:
        APT_PACKAGES_EXTRA: "${DOCKER_APP_APT_PACKAGES_EXTRA:-}"
        BUILD_FRONTEND: "${DOCKER_APP_BUILD_FRONTEND:-0}"
        PHP_BASE_TYPE: "${DOCKER_APP_BASE_TYPE}"
        PHP_DEBIAN_RELEASE: "${DOCKER_APP_DEBIAN_RELEASE}"
        PHP_EXTENSIONS_EXTRA: "${DOCKER_APP_PHP_EXTENSIONS_EXTRA:-}"
        PHP_PECL_EXTENSIONS_EXTRA: "${DOCKER_APP_PHP_PECL_EXTENSIONS_EXTRA:-}"
        PHP_VERSION: "${DOCKER_APP_PHP_VERSION:?error}"
    environment:
      # Used by Pixelfed Docker init script
      DOCKER_SERVICE_NAME: "web"
      DOCKER_APP_ENTRYPOINT_DEBUG: ${DOCKER_APP_ENTRYPOINT_DEBUG:-0}
      ENTRYPOINT_SKIP_SCRIPTS: ${ENTRYPOINT_SKIP_SCRIPTS:-}
      # Used by [proxy] service
      LETSENCRYPT_HOST: "${DOCKER_PROXY_LETSENCRYPT_HOST:?error}"
      LETSENCRYPT_EMAIL: "${DOCKER_PROXY_LETSENCRYPT_EMAIL:?error}"
      LETSENCRYPT_TEST: "${DOCKER_PROXY_LETSENCRYPT_TEST:-}"
      VIRTUAL_HOST: "${APP_DOMAIN}"
      VIRTUAL_PORT: "80"
    volumes:
      - "./.env:/var/www/.env"
      - "${DOCKER_ALL_HOST_CONFIG_ROOT_PATH}/proxy/conf.d:/shared/proxy/conf.d"
      - "${DOCKER_APP_HOST_CACHE_PATH}:/var/www/bootstrap/cache"
      - "${DOCKER_APP_HOST_OVERRIDES_PATH}:/docker/overrides:ro"
      - "${DOCKER_APP_HOST_STORAGE_PATH}:/var/www/storage"
    labels:
      com.github.nginx-proxy.nginx-proxy.keepalive: 30
      com.github.nginx-proxy.nginx-proxy.http2.enable: true
      com.github.nginx-proxy.nginx-proxy.http3.enable: true
    ports:
      - "${DOCKER_WEB_PORT_EXTERNAL_HTTP}:80"
    healthcheck:
      test: 'curl --header "Host: ${APP_DOMAIN}" --fail http://localhost/api/service/health-check'
      interval: "${DOCKER_WEB_HEALTHCHECK_INTERVAL}"
      retries: 2
      timeout: 5s

  worker:
    image: "${DOCKER_APP_IMAGE}:${DOCKER_APP_TAG}"
    container_name: "${DOCKER_ALL_CONTAINER_NAME_PREFIX}-worker"
    command: gosu www-data php artisan horizon
    restart: unless-stopped
    stop_signal: SIGTERM
    profiles:
      - ${DOCKER_WORKER_PROFILE:-}
    build:
      target: ${DOCKER_APP_RUNTIME}-runtime
      cache_from:
        - "type=registry,ref=${DOCKER_APP_IMAGE}-cache:${DOCKER_APP_TAG}"
      args:
        APT_PACKAGES_EXTRA: "${DOCKER_APP_APT_PACKAGES_EXTRA:-}"
        BUILD_FRONTEND: "${DOCKER_APP_BUILD_FRONTEND:-0}"
        PHP_BASE_TYPE: "${DOCKER_APP_BASE_TYPE}"
        PHP_DEBIAN_RELEASE: "${DOCKER_APP_DEBIAN_RELEASE}"
        PHP_EXTENSIONS_EXTRA: "${DOCKER_APP_PHP_EXTENSIONS_EXTRA:-}"
        PHP_PECL_EXTENSIONS_EXTRA: "${DOCKER_APP_PHP_PECL_EXTENSIONS_EXTRA:-}"
        PHP_VERSION: "${DOCKER_APP_PHP_VERSION:?error}"
    environment:
      # Used by Pixelfed Docker init script
      DOCKER_SERVICE_NAME: "worker"
      DOCKER_APP_ENTRYPOINT_DEBUG: ${DOCKER_APP_ENTRYPOINT_DEBUG:-0}
      ENTRYPOINT_SKIP_SCRIPTS: ${ENTRYPOINT_SKIP_SCRIPTS:-}
    volumes:
      - "./.env:/var/www/.env"
      - "${DOCKER_ALL_HOST_CONFIG_ROOT_PATH}/proxy/conf.d:/shared/proxy/conf.d"
      - "${DOCKER_APP_HOST_CACHE_PATH}:/var/www/bootstrap/cache"
      - "${DOCKER_APP_HOST_OVERRIDES_PATH}:/docker/overrides:ro"
      - "${DOCKER_APP_HOST_STORAGE_PATH}:/var/www/storage"
    healthcheck:
      test: gosu www-data php artisan horizon:status | grep running
      interval: "${DOCKER_WORKER_HEALTHCHECK_INTERVAL:?error}"
      timeout: 5s
      retries: 2

 

• Navigate to the directory you set for the pixelfed "appdata" and create a .env file. Paste the following into the file

 

################################################################################
# app
################################################################################
APP_NAME=pixelfed
APP_DOMAIN="PIXELFED.DOMAIN"
APP_URL="https://${APP_DOMAIN}"
ADMIN_DOMAIN="${APP_DOMAIN}"
ENABLE_CONFIG_CACHE="true"
OPEN_REGISTRATION="false"
ENFORCE_EMAIL_VERIFICATION="true"
OAUTH_ENABLED="true"
# ! Do not edit your timezone once the service is running - or things will break!
APP_TIMEZONE="UTC"
MAX_ALBUM_LENGTH="4"
INSTANCE_CONTACT_EMAIL="CONTACT@EMAIL"
CACHE_DRIVER="redis"
BROADCAST_DRIVER="redis"
################################################################################
# database
################################################################################
DB_VERSION="11.2"
DB_CONNECTION="mysql"
DB_HOST="MARIADBCONTAINERADDRESS"
DB_USERNAME="DBUSERNAME"
DB_PASSWORD='DBPASSWORD'
DB_DATABASE="DATABASENAME"
DB_PORT="3306"
# ! Automatically force database migration when migration is detected !
DB_APPLY_NEW_MIGRATIONS_AUTOMATICALLY="false"
################################################################################
# mail
################################################################################
#MAIL_DRIVER="smtp"
#MAIL_HOST="smtp.mailgun.org"
#MAIL_PORT="587"
#MAIL_FROM_ADDRESS="__CHANGE_ME__"
#MAIL_FROM_NAME="${APP_NAME}"
#MAIL_USERNAME=""
#MAIL_PASSWORD=""
#MAIL_ENCRYPTION="tls"
################################################################################
# redis
################################################################################
REDIS_CLIENT="phpredis"
REDIS_SCHEME="tcp"
REDIS_HOST="REDISHOST"
REDIS_PORT="REDISPORT"
################################################################################
# experiments
################################################################################
#EXP_TOP="true"
#EXP_POLLS="true"
#EXP_CPT="false"
#EXP_EMC="true"
################################################################################
# ActivityPub
################################################################################
ACTIVITY_PUB="true"
AP_REMOTE_FOLLOW="true"
AP_SHAREDINBOX="true"
AP_INBOX="true"
AP_OUTBOX="true"
################################################################################
# Federation
################################################################################
ATOM_FEEDS="true"
NODEINFO="true"
WEBFINGER="true"
################################################################################
# logging
################################################################################
LOG_CHANNEL="stderr"
################################################################################
# queue
################################################################################
QUEUE_DRIVER="redis"
################################################################################
# session
################################################################################
SESSION_DRIVER="redis"
################################################################################
# docker shared
################################################################################

# !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
# ! NOTE: do not fill APP_KEY. this will be auto-generated by Docker during bootstrap
# !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
APP_KEY=""
DOCKER_ALL_CONTAINER_NAME_PREFIX="${APP_NAME}"
DOCKER_ALL_DEFAULT_HEALTHCHECK_INTERVAL="10s"
DOCKER_ALL_HOST_ROOT_PATH="./docker-compose-state"
DOCKER_ALL_HOST_DATA_ROOT_PATH="${DOCKER_ALL_HOST_ROOT_PATH:?error}/data"
DOCKER_ALL_HOST_CONFIG_ROOT_PATH="${DOCKER_ALL_HOST_ROOT_PATH:?error}/config"
DOCKER_APP_HOST_OVERRIDES_PATH="${DOCKER_ALL_HOST_ROOT_PATH:?error}/overrides"
# Set timezone used by *all* containers - these must be in sync.
# ! Do not edit your timezone once the service is running - or things will break!
TZ="${APP_TIMEZONE}"
################################################################################
# docker app
################################################################################
DOCKER_APP_RELEASE="latest"
DOCKER_APP_PHP_VERSION="8.4"
DOCKER_APP_RUNTIME="nginx"
DOCKER_APP_DEBIAN_RELEASE="bookworm"
DOCKER_APP_BASE_TYPE="fpm"
DOCKER_APP_IMAGE="ghcr.io/pixelfed-glitch/pixelfed"
DOCKER_APP_TAG="${DOCKER_APP_RUNTIME:?error}-${DOCKER_APP_RELEASE:?error}"
DOCKER_APP_HOST_STORAGE_PATH="${DOCKER_ALL_HOST_DATA_ROOT_PATH:?error}/pixelfed/storage"
DOCKER_APP_HOST_CACHE_PATH="${DOCKER_ALL_HOST_DATA_ROOT_PATH:?error}/pixelfed/cache"
################################################################################
# docker web
################################################################################
DOCKER_WEB_PORT_EXTERNAL_HTTP="8080"
DOCKER_WEB_HEALTHCHECK_INTERVAL="${DOCKER_ALL_DEFAULT_HEALTHCHECK_INTERVAL:?error}"
################################################################################
# docker worker
################################################################################
DOCKER_WORKER_HEALTHCHECK_INTERVAL="${DOCKER_ALL_DEFAULT_HEALTHCHECK_INTERVAL:?error}"

 

• Modify the .env file to suit the needs of your instance. Note that the Domain and Timezone cannot be changed after the instance is started. more info about the env flags that can be set and what they do can be found at https://github.com/pixelfed-glitch/pixelfed/blob/develop/.env.docker

 

• In the docker tab of unraid click the new "compose up" button to this will download and start the docker containers from the murazaki/pixelfed:edge-apache repository.

 

-------------------------------------------------------

pixelfed instance setup

-------------------------------------------------------

The Following should set up the instance now that the containers are running.

 

• In the docker tab of the unraid UI click on the new pixelfed-web container and click ">_ console" this will open a new window that contains a console shell of the docker container

• Paste "php artisan key:generate" into the console window and press enter. This will generate an appkey and insert it into your .env file

• in the Unraid docker tab click the "Compose Down" key to the right of your pixelfed stack then, when that is complete, "compose up". This will restart your containers

• Enter the Console for pixelfed-web again and paste "php artisan config:cache" this will cache the settings in you .env to pixelfed. If you make changes to your .env file run "php artisan cache:clear" then "php artisan config:cache" to clear the old and cache the new settings

• In the console paste "php artisan migrate" and press enter. You will be asked of you want to proceed. Arrow left and press enter to select "yes" This will set up your database

• When this is complete compose down then up again to restart the containers

• Enter the Console again and paste "php artisan user:create". Follow the prompts to create your first admin account. Email account is used for login so please use a valid email address format

 

-------------------------------------------------------

reverse proxy setup (swag)

-------------------------------------------------------

• Navigate to the proxy-conf directory of your swag appdata and edit the pixelfed.subdomain.conf.sample file to match the following config with the upsteam app and upstream port edited to match your setup

 

server {
    listen 443 ssl http2;
    listen [::]:443 ssl http2;

    server_name pixelfed.*;

    include /config/nginx/ssl.conf;

    client_max_body_size 0;


    location / {

        include /config/nginx/proxy.conf;
        include /config/nginx/resolver.conf;
        set $upstream_app PIXELFED-LOCAL_ADDRESS;
        set $upstream_port PIXELFED-WEBPORT;
        set $upstream_proto http;
        proxy_pass $upstream_proto://$upstream_app:$upstream_port;
    }
}

 

-------------------------------------------------------

DNS and Beyons

-------------------------------------------------------

At this point you should have a working pixelfed instance with a reverse proxy. What is left is to create a CNAME dns record. There are likely guides for how to do this for your DNS provider. If you are using cloudflare my understanding is that you will have to disable the cloudflare proxy for activity pub federation to work properly

 

On the subject of federation if you would like to enable activity pub federation enter the pixelfed-web console again and run "php artisan instance:actor"

 

After updates you may need to run "php artisan migrate" I haven't had to update yet so I haven't tested this.

 

There are many settings that can be changed or added via the .env file. The one I posed is trimmed down to make it clearer and easier to follow. You can check out the full .env file at the Pixelfed Github repo in the .env.docker file

 

----------------------------------------------------------------------------------------------------------------------------------------------------

 

Hopefully by now you have a working instance that can be reached from outside of your network. I am sure there are better or more efficient ways to do but, this suits my needs for a small instance for a few friends and myself to use. Please understant that I am an amateur and am new to server/system administration so I cannot guarantee that this is secure enough for production use. Please review these methods along with the pixelfed official documentation before decideding if this is right for you and your user's security

Edited February 9, 20251 yr by tekolote
corrected docker

I'm a bit surprised to see no responses or feedback to this article so far. It's great! Helped me setup an instance step by step. Only difference for me was that I use NGINX Proxy Manager instead of SWAG which is pretty much just personal preference.

Am I the only one finding an error with DOCKER_WORKER_HEALTHCHECK_INTERVAL? 

 

Quote

error while interpolating worker.healthcheck.interval: required variable DOCKER_WORKER_HEALTHCHECK_INTERVAL is missing a value: error

 

 

Edited January 23, 20251 yr by felipes

Apologies. It looks like somehow I dropped a few lines off of the bottom of the .env file while writing the guide. try adding

################################################################################
# docker worker
################################################################################

# Set this to a non-empty value (e.g. "disabled") to disable the [worker] service
#DOCKER_WORKER_PROFILE=""

# How often Docker health check should run for [worker] service
# @dottie/validate required
DOCKER_WORKER_HEALTHCHECK_INTERVAL="${DOCKER_ALL_DEFAULT_HEALTHCHECK_INTERVAL:?error}"

to the bottom of the .env file to add the variable "DOCKER_WORKER_HEALTHCHECK_INTERVAL" is looking for. I'll have to take another look at this guide over the weekend. It's probably due for an update

I have updated the compose and env file in the original post. It was pulling a specific image from a repository. That made it difficult to update since the the env file needed to be manually edited to point to the updated app image for each update. It should now pull the latest image from pixelfed-glitch which should make it easier to update. I have also added the docker worker files that I mistakenly left out so with luck it should run without the worker healthcheck errors

When I try and start this up I'm getting an error because the web container is trying to change the ownership of the .env file and is failing.  This is causing the container to loop on restart.  I've tried setting RUNTIME_UID and RUNTIME_GID to 99 and 100 respectively, but then I just get an error that 99 user does not exist.

@binarymelon I am traveling for the rest of the week so I may be slow to respond. if you navigate to the directory the .env file is in, can you run

ls

ls -la

and check the file permissions on the .env file. Or if you have the unraid file manager can you navigate to the file there and show the permissions and owner of the file. I wonder if the the .env file is not readable when the container and causing issues. If the .env was created outside of unraid then it's possible it has permissions from the user that created the file rather than the "root" user that unraid is expecting to own it

On 1/25/2025 at 11:59 AM, tekolote said:

I have updated the compose and env file in the original post. It was pulling a specific image from a repository. That made it difficult to update since the the env file needed to be manually edited to point to the updated app image for each update. It should now pull the latest image from pixelfed-glitch which should make it easier to update. I have also added the docker worker files that I mistakenly left out so with luck it should run without the worker healthcheck errors

I was able to start the containers using the updated compose and env (modified to my instance) of your post. 

 

However, when trying to do the first step after composing up (the php artisan key:generate command at the pixelfed-web prompt) I get a "Unable to set application key. No APP_KEY variable was found in the .env file." error. And, yes, I've checked and the env file does have the line "APP_KEY="APPKEY"".

@felipes I don't think it is causing the issue but could you remove the "APPKEY" value in that line in the .env to leave it as empty quotes before running the containers and trying the command. and is there any more to that error that message that could help narrow it down? I wonder if it's not able to find the .env file when trying to generate the key

Thanks a lot for this guide @tekolote.

 

I don't know if it's a change with Unraid 7.0.0 or new docker version but I needed to add "network_mode: bridge" in docker-compose for service "web" and "worker" to allow Pixelfed container to communicate with mariadb/mysql and redis container. Without this command, a pixelfed network is created and it can't communicate with the standard bridge network for Unraid's container apps.

 

I hope this information will be useful to those who might be stuck despite this guide.

If like me after the setup of your Pixelfed instance you want to import data from your Instagram account, there is a bug with the version 0.12.4 of PixelFed. 😭

After the import of your Instagram's data zip file and the selection of images you want to import, the import queue may be stuck.

 

It's possible to fix the problem with the following commands in the console of the web container :

php artisan app:transform-imports
chown -R www-data:www-data /var/www/public/storage/m/_v2/

The first command force the import and the second command fix the rights problem that made the imported pics not visible.

I had to remove these lines from the compose file:

 

```

# Used by [proxy] service

LETSENCRYPT_HOST: "${DOCKER_PROXY_LETSENCRYPT_HOST:?error}"

LETSENCRYPT_EMAIL: "${DOCKER_PROXY_LETSENCRYPT_EMAIL:?error}"

LETSENCRYPT_TEST: "${DOCKER_PROXY_LETSENCRYPT_TEST:-}"

```

 

Then it started to work, after forgetting to set the TCP port to something other than 8080.

 

Not sure why it wants to concern itself with Let's Encrypt, because that is indeed up to the proxy service, which isn't included in the stack. And probably for good reason: if you have a proxy, you would want it separately, which I have. So all's good, but maybe remove those lines from the instructions as well.

 

Secondly, I was mystified about the APP_TIMEZONE variable. It is not mentioned on the pixelfed documentation, and it's unclear what format is expected. I just willy-nilly put in "Europe/Amsterdam" and so far it doesn't error out.

 

So then the stack was able to start.

 

After starting, you instruct:

 

> In the docker tab of the unraid UI click on the new pixelfed-web container and click ">_ console" this will open a new window that contains a console shell of the docker container

 

But that part isn't working. For BOTH the web and worker dockers, BOTH the console and log open a split second and then close. The status on the right says "Restarting (127): 47 seconds ago" for both, even minutes after creating, so I guess something is wrong, but without a console or log, I have no way of knowing what. It doesn't seem to drop a logfile in the appdata directory either, so I'm hoping your guess is *not* as good as mine, but better

Oh here we go, the compose UI also has logs. It says this error for BOTH dockers:

```

pixelfed-web     | 2025-03-27 14:00:15 +00:00 - [entrypoint / entrypoint.sh] - ============================================================
pixelfed-web     | 2025-03-27 14:00:15 +00:00 - [entrypoint / entrypoint.sh] - Executing [/docker/entrypoint.d/02-check-config.sh]
pixelfed-web     | 2025-03-27 14:00:15 +00:00 - [entrypoint / entrypoint.sh] - ============================================================
pixelfed-web     | 2025-03-27 14:00:15 +00:00 - [entrypoint / 02-check-config.sh] - 👷 Running [dottie validate --file /var/www/.env --ignore-rule dir,file --exclude-prefix APP_KEY --no-fix] as [root]
) - parseCompleteAssign 13-27 14:00:15 +00:00 - [entrypoint / 02-check-config.sh] - (stderr) Error: failed to load file: unexpected token at line 5: SPACE(
pixelfed-web     | 2025-03-27 14:00:15 +00:00 - [entrypoint / 02-check-config.sh] - (stderr) Run 'dottie validate --help' for usage.
pixelfed-web     | 2025-03-27 14:00:15 +00:00 - [entrypoint / 02-check-config.sh] - ERROR - ❌ Error!
pixelfed-web     | 2025-03-27 14:00:15 +00:00 - [entrypoint / entrypoint.sh] - ============================================================
pixelfed-web     | 2025-03-27 14:00:15 +00:00 - [entrypoint / entrypoint.sh] - Sourcing [/docker/entrypoint.d/04-defaults.envsh]
pixelfed-web     | 2025-03-27 14:00:15 +00:00 - [entrypoint / entrypoint.sh] - ============================================================
pixelfed-web     | 2025-03-27 14:00:15 +00:00 - [entrypoint / 04-defaults.envsh] - Sourcing /var/www/.env
pixelfed-web     | /var/www/.env: line 84: $'\r': command not found
pixelfed-web     | /docker/helpers.sh: line 254: pop_var_context: head of shell_variables not a function context
pixelfed-web     | /docker/entrypoint.d/04-defaults.envsh: line 13: pop_var_context: head of shell_variables not a function context

```

 

I don't know what it means by `SPACE(` on line 5. That's where the domain name is. There are no spaces.

 

Then it also complains about line 84, which is an empty line, just like in the instructions 🤨

Edited March 27, 20251 yr by thany

If I remove that empty line, I see in the logs a lot of git diffs flying about, first of all. I wonder how that happens. Why does a docker need to concern itself with anything git? And then also why would it need to show diffs?... This is really confusing, and without any explanation about it.

 

After all those diffs, it's erroring out again though.

 

(see attachment - unraid forums has decided to mess up the formatting)

 

Something about a cache path, it looks like. No idea what it's on about. Can't the dockerfile/config just use whatever cache path is appropriate without us users having to supply one manually? Or something else is broken?

logs.txt

Edited March 27, 20251 yr by thany

FYI, if you set up 2FA with personal access tokens on hub.docker.com:

• Go to https://hub.docker.com/settings/security and generate a PAT
   
• Run

  echo -n 'johndoe:ghp_ABC1234567890' | base64

• Replace the "auth" string in your config.json with the new one.
  The file should be in ~/.docker/config.json
  The .docker folder should be a symlink pointing to /boot/config/plugins/dockerMan/

{
    "auths": {
        "https://index.docker.io/v1/": {
            "auth": "am9obmRvZTpnaHBfQUJDMTIzNDU2Nzg5MA=="
        }
    }
}