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